Migrating a Flutter app to Materials 3

This put up is written by Taha Tesser

At Google I/O 2021, Google introduced the subsequent evolution of Materials Design, Materials You, together with Android 12. The Materials Design system’s greatest overhaul but introduced redesigned parts, new colours, a variety of shapes, simplified typography, new elevation, higher accessibility, and lots of different tweaks. With this replace, Flutter apps can have a constant design throughout a number of platforms. Materials Design 3 (the technical identify for Materials You) is typically known as Materials 3 or just M3 for the sake of brevity, equally to how Materials 2 is known as M2.

On this article, we are going to talk about every thing that you just, as a Flutter developer, ought to learn about migrating your Flutter app to Materials 3.

How one can allow Materials 3 in Flutter

For the reason that announcement of Materials 3, Flutter has obtained a bunch of updates to help it, together with help for brand new typography, shapes, elevation, up to date widgets, and new M3 widgets. A lot of the M3 parts can be found in Flutter. You possibly can monitor the few remaining widgets which can be but to obtain Materials 3 help and the progress of the Materials 3 implementations in Flutter for them within the Convey Materials 3 to Flutter concern.

At the moment, Materials 3 modifications are solely accessible when opting in, so that you’ll want to make use of the useMaterial3 flag on ThemeData to allow Materials 3 help. (This may change sooner or later, so be sure you try the Flutter web site for up to date documentation. We’ll additionally replace this text quickly after the change takes place.)

To make use of Materials 3 in Flutter as a substitute of Materials 2, specify the next:

