Theming
Material 3 schemes and foundation roles projected into applications through ThemeProvider.
Material theming
Material 3 theming coordinates foundations rather than styling each component in isolation. Color supplies semantic roles such as primary and surface, typography supplies named text roles, shape supplies reusable corner families, and component tokens map those foundation roles into the visuals of a specific component.
m3-ui keeps the same separation. Components consume canonical tokens and semantic roles; applications choose the active runtime theme through ThemeProvider instead of copying component constants into app CSS.
- Material 3 color
- Color covers baseline schemes, semantic roles, dynamic color, and contrast.
- Typography covers the Material type scale and typeface roles.
- Shape, motion, and elevation remain canonical component/foundation data, but they are not currently global mutable
ThemeProviderinputs.
ThemeProvider as the application theme boundary
ThemeProvider projects the current Material runtime values into a React subtree. It owns the resolved light or dark color scheme, optional dynamic source color, contrast input for dynamic schemes, global ripple focus treatment, scoped theme CSS variables, default Material typeface variables, and a matching theme scope for portaled surfaces.
import { ThemeProvider } from '@m3-ui/ui';
export function AppRoot() {
return (
<ThemeProvider mode="light">
<App />
</ThemeProvider>
);
}The provider renders a normal themed wrapper marked with data-m3-theme and data-theme. Generated theme CSS supplies the baseline Material variables for that scope. Runtime dynamic color values and explicit style overrides are written after those baseline declarations.
Public theme inputs
| Prop | Contract | Default |
|---|---|---|
mode | Resolved Material scheme mode: `light | dark` |
sourceColor | Optional source color for runtime Material dynamic color generation | baseline scheme |
contrastLevel | Dynamic-scheme contrast input from -1 through 1 | 0 |
rippleFocus | Global Material ripple focus treatment: `opacity | inset-ring` |
style | CSS and custom-property overrides applied after generated/runtime theme values | — |
Normal div attributes such as className, id, and data attributes are forwarded to the provider wrapper.
Baseline schemes
When sourceColor is omitted, ThemeProvider uses the generated Material baseline light or dark scheme selected by mode.
<ThemeProvider mode="dark">
<App />
</ThemeProvider>The baseline role values come from the canonical token graph. ThemeProvider does not rebuild a second handwritten palette at runtime.
Dynamic color and contrast
When sourceColor is present, m3-ui converts that color to HCT and creates a Material Color Utilities SchemeTonalSpot scheme. The generated role set replaces the baseline color-role variables within the provider scope.
<ThemeProvider
mode="dark"
sourceColor="#0061a4"
contrastLevel={0.5}
>
<App />
</ThemeProvider>contrastLevel accepts values from -1 through 1; values outside that range throw. It is an input to runtime dynamic scheme generation, so changing contrastLevel without a sourceColor does not alter the baseline scheme.
Dynamic color changes semantic roles, not component token definitions. A button that resolves its container through the primary role continues to reference the same component token; only the concrete primary color changes inside the active theme.
See Color for the role model and dynamic-color details.
Typography and shape ownership
Material theming includes typography and shape as foundations, but their runtime ownership is not identical in the current package.
ThemeProvider installs the generated Material typeface variables used by the public type scale and by components. The actual type-scale values remain canonical generated data rather than provider props.
Shape tokens are likewise part of the Material foundation/component-token system, but there is no global ThemeProvider shapes={...} contract today. Customize shape only through public component APIs or documented semantic/theme variables where such an override is intentionally exposed; do not copy internal component constants into application code.
system preference belongs to the application
The public ThemeMode type is intentionally only light | dark. system is a preference policy, not a third Material color scheme.
Applications can own browser or operating-system preference resolution, persistence, and user controls, then pass the resolved mode into ThemeProvider.
const resolvedMode =
preference === 'system' ? systemMode : preference;
<ThemeProvider mode={resolvedMode}>
{children}
</ThemeProvider>The documentation application uses this pattern in its own DocsThemeProvider: docs state may be system | light | dark, but only the resolved light | dark value crosses into the public @m3-ui/ui provider. A docs-owned pre-hydration bootstrap resolves the persisted/versioned preference (or the system color scheme) before the themed scopes paint, then DocsThemeProvider continues observing system changes after hydration. That docs-only persistence/bootstrap policy is not part of the core theme API.
Theme-aware portals
Material overlays often render outside the normal DOM subtree. ThemeProvider therefore creates a second themed container under document.body and registers it once with React Aria's UNSAFE_PortalProvider. React Aria overlays beneath the theme boundary inherit that container automatically rather than each m3-ui component forwarding a private portal-context value.
The normal provider wrapper and portal container receive the same data-m3-theme, data-theme, dynamic color variables, and style override object. Dialogs, menus, sheets, tooltips, and other library surfaces rendered through that container therefore resolve the same theme roles as nearby non-portaled content. Nested ThemeProvider instances install the nearest portal target for their descendants. Existing component APIs that expose an explicit UNSTABLE_portalContainer still override the provider when an application needs a different host.
A className passed to ThemeProvider belongs to the normal wrapper only. If a theme override must also reach library portals, put the semantic custom-property override in the provider style object rather than relying on a wrapper-only class selector.
Ripple focus treatment
rippleFocus selects the global Material ripple focus presentation while leaving focus semantics with the underlying web control.
<ThemeProvider rippleFocus="inset-ring">
<App />
</ThemeProvider>opacity is the default Material ripple-theme mapping. inset-ring selects the library mapping of AndroidX's inset focus-ring configuration. This changes visual indication; it does not replace browser focus behavior or accessible interaction semantics.
Safe theme customization
Prefer semantic customization at the theme boundary. Public CSS custom properties let application styling change a role while components continue to consume their canonical token mapping.
<ThemeProvider
style={{
'--primary': '#315da8',
'--on-primary': '#ffffff',
}}
>
<App />
</ThemeProvider>Those values are application overrides, not canonical Material token values. When replacing semantic colors manually, the application is responsible for maintaining appropriate contrast and coherent related roles.
For larger color-system changes, prefer sourceColor and Material dynamic scheme generation over overriding a long list of roles by hand. For local component variation, prefer that component's documented public props before reaching for theme-wide variables.
Avoid copying internal selectors, private token names, measured dimensions, or component implementation constants into application styles. Those are implementation details rather than a stable theming API.
Runtime data for JavaScript consumers
useTheme() exposes the resolved runtime theme to code that genuinely needs JavaScript access:
interface ThemeContextValue {
mode: 'light' | 'dark';
sourceColor?: string;
contrastLevel: number;
rippleFocus: 'opacity' | 'inset-ring';
scheme: ColorScheme;
}Normal component styling should still prefer semantic CSS roles and the cascade. The React context is for runtime logic that cannot be expressed through CSS alone.
Current boundary
ThemeProvider currently owns runtime color scheme selection/generation, generated theme projection, typeface application, ripple focus configuration, and theme-aware portal propagation.
It does not own application preference persistence, a system mode, adaptive layout policy, or global mutable shape/motion/elevation objects. Those concerns remain with the application or their respective public foundation/component APIs until a dedicated runtime contract exists.