Docs
BlogChangelogStar us on GitHub
HomeGuidesEASReferenceLearn

Reference version

ArchiveExpo SnackDiscord and forumsNewsletter

This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 58).

Material Colors

Read the Material 3 color palette (including Material 3 Dynamic Colors) from JavaScript.

Android
Included in Expo Go

GitHub

npm

Changelog

Expo UI Jetpack Compose exposes the Material 3 color palette used by Jetpack Compose so you can pick a palette source and have every component under a <Host> theme from it consistently.

The palette source depends on the options you pass:

  • Wallpaper-derived: Default on Android 12+ when no seedColor is given. Uses Material 3 Dynamic Colors (Material You).
  • Static Material 3 baseline: Default fallback on Android 11 and below when no seedColor is given.
  • Seeded from a color: When you pass a seedColor, the full palette is derived using the same algorithm that Material 3 Dynamic Colors use for wallpaper-based colors. Works on every Android API level and is independent of the wallpaper.

Installation

Terminal
- npx expo install @expo/ui
- yarn expo install @expo/ui
- pnpm expo install @expo/ui
- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

Usage

Theming <Host> from a seed color

Host accepts seedColor and colorScheme props directly. This is the recommended way to theme a Compose subtree. Native Compose components under this Host render with the seeded palette and any descendant that calls useMaterialColors() without arguments receives the same palette from the Host's context.

BrandedHostExample.tsx
import { Button, Host, Text } from '@expo/ui/jetpack-compose';

export default function BrandedHostExample() {
  return (
    <Host seedColor="#8E24AA" colorScheme="dark" matchContents>
      <Button onClick={() => {}}>
        <Text>Themed from the seed</Text>
      </Button>
    </Host>
  );
}

Overriding palette roles

Use the colorOverrides prop on Host to set specific Material 3 roles. Host builds the palette from seedColor and colorScheme first. Then it replaces each role that you pass. The other roles keep their palette values. Compose components under the Host and useMaterialColors() both use the result.

import { Button, Host, Text } from '@expo/ui/jetpack-compose';

const colorOverrides = { primary: '#1E88E5FF' } as const;

export default function ColorOverridesExample() {
  return (
    <Host
      seedColor="#8E24AA"
      colorOverrides={colorOverrides}
      matchContents>
      <Button onClick={() => {}}>
        <Text>Blue primary, purple palette</Text>
      </Button>
    </Host>
  );
}

Reading the current palette inside Host

Call useMaterialColors() without arguments inside a <Host> to read the Host's current palette. The hook returns a reference-stable MaterialColors object and does not cross the native bridge on re-renders.

MaterialColorsExample.tsx
import {
  Column,
  Host,
  Surface,
  Text,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import { padding } from '@expo/ui/jetpack-compose/modifiers';

export default function MaterialColorsExample() {
  return (
    <Host style={{ flex: 1 }}>
      <Surface>
        <PaletteInspector />
      </Surface>
    </Host>
  );
}

function PaletteInspector() {
  const colors = useMaterialColors();
  return (
    <Column
      modifiers={[padding(16, 16, 16, 16)]}
      verticalArrangement={{ spacedBy: 8 }}>
      <Text>Primary: {colors.primary}</Text>
      <Text>Surface: {colors.surface}</Text>
    </Column>
  );
}

Computing a specific palette with arguments

Pass arguments to useMaterialColors() to compute a palette on demand, even outside a <Host>. The colorScheme takes 'light' or 'dark', you can omit it to follow the system.

UseMaterialColorsExample.tsx
import {
  Column,
  Host,
  Surface,
  Text,
  useMaterialColors,
} from '@expo/ui/jetpack-compose';
import { padding } from '@expo/ui/jetpack-compose/modifiers';

export default function UseMaterialColorsExample() {
  const dark = useMaterialColors({ colorScheme: 'dark' });
  const brand = useMaterialColors({ seedColor: '#8E24AA' });
  const brandedDark = useMaterialColors({
    colorScheme: 'dark',
    seedColor: '#8E24AA',
  });

  return (
    <Host style={{ flex: 1 }}>
      <Surface>
        <Column
          modifiers={[padding(16, 16, 16, 16)]}
          verticalArrangement={{ spacedBy: 8 }}>
          <Text>Dark primary: {dark.primary}</Text>
          <Text>Brand primary: {brand.primary}</Text>
          <Text>Branded dark primary: {brandedDark.primary}</Text>
        </Column>
      </Surface>
    </Host>
  );
}

Reading colors outside React components

GetMaterialColorsExample.tsx
import {
  getMaterialColors,
  isDynamicColorAvailable,
} from '@expo/ui/jetpack-compose';

const palette = getMaterialColors({ seedColor: '#8E24AA' });
console.log(
  'available:',
  isDynamicColorAvailable,
  'primary:',
  palette.primary
);

API

Constants

MaterialColors.isDynamicColorAvailable

Android

Type: boolean

Whether the current device supports Material You dynamic colors (Android 12+). When false, getMaterialColors and useMaterialColors return the static Material 3 baseline palette unless a seedColor is provided — seed-based palettes work on every Android API level.

Hooks

useMaterialColors(options)

Android
ParameterType
options(optional)UseMaterialColorsOptions

Returns the Material 3 color palette. Call with no arguments inside a <Host> to get the palette that <Host> is themed with. Pass scheme and/or seedColor to get a specific palette.

Returns:
MaterialColors

Methods

MaterialColors.getMaterialColors(options)

Android
ParameterType
options(optional)MaterialColorsOptions

Get the Material 3 color palette.

Returns:
MaterialColors

Types

MaterialColors

Android

Material 3 color palette exposed to TypeScript/JavaScript as #RRGGBBAA strings.

On Android 12+ devices these values are derived from the app user's wallpaper (Material You). On older devices they fall back to the static Material 3 baseline palette. Use isDynamicColorAvailable to distinguish the two at runtime.

PropertyTypeDescription
backgroundRgbaHex

The background color that appears behind scrollable content.

errorRgbaHex

The error color is used to indicate errors in components, such as invalid text in a text field.

errorContainerRgbaHex

The preferred tonal color of error containers.

inverseOnSurfaceRgbaHex

A color that contrasts well with inverseSurface. Useful for content that sits on top of containers that are inverseSurface.

inversePrimaryRgbaHex

Color to be used as a "primary" color in places where the inverse color scheme is needed, such as the button on a SnackBar.

inverseSurfaceRgbaHex

A color that contrasts sharply with surface. Useful for surfaces that sit on top of other surfaces with surface color.

onBackgroundRgbaHex

Color used for text and icons displayed on top of the background color.

onErrorRgbaHex

Color used for text and icons displayed on top of the error color.

onErrorContainerRgbaHex

The color (and state variants) that should be used for content on top of errorContainer.

onPrimaryRgbaHex

Color used for text and icons displayed on top of the primary color.

onPrimaryContainerRgbaHex

The color (and state variants) that should be used for content on top of primaryContainer.

onPrimaryFixedRgbaHex

Color used for text and icons displayed on top of primaryFixed or primaryFixedDim. Maintains the same tone in light and dark themes.

onPrimaryFixedVariantRgbaHex

An onPrimaryFixed variant which provides less emphasis. Useful when a strong contrast is not required.

onSecondaryRgbaHex

Color used for text and icons displayed on top of the secondary color.

onSecondaryContainerRgbaHex

The color (and state variants) that should be used for content on top of secondaryContainer.

onSecondaryFixedRgbaHex

Color used for text and icons displayed on top of secondaryFixed or secondaryFixedDim. Maintains the same tone in light and dark themes.

onSecondaryFixedVariantRgbaHex

An onSecondaryFixed variant which provides less emphasis. Useful when a strong contrast is not required.

onSurfaceRgbaHex

Color used for text and icons displayed on top of the surface color.

onSurfaceVariantRgbaHex

The color (and state variants) that can be used for content on top of surface.

onTertiaryRgbaHex

Color used for text and icons displayed on top of the tertiary color.

onTertiaryContainerRgbaHex

The color (and state variants) that should be used for content on top of tertiaryContainer.

onTertiaryFixedRgbaHex

Color used for text and icons displayed on top of tertiaryFixed or tertiaryFixedDim. Maintains the same tone in light and dark themes.

onTertiaryFixedVariantRgbaHex

An onTertiaryFixed variant which provides less emphasis. Useful when a strong contrast is not required.

outlineRgbaHex

Subtle color used for boundaries. Outline color role adds contrast for accessibility purposes.

outlineVariantRgbaHex

Utility color used for boundaries for decorative elements when strong contrast is not required.

primaryRgbaHex

The primary color is the color displayed most frequently across your app's screens and components.

primaryContainerRgbaHex

The preferred tonal color of containers.

primaryFixedRgbaHex

A primary variant that maintains the same tone in light and dark themes. The fixed color role may be used instead of the equivalent container role in situations where such fixed behavior is desired.

primaryFixedDimRgbaHex

A primary variant that maintains the same tone in light and dark themes. Dim roles provide a stronger, more emphasized tone relative to the equivalent fixed color.

scrimRgbaHex

Color of a scrim that obscures content.

secondaryRgbaHex

The secondary color provides more ways to accent and distinguish your product. Secondary colors are best for:

  • Floating action buttons
  • Selection controls, like checkboxes and radio buttons
  • Highlighting selected text
  • Links and headlines
secondaryContainerRgbaHex

A tonal color to be used in containers.

secondaryFixedRgbaHex

A secondary variant that maintains the same tone in light and dark themes. The fixed color role may be used instead of the equivalent container role in situations where such fixed behavior is desired.

secondaryFixedDimRgbaHex

A secondary variant that maintains the same tone in light and dark themes. Dim roles provide a stronger, more emphasized tone relative to the equivalent fixed color.

surfaceRgbaHex

The surface color that affect surfaces of components, such as cards, sheets, and menus.

surfaceBrightRgbaHex

A surface variant that is always brighter than surface, whether in light or dark mode.

surfaceContainerRgbaHex

A surface variant that affects containers of components, such as cards, sheets, and menus.

surfaceContainerHighRgbaHex

A surface variant for containers with higher emphasis than surfaceContainer. Use this role for content which requires more emphasis than surfaceContainer.

surfaceContainerHighestRgbaHex

A surface variant for containers with higher emphasis than surfaceContainerHigh. Use this role for content which requires more emphasis than surfaceContainerHigh.

surfaceContainerLowRgbaHex

A surface variant for containers with lower emphasis than surfaceContainer. Use this role for content which requires less emphasis than surfaceContainer.

surfaceContainerLowestRgbaHex

A surface variant for containers with lower emphasis than surfaceContainerLow. Use this role for content which requires less emphasis than surfaceContainerLow.

surfaceDimRgbaHex

A surface variant that is always dimmer than surface, whether in light or dark mode.

surfaceTintRgbaHex

This color will be used by components that apply tonal elevation and is applied on top of surface. The higher the elevation the more this color is used.

surfaceVariantRgbaHex

Another option for a color with similar uses of surface.

tertiaryRgbaHex

The tertiary color that can be used to balance primary and secondary colors, or bring heightened attention to an element such as an input field.

tertiaryContainerRgbaHex

A tonal color to be used in containers.

tertiaryFixedRgbaHex

A tertiary variant that maintains the same tone in light and dark themes. The fixed color role may be used instead of the equivalent container role in situations where such fixed behavior is desired.

tertiaryFixedDimRgbaHex

A tertiary variant that maintains the same tone in light and dark themes. Dim roles provide a stronger, more emphasized tone relative to the equivalent fixed color.

MaterialColorsOptions

Android

Options common to getMaterialColors and useMaterialColors.

PropertyTypeDescription
scheme(optional)'light' | 'dark'

Force a specific appearance. When omitted, the palette follows the current system dark/light mode.

seedColor(optional)ColorValue

Seed color used to generate the full Material 3 palette via the SchemeTonalSpot variant (the same one Material You uses). When set, the palette is derived from this color on every Android device, including those below Android 12 where wallpaper-based dynamic colors are not available. When omitted, the palette comes from the device wallpaper (Android 12+) or the static Material 3 baseline.

RgbaHex

Android

8-digit RGBA hex color string, always in #RRGGBBAA form (uppercase). Compatible with React Native's ColorValue.

String union of string values.

UseMaterialColorsOptions

Android

Options for useMaterialColors.

Type: Omit<MaterialColorsOptions, 'scheme'> extended by:

PropertyTypeDescription
colorScheme(optional)ColorSchemeName

'light' or 'dark' force a specific palette. 'unspecified', null, or omitted follows the system appearance.