theme: ThemeData(
  useMaterial3: true,

What’s new in Materials Design 3 for Flutter?

Materials 3 updates introduced revamped typography, an improved ColorScheme (together with the flexibility to generate a full ColorScheme from a given seed coloration), up to date elevation, a ravishing Android 12 overscroll stretch impact, and a brand new ink ripple. A bunch of Materials widgets, reminiscent of AppBar, FloatingActionButton (FAB), ElevatedButton, OutlinedButton, IconButton, and Card, have been up to date to help Materials 3 design. There are additionally new Materials 3 widgets, reminiscent of NavigationBar, NavigationDrawer, andSegmentedButton, some new M3-style buttons, reminiscent of FilledButton and FilledButton.tonal, and a complete lot extra.

In case you merely migrate the Flutter starter app to Materials 3, you’ll already discover some modifications: The AppBar has no elevation or background coloration, and the FAB has a rounded rectangular form as a substitute of the extra acquainted round form.

For a whole overview of M3 in Flutter, try the official Materials 3 Demo.

Within the following sections, I’ll clarify a few of the key modifications and tweaks you may need to make in your app to help Materials 3.

The key modifications in Materials 3 are:

  • Dynamic coloration
  • Typography
  • Shapes
  • Elevation

Let’s undergo every of them intimately.

Dynamic coloration

Let’s begin with Dynamic coloration, which allows you to apply constant colours throughout your app. It comprises some key colours and impartial colours associated to separate tonal palettes. Colours from these tonal palettes are utilized throughout the UI. Use the Materials Theme Builder internet app or the Figma plugin to visualise the dynamic coloration on your app and create a customized coloration scheme.

Flutter makes use of a low-level material_color_utilities package deal that comprises algorithms to create a Materials Design 3 coloration system. You possibly can create coloration schemes on your apps utilizing dynamic_color based mostly on a platform’s implementation of dynamic coloration.

The simplest option to create an M3 ColorScheme is by offering a seedColor coloration within the app’s theme.

For example, add colorSchemeSeed: Colours.inexperienced to the starter app. Discover that the FAB is now utilizing a lighter inexperienced coloration as a substitute of the sunshine purple from the default coloration scheme.

Including colorSchemeSeed when primarySwatch is current will throw assertion :
'package deal:flutter/src/materials/theme_data.dart': Failed assertion: line 477 pos 12: 'colorSchemeSeed == null || primarySwatch == null': isn't true.

To repair this, take away primarySwatch: Colours.blue, from the starter app’s theme.

	primarySwatch: Colours.blue,
  useMaterial3: true,
  colorSchemeSeed: Colours.inexperienced,

Right here, I’ve created an instance that reveals all the colours from the M3 ColorScheme. On the left, we have now the default ColorScheme, which is out there when setting the useMaterial flag to true. And on the suitable, we’re utilizing the customized ColorScheme, generated utilizing the colorSchemeSeed parameter, which takes a seed coloration or key coloration to generate a full Materials 3 ColorScheme.

Default M3 ColorScheme Customized M3 ColorScheme

You possibly can take this to the subsequent stage utilizing each flex_seed_scheme, which lets you create a extra versatile model of Flutter’s ColorScheme.fromSeed, and flex_color_scheme, which ensures UI parts get themed utterly by the colour schemes and customized colours you present.


Materials 3 simplified the typography naming by splitting the typescales into 5 key teams:

  • Show
  • Headline
  • Title
  • Physique
  • Label

The function of every key group is extra descriptive, and it’s a lot simpler to make use of completely different sizes in a selected typography group, e.g., BodyLarge, BodyMedium, and BodySmall as a substitute of bodyText1, bodyText2, and caption. This helps when implementing typography for units with completely different display sizes.

The scaling of the typography has turn into constant throughout the teams. Here’s a comparability between the M3 and M2 typescales:


In Materials 2, every elevated element will get a shadow. The upper the elevation, the larger the shadow. Going even additional, Materials 3 introduces a brand new surfaceTintColor coloration property. When utilized to elevated parts, the floor of the elevated parts will get this coloration, and its depth depends upon the elevation worth.

Supply: https://m3.materials.io/types/elevation/overview

The surfaceTintColor property is added to all of the elevated widgets in Flutter, together with the elevation and shadow properties.

Check out this Materials elevation demo: Flip off shadows by tapping on the icon button within the prime proper and change between M2 and M3. Discover that elevated surfaces tackle the surfaceTintColor coloration, which makes them seen even when no shadow is offered.

When evaluating the M2 AppBar with the M3 AppBar within the starter app, you’ll discover that the AppBar doesn’t have a default elevation worth, surfaceTintColor coloration, or shadow coloration.

M2 AppBar M3 AppBar

Offering a customized elevation worth reveals the default surfaceTintColor coloration in impact and applies the theme’s shadow coloration to the AppBar in order that the AppBar casts a shadow as effectively.

Observe: This AppBar.elevation property is completely different from the brand new AppBar.scrolledUnderElevation property, which is barely in impact when the content material is scrolled beneath the AppBar. Study extra about this additional under.

  appBar: AppBar(
    title: Textual content(widget.title),
    elevation: 4,

  appBar: AppBar(
    title: Textual content(widget.title),
    elevation: 4,
    shadowColor: Theme.of(context).shadowColor,


Materials 3 presents a wider vary of shapes, together with squared, rounded, and rounded rectangular shapes. The FAB, which was beforehand circled, now has a rounded rectangular form, and materials buttons went from rounded rectangular to tablet formed. Widgets like Card, Dialog, and BottomSheet are additionally extra rounded in M3.

Migrating from Materials 2 to Materials 3

Right here, I’ll stroll you thru the method of migrating a Materials 2 demo app to Materials 3.

This demo app comprises some Materials 2 Flutter widgets. A few of them might be up to date when enabling M3, and a few of the M2 widgets may be changed with new M3-style widgets. For instance, ElevatedButton may be changed with the brand new FilledButton to protect the visible design, and BottomNavigationBar may be changed with the brand new M3-style NavigationBar widget. The demo app additionally comprises some customization wanted in an M2 app for some widgets to stack effectively. For example, InputDecorationTheme applies a customized fillColor in order that the TextField is seen when positioned within the AppBar in an M2 app.

  theme: ThemeData(
    colorScheme: const ColorScheme.mild().copyWith(
      major: Colours.inexperienced[700],
      secondary: Colours.inexperienced[700],
    inputDecorationTheme: InputDecorationTheme(
      stuffed: true,
      fillColor: Theme.of(context).colorScheme.onPrimary,
      hintStyle: TextStyle(
        coloration: Colours.inexperienced[700],
    floatingActionButtonTheme: const FloatingActionButtonThemeData(
      foregroundColor: Colours.white,

Among the best issues about Materials 3 is that widgets use constant colours, and the general theming expertise has additionally been improved. For instance, within the demo, we used a customized InputDecorationTheme to make the TextField seen in the dead of night inexperienced AppBar. However when migrating to M3, we will take away this, and the TextField might be seen with none customization.

Within the demo, take away the prevailing colorScheme property, inputDecorationTheme, and floatingActionButtonTheme. Then add the next traces:

	theme: ThemeData(
    useMaterial3: true,
    colorSchemeSeed: Colours.inexperienced[700]

We now have a brand new stunning ColorScheme that’s utilized to all of the parts within the demo app. Every UI element is utilizing particular tonal palette colours. TextField makes use of an applicable fillColor, and playing cards have the default greenish surfaceTintColor.

IconButton now helps the ButtonStyle property, which you should utilize to customise the IconButton to get an M3 visible and a brand new chosen state. Let’s replace the IconButton from the AppBar within the demo app to an M3 filled-style icon button.

Take a look at https://api.flutter.dev/flutter/materials/IconButton-class.html and https://m3.materials.io/parts/icon-buttons/overview to study extra.

Right here’s my favourite half: If you scroll via the content material, the AppBar’s default scrollUnderElevation kicks in. Discover that the surfaceTintColor intensified once we’re scrolling, and in consequence, the AppBar modifications coloration. It is because the AppBar is elevated based mostly on the scrollUnderElevation worth when the content material is scrolled beneath. Record views ship scroll notifications to the AppBar that they’re being scrolled beneath.

You possibly can implement AppBar.notificationPredicate and hearken to scroll notifications from a nested record view for extra advanced layouts.

The Materials 3 AppBar is elevated when content material is scrolled beneath the AppBar. You possibly can alter this elevation utilizing the brand new scrolledUnderElevation property.

Take a look at the official scrolledUnderElevation code pattern I’ve added within the AppBar docs.

Execute flutter create --sample=materials.AppBar.2 mysample to create an area venture with this code pattern.

The migration course of for our demo app isn’t full but. It nonetheless makes use of the M2-style BottomNavigationBar, so let’s substitute it with the brand new M3-style NavigationBar widget. It’s taller and simpler to work together with, and it isn’t elevated.

M2-style BottomNavigationBar M3-style NavigationBar

Take a look at the documentation for the NavigationBar class for extra particulars.

Tapping on the FAB on the house display opens a dialog with a rounded rectangular form. For the reason that dialog is elevated by default, we will see that the default surfaceTintColor has been utilized and the content material padding has been barely modified, because it has an non-compulsory icon property.

Take a look at the documentation for the showDialog operate for extra particulars.

Now, navigate to the main points web page by tapping on one of many record gadgets. This web page comprises a SliverAppBar with expandedHeight and flexibleSpace to make the app bar title giant and the SliverAppBar collapsable. This may be changed with the brand new SliverAppBar.giant, which helps giant titles and can be collapsable. When doing so, we will take away expandedHeight and flexibleSpace.

    title: const Textual content('Lorem Ipsum'),

For the brand new M3 AppBar variants, which help medium and huge titles, use the brand new SliverAppBar.medium and SliverAppBar.giant.

Take a look at the documentation for the SilverAppBar.medium constructor and SilverAppBar.giant constructor for extra particulars.

Listed below are the screenshots of the ultimate M3 demo.

The supply code for all of the demos is out there on GitHub.


Materials 3 makes it attainable to create stunning, personalised, and accessible designs. When combining Materials 3 with Flutter, you may create a constant and unified UI expertise throughout cell, internet, and desktop platforms. It makes it a lot simpler to create advanced algorithmic coloration schemes and scale typography for units with various display sizes. Moreover, accessibility has been improved, and visible suggestions is clearer.

The Flutter crew has been working onerous on including full help for Materials 3 to Flutter. As demonstrated above, you may already migrate your current Materials 2 app to Materials 3. In case you use some widgets which can be but to obtain Materials 3 help, you may monitor their progress within the Materials 3 concern.

Taha Tesser is likely one of the prime Flutter contributors. His major focus is fixing points and including new options to Materials Design and Cupertino Design within the framework. He has additionally added and up to date dozens of official examples and documentation pages. You possibly can attain out to him on Twitter and comply with him on GitHub.

Related Articles


Please enter your comment!
Please enter your name here

Latest Articles