The theme engine of Root Native UI, a React Native component library. It ships with Material Design 3, and it takes the tokens of your own design system too.
pnpm add @rootnative/core @rootnative/inertiaPeer dependencies: react >=19.3.0, react-native >=0.88.0 <0.89.0, @rootnative/inertia >=0.0.26 <0.1.0
@rootnative/inertia is required. Every animation in the library runs on it.
npm and pnpm install the required peers for you. Yarn classic doesn't, so add
it by hand there.
createMaterialTheme needs no extra install. Its MD3 color engine
(@material/material-color-utilities) is bundled behind the
@rootnative/core/create-theme subpath.
Wrap your app root in ThemeProvider:
import { ThemeProvider } from '@rootnative/core'
export default function App() {
return (
<ThemeProvider>
{/* Your app */}
</ThemeProvider>
)
}Provides the theme context to all child components. It takes an MD3 theme or a theme with your own roles. The default is the MD3 light theme.
| Prop | Type | Default | Description |
|---|---|---|---|
theme |
BaseTheme |
lightTheme (MD3) |
The theme object |
iconResolver |
IconResolver |
none | Resolves a string icon name (leadingIcon="check") to an icon node. Set it once at the app root to use Lucide, SF Symbols, custom SVGs, and so on. Pre-built adapters: @rootnative/icons. A nested provider without it uses the resolver of its parent |
children |
ReactNode |
— | The app content |
Returns the current theme from the nearest ThemeProvider.
import { useTheme } from '@rootnative/core'
// MD3 (default)
const theme = useTheme()
// Custom design system
const theme = useTheme<MyTheme>()A helper that makes a custom theme with full type checks.
A theme with your own role names is for your own components. It needs
colors and typography, and it can carry token groups of your own:
import { defineTheme } from '@rootnative/core'
const myTheme = defineTheme({
colors: { brand: '#FF6B00', background: '#FFF', text: '#1A1A1A' },
typography: {
body: {
fontFamily: 'Inter',
fontSize: 16,
fontWeight: '400',
lineHeight: 24,
letterSpacing: 0,
},
},
radius: { control: 8, card: 16 },
})The components of @rootnative/components read the MD3 color and typography
roles. For them, keep the MD3 theme and add your tokens beside it:
import { defineTheme, lightTheme } from '@rootnative/core'
const appTheme = defineTheme({
...lightTheme,
status: { success: '#388E3C', onSuccess: '#FFFFFF' },
})Makes a complete MD3 light and dark theme from one seed color, with Google's HCT color space.
import { createMaterialTheme } from '@rootnative/core/create-theme'
import { ThemeProvider } from '@rootnative/core'
const { lightTheme, darkTheme } = createMaterialTheme('#006A6A')
<ThemeProvider theme={lightTheme}>{children}</ThemeProvider>You need no extra install, and the subpath imports nothing from
react-native, so it also runs in plain Node. Print a palette from a script,
or check a theme in CI.
Scales the MD3 corner radius tokens by a multiplier: 0 = sharp corners, 1 = the MD3 default, 2 = double rounding. cornerNone stays 0 and cornerFull stays 999.
import { lightTheme, applyRoundness } from '@rootnative/core'
const sharp: Theme = { ...lightTheme, shape: applyRoundness(0.5) }One grouped object with all MD3 theme values:
import { material } from '@rootnative/core'
material.lightTheme
material.darkTheme
material.defaultTopAppBarTokensBaseTheme: the generic base. Colors asRecord<string, string>, typography asRecord<string, TypographyToken>, and room for token groups of your own.Theme: the MD3 theme. It extendsBaseThemewith 49 color roles, 30 typography variants (15 base + 15 emphasized), the shape, spacing, stateLayer, elevation and motion groups, and the optionaltopAppBartokens.MaterialThemeis an identical alias. Use it to tell the themes apart in a codebase with more than one design system.
| Token group | Description |
|---|---|
colors |
The color roles of the design system (Record<string, string>) |
typography |
The type scale variants (Record<string, TypographyToken>) |
shape |
The roundness multiplier plus the corner radius tokens (cornerNone through cornerFull) |
spacing |
The spacing scale (xs, sm, md, lg, xl) |
elevation |
The shadow levels level0 through level5 |
stateLayer |
The opacity values: pressedOpacity, focusedOpacity, hoveredOpacity, draggedOpacity, disabledOpacity, disabledContainerOpacity |
motion |
16 duration*, 7 easing* and 6 spring* tokens |
import { lightTheme } from '@rootnative/core'
import type { Theme } from '@rootnative/core'
const custom: Theme = {
...lightTheme,
colors: { ...lightTheme.colors, primary: '#006A6A', onPrimary: '#FFFFFF' },
}
<ThemeProvider theme={custom}>{children}</ThemeProvider>import { ThemeProvider, darkTheme } from '@rootnative/core'
<ThemeProvider theme={darkTheme}>{children}</ThemeProvider>A second ThemeProvider inside the root one gives one part of the app its own
theme. It takes the icon resolver of its parent when it gets no
iconResolver. With a { light, dark } pair and none of mode,
defaultMode and storage, it follows the mode of its parent, and its
setMode() sets the mode of the parent. An overlay (Dialog, Menu, ...)
renders its content at the PortalHost, so the components inside it take the
theme of the provider above the host. The
theming guide
shows the two fixes.
The HTML of a static web export holds the light theme, so a reader with a dark
system setting sees the light page until hydration ends. The
@rootnative/core/static-export subpath hides it. Put both in the HTML shell
(app/+html.tsx with Expo Router), before the body:
import { darkTheme } from '@rootnative/core'
import {
schemeGuardCss,
schemeGuardScript,
} from '@rootnative/core/static-export'
<script dangerouslySetInnerHTML={{ __html: schemeGuardScript() }} />
<style
dangerouslySetInnerHTML={{
__html: schemeGuardCss({ background: darkTheme.colors.background }),
}}
/>A reader with a dark scheme then sees the dark background until
ThemeProvider shows the dark theme. A reader with a light scheme sees no
change.
Returns the current MD3 window size class: 'compact' | 'medium' | 'expanded' | 'large' | 'extraLarge'.
Returns the value of the current breakpoint. A missing breakpoint falls back to the nearest smaller entry.
const columns = useBreakpointValue({ compact: 1, medium: 2, expanded: 4 })Returns the window size, the same as the react-native hook, but safe in a static web export. Use it when a layout needs the raw width or height.
const { width } = useWindowDimensions()ThemeProvider: the theme context provider (works with any design system, defaults to MD3)useTheme: reads the current theme (generic)useIconResolver: reads the configured icon resolveruseThemeScope/ThemeScopeProvider: read the providers of one place as one value, and provide them again at another place, for content rendered through a portaldefineTheme: makes a custom theme with full type checkscreateMaterialTheme: makes MD3 themes from a seed color (import from@rootnative/core/create-theme)schemeGuardScript/schemeGuardCss: hide the light first paint of a static web export from a dark-scheme reader (import from@rootnative/core/static-export, withSCHEME_ATTRIBUTEandTHEME_READY_ATTRIBUTE)applyRoundness: scales the MD3 corner radius tokens by a multipliermaterial: the MD3 preset object (lightTheme,darkTheme,defaultTopAppBarTokens)useBreakpoint/breakpoints: the current window size classuseBreakpointValue: responsive valuesuseWindowDimensions: the window size, safe to hydrate from a static exportlightTheme/darkTheme: the built-in MD3 themesdefaultTopAppBarTokens: the MD3 top app bar defaultsmotionTransitions: the named-transition registry thatThemeProvidermountsBaseTheme,Theme,MaterialTheme,Colors,Typography,TypographyToken,FontWeight,Shape,Spacing,Elevation,ElevationLevel,ShadowOffset,StateLayer,Motion,MotionSpring,TopAppBarTokens,IconResolver,IconRenderProps,IconSource,ThemeProviderProps,ThemeScope,ThemeScopeProviderProps,Breakpoint,BreakpointValues: types
Full docs: https://rootnative.github.io/ui/
LLM-optimized reference: https://rootnative.github.io/ui/llms-full.txt. Or read node_modules/@rootnative/core/llms.txt for the exact installed version.
MIT
