Android Theme Configuration

No theme setup is required to avoid a crash. React Native and Expo templates ship an AppCompat app theme, and every component works with it. When the theme is not a Material theme, SegmentedControl, Button, ButtonGroup, FloatingToolbar and the inline M3 SelectionMenu render with Material 3 default colors, the M3 date and time pickers use a built-in Material 3 dialog theme, and the library logs one warning under the PlatformComponents tag. Give the app a Material 3 theme to have those components use your app's colors instead.

Two different android.material props exist, because they answer different questions:

DatePicker and SelectionMenu: 'system' (the platform widget, the default) or 'm3' (the Material one).
SegmentedControl, Button and ButtonGroup: 'expressive' (Material 3 Expressive, the default) or 'm3' (classic Material 3). These are always Material widgets; the choice is the design generation. FloatingToolbar only exists in Expressive.

The Expressive styles are applied as a theme overlay over your app theme, so your colors (and useNativeTheme) apply to both generations.

Releases before 1.0.0 crashed on mount in these cases (Cannot find theme attribute materialButtonOutlinedStyle, You need to use a Theme.AppCompat theme). Upgrade to get the fallback behavior.

Theme Requirements by Component

Component	Mode	Uses your colors with	Without it
SegmentedControl	(always Material; `android.material: 'expressive'` or `'m3'`)	`Theme.Material3.*`	Material 3 default colors, one warning logged
Button, ButtonGroup	(always Material; `android.material: 'expressive'` or `'m3'`)	`Theme.Material3.*`	Material 3 default colors, one warning logged
FloatingToolbar	(always Material 3 Expressive)	`Theme.Material3.*`	Material 3 default colors, one warning logged
DatePicker	`android.material: 'm3'`	`Theme.Material3.*`	Built-in Material 3 dialog theme, one warning logged
DatePicker	`android.material: 'system'`	`Theme.AppCompat.*`	Built-in AppCompat dialog theme, one warning logged
SelectionMenu	`android.material: 'm3'`	`Theme.Material3.*`	Material 3 default colors, one warning logged
SelectionMenu	`android.material: 'system'`	`Theme.AppCompat.*`	Platform widgets, no theme dependency
ContextMenu	—	Any	—
LiquidGlass	—	Any	—

Theme.Material3.* extends Theme.AppCompat.*, so a Material 3 theme satisfies every row.

To use your brand color without editing styles.xml, set it from JavaScript with useNativeTheme (Android 13 and later). See Brand color.

Material 3 Theme Setup (Recommended)

Expo: pass { "android": { "theme": "material3" } } to the config plugin. See Expo Configuration below.

Bare React Native: change the parent of your app theme in android/app/src/main/res/values/styles.xml:

<resources>
    <style name="AppTheme" parent="Theme.Material3.DayNight.NoActionBar">
        <!-- Keep the items the React Native template put here -->
        <item name="android:editTextBackground">@drawable/rn_edit_text_material</item>
    </style>
</resources>

Material 3 supplies a complete default color scheme. To use your own, override the colors you care about in the same style:

<item name="colorPrimary">@color/md_theme_primary</item>
<item name="colorOnPrimary">@color/md_theme_onPrimary</item>
<item name="colorPrimaryContainer">@color/md_theme_primaryContainer</item>
<item name="colorOnPrimaryContainer">@color/md_theme_onPrimaryContainer</item>
<item name="colorSecondaryContainer">@color/md_theme_secondaryContainer</item>
<item name="colorOnSecondaryContainer">@color/md_theme_onSecondaryContainer</item>
<item name="colorSurface">@color/md_theme_surface</item>
<item name="colorOnSurface">@color/md_theme_onSurface</item>

Tip: Use Google's Material Theme Builder to generate a complete color scheme, and define the colors in res/values/colors.xml.

Mode Selection Guide

Choose the mode that matches your app's theme:

// If your app uses Theme.Material3.* (recommended)
<DatePicker android={{ material: 'm3' }} />
<SelectionMenu android={{ material: 'm3' }} />
<SegmentedControl /> // Material 3 Expressive; android={{ material: 'm3' }} for classic
<Button label="Save" /> // Material 3 Expressive; android={{ material: 'm3' }} for classic

// If your app uses Theme.AppCompat.* (the React Native default)
<DatePicker android={{ material: 'system' }} />
<SelectionMenu android={{ material: 'system' }} />
<SegmentedControl /> // Renders with Material 3 default colors
<Button label="Save" /> // Renders with Material 3 default colors

Expo Configuration

For Expo projects, the config plugin configures the theme for you. With android.theme set to material3, npx expo prebuild re-parents the generated AppTheme onto Theme.Material3.DayNight.NoActionBar and keeps every item Expo already put there (colorPrimary, status bar colors, and so on). Material 3 supplies the remaining colors, so you only add the ones you want to override. Add to app.json:

{
  "expo": {
    "plugins": [
      [
        "react-native-platform-components/app.plugin",
        {
          "android": {
            "theme": "material3"
          }
        }
      ]
    ]
  }
}

Then run npx expo prebuild to apply the configuration. Leave the option out (or set it to appcompat) to keep Expo's default AppCompat theme.

Theme Requirements by Component​

Material 3 Theme Setup (Recommended)​

Mode Selection Guide​

Expo Configuration​

Theme Requirements by Component

Material 3 Theme Setup (Recommended)

Mode Selection Guide

Expo Configuration