Skip to main content

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