Theme API
For concepts and the full token table, see the Theming guide.
PatineProvider
function PatineProvider(props: {
children: React.ReactNode;
colorScheme?: 'auto' | 'light' | 'dark'; // default 'auto'
theme?: DeepPartial<Theme>; // merged onto lightTheme (and onto darkTheme if `darkTheme` is omitted)
darkTheme?: DeepPartial<Theme>; // merged onto darkTheme
platform?: PlatformOSType; // default Platform.OS
design?: 'brand' | 'native' | 'ios' | 'material' | 'web'; // default 'brand'
}): JSX.Element;
Optional. Without a provider, components use lightTheme / darkTheme following useColorScheme().
useTheme
function useTheme(override?: DeepPartial<Theme>): Theme;
Returns the active theme: the design's tokens on the built-in light or dark theme, then the provider's overrides, then override. The design comes from override.design, the provider's design, or the platform. theme.design tells your own components which design to match.
usePlatform
function usePlatform(): PlatformOS; // 'ios' | 'android' | 'web' | 'windows' | 'macos'
The platform components behave as on: PatineProvider's platform, or Platform.OS without one. Read it in your own components to follow the same behaviour as Patine's, such as a bottom sheet on phones and a dropdown on the web, including when the docs or a preview set the provider's platform to show iOS or Android in a browser.
createTheme
function createTheme(overrides: DeepPartial<Theme>, base?: Theme): Theme;
Builds a complete theme. Without base, starts from darkTheme if overrides.dark is true, else lightTheme.
mergeTheme
function mergeTheme<T>(base: T, override?: DeepPartial<T>): T;
Deep merge without mutating. Plain objects merge recursively; arrays, functions and primitives in override replace the base value.
lightTheme / darkTheme
const lightTheme: Theme;
const darkTheme: Theme;
The built-in themes. See default values.
Designs
const DESIGN: { brand: 'brand'; native: 'native'; ios: 'ios'; material: 'material'; web: 'web' };
const DESIGN_TOKENS: Record<Design, DeepPartial<Theme>>; // what each design changes on the light or dark theme
function resolveDesign(preference: DesignPreference, platform: PlatformOSType): Design;
resolveDesign('native', platform) gives 'ios' on iOS, 'web' on the web and 'material' everywhere else. See designs.
textStyle and fontFace
function textStyle(
theme: Theme,
size: TextSize, // 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | 'display' | 'hero'
weight?: 'regular' | 'medium' | 'semibold' | 'bold', // default 'regular'
font?: 'body' | 'heading' | 'display' | 'numeric' | 'mono', // default 'body'
): TextStyle; // { fontSize, lineHeight?, letterSpacing?, fontFamily?, fontWeight?, color: theme.colors.text }
function fontFace(theme: Theme, weight?: TextWeight, font?: FontRole): TextStyle; // { fontFamily?, fontWeight? }
The family is the role's face for that weight, else its regular face at that weight, else body's, else the system font. A face named for the exact weight is drawn without fontWeight. numeric adds tabular figures (TABULAR).
Types
type DeepPartial<T> = { [K in keyof T]?: T[K] extends (...args: never[]) => unknown ? T[K] : T[K] extends object ? DeepPartial<T[K]> : T[K] };
interface ThemableProps { theme?: DeepPartial<Theme>; design?: Design }
type DesignPreference = 'brand' | 'native' | 'ios' | 'material' | 'web';
type Design = 'ios' | 'material' | 'web';
type Locale = string; // a BCP 47 tag passed to Intl, e.g. 'en-US' or 'he'. Default: the device locale