useMaterial3 property

A temporary flag used to opt-in to Material 3 features.

If true, then widgets that have been migrated to Material 3 will use new colors, typography and other features of Material 3. If false, they will use the Material 2 look and feel.

During the migration to Material 3, turning this on may yield inconsistent look and feel in your app as some widgets are migrated while others have yet to be.

Defaults to false. When the Material 3 specification is complete and all widgets are migrated on stable, we will change this flag to be true by default. After that change has landed on stable, we will deprecate this flag and remove all uses of it. At that point, the material library will aim to only support Material 3.

Defaults

If a ThemeData is constructed with useMaterial3 set to true, then some properties will get updated defaults. However, the ThemeData.copyWith method with useMaterial3 set to true will not change any of these properties in the resulting ThemeData.

* if the target platform is Android and the app is not running on the web, otherwise it will fallback to InkRipple.

If brightness is Brightness.dark then the default color scheme will be either the M3 baseline dark color scheme or the M2 baseline dark color scheme depending on useMaterial3.

Affected widgets

This flag affects styles and components.

Styles

• Color: ColorScheme, Material (see table above)
• Shape: (see components below)
• Typography: Typography (see table above)

Components

* new means the new widgets/methods created since the last stable release.

• Badges: Badge
• Bottom app bar: BottomAppBar
• Bottom sheets: BottomSheet
• Buttons
  • Common buttons: ElevatedButton, FilledButton, FilledButton.tonal, OutlinedButton, TextButton
  • FAB: FloatingActionButton, FloatingActionButton.extended
  • Icon buttons: IconButton, IconButton.filled (new), IconButton.filledTonal (new), IconButton.outlined (new)
  • Segmented buttons: SegmentedButton (replacing ToggleButtons)
• Cards: Card
• Checkbox: Checkbox, CheckboxListTile
• Chips:
  • ActionChip (used for Assist and Suggestion chips),
  • FilterChip, ChoiceChip (used for single selection filter chips),
  • InputChip
• Date pickers: showDatePicker, showDateRangePicker, DatePickerDialog, DateRangePickerDialog, InputDatePickerFormField
• Dialogs: AlertDialog, Dialog.fullscreen
• Divider: Divider, VerticalDivider
• Lists: ListTile
• Menus: MenuAnchor, DropdownMenu, MenuBar
• Navigation bar: NavigationBar (replacing BottomNavigationBar)
• Navigation drawer: NavigationDrawer (replacing Drawer)
• Navigation rail: NavigationRail
• Progress indicators: CircularProgressIndicator, LinearProgressIndicator
• Radio button: Radio, RadioListTile
• Search: SearchBar (new), SearchAnchor (new),
• Snack bar: SnackBar
• Slider: Slider, RangeSlider
• Switch: Switch, SwitchListTile
• Tabs: TabBar, TabBar.secondary (new)
• TextFields: TextField together with its InputDecoration
• Time pickers: showTimePicker, TimePickerDialog
• Top app bar: AppBar, SliverAppBar, SliverAppBar.medium, SliverAppBar.large

In addition, this flag enables features introduced in Android 12.

• Stretch overscroll: MaterialScrollBehavior
• Ripple: splashFactory (see table above)

See also:

• Material 3 specification.