# Theme API

> PatineProvider, useTheme, usePlatform, createTheme, mergeTheme, lightTheme, darkTheme, designs, textStyle and fontFace — signatures and behaviour.

For concepts and the full token table, see the [Theming guide](../guides/theming).

## `PatineProvider`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
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`

```ts
const lightTheme: Theme;
const darkTheme: Theme;
```

The built-in themes. See [default values](../guides/theming#defaults).

## Designs

```ts
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](../guides/designs).

## `textStyle` and `fontFace`

```ts
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

```ts
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
```
