# Theming

> Theme every React Native picker with PatineProvider: colours, radius, spacing, typography and custom font tokens, automatic dark mode, iOS / Material / web designs and createTheme.

Pickers ship with a light and a dark theme that follow the OS appearance automatically. Change any token for the whole app with `PatineProvider`, or for one component with its `theme` prop.

## PatineProvider

```tsx title="App.tsx"
import { PatineProvider } from 'patine-ui';

export default function App() {
  return (
    <PatineProvider
      colorScheme="auto"
      theme={{
        colors: { primary: '#FF5A5F', primaryMuted: 'rgba(255,90,95,0.12)' },
        radius: { md: 8, sheet: 16 },
        typography: { fonts: { body: { regular: 'Inter_400Regular', semibold: 'Inter_600SemiBold' } } },
      }}
      darkTheme={{
        colors: { primary: '#FF8A8E', background: '#000000', sheet: '#111111' },
      }}
    >
      <Navigation />
    </PatineProvider>
  );
}
```

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `colorScheme` | `'auto' \| 'light' \| 'dark'` | `'auto'` | `'auto'` follows `useColorScheme()`. |
| `theme` | `DeepPartial<Theme>` | — | Overrides merged onto `lightTheme`. **Also applied to dark mode when `darkTheme` is not given.** |
| `darkTheme` | `DeepPartial<Theme>` | — | Overrides merged onto `darkTheme`. |
| `platform` | `'ios' \| 'android' \| 'web' \| …` | `Platform.OS` | Pickers behave as on this platform. See [previewing other platforms](./platforms#previewing-other-platforms). |
| `design` | `'auto' \| 'ios' \| 'material' \| 'web'` | `'auto'` | The look pickers follow. `'auto'` matches the platform. See [designs](./designs). |
| `children` | `ReactNode` | **required** | |

:::caution Light overrides leak into dark mode
If you pass only `theme`, the same overrides are applied on top of the dark base too. That's right for brand colours and fonts, but wrong for backgrounds. Pass `darkTheme` whenever you override surface colours.
:::

Providers can be nested; the innermost one wins. That's an easy way to force one area dark:

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { PatineProvider, DatePicker } from 'patine-ui';

export default function Example() {
  const [date, setDate] = useState<Date | null>(new Date());
  return (
    <PatineProvider colorScheme="dark">
      <View
        style={{ backgroundColor: '#0E1312', borderRadius: 20, padding: 8 }}
      >
        <DatePicker value={date} onValueChange={setDate} />
      </View>
    </PatineProvider>
  );
}
```

## Per-component `theme`

Every component accepts `theme`, merged on top of the provider's theme for that component only:

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { TimePicker } from 'patine-ui';

export default function Example() {
  const [t, setT] = useState(new Date());
  return (
    <View style={{ gap: 16 }}>
      <TimePicker
        value={t}
        onValueChange={setT}
        theme={{
          colors: { indicator: 'rgba(16,185,129,0.15)' },
          typography: { sizes: { lg: 24 } },
        }}
      />
      <TimePicker
        value={t}
        onValueChange={setT}
        theme={{
          colors: { indicator: 'rgba(244,63,94,0.12)', text: '#E11D48' },
          radius: { md: 0 },
        }}
      />
    </View>
  );
}
```

:::tip Memoize theme objects
Pass a constant or `useMemo`'d object rather than an inline literal, so the merged theme isn't recomputed every render. It matters most on wheels.
:::

## Tokens

```ts
interface Theme {
  dark: boolean;
  design: 'ios' | 'material' | 'web'; // see the Designs guide
  colors: {
    background: string;    // picker surfaces
    surface: string;       // search inputs, chips, pressed rows
    sheet: string;         // bottom sheet background
    text: string;
    textSecondary: string; // labels, unselected wheel rows, placeholders
    textDisabled: string;
    primary: string;       // selected day, check marks, buttons, accents
    onPrimary: string;     // text on primary
    primaryMuted: string;  // range band, selected list row, chips
    border: string;
    outline: string; // edges of controls, 3:1 against the background
    backdrop: string;      // sheet overlay
    indicator: string;     // wheel selection band
    handle: string;        // sheet grab handle
    hover: string;         // tint while the pointer is over anything pressable
    ripple: string;        // ripple that spreads from the touch point on press
    danger: string;        // destructive actions and field errors
    onDanger: string;      // text and icons on a danger fill (destructive Button, Badge)
    success: string;       // positive statuses (Badge, Alert)
    warning: string;       // statuses that need attention (Badge, Alert)
  };
  radius: { sm: number; md: number; lg: number; full: number; sheet: number };
  spacing: { xs: number; sm: number; md: number; lg: number; xl: number };
  typography: {
    // Families by role, one name per weight. A missing role uses body; no body, the system font.
    fonts?: Partial<Record<'body' | 'heading' | 'display' | 'numeric' | 'mono', { regular: string; medium?: string; semibold?: string; bold?: string }>>;
    sizes: { xs: number; sm: number; md: number; lg: number; xl: number; '2xl': number; '3xl': number; display: number; hero: number };
    lineHeights?: Partial<Record<TextSize, number>>; // points; leave out to keep each font's own
    tracking?: Partial<Record<TextSize, number>>;    // letterSpacing in points
    weights: { regular: TextStyle['fontWeight']; medium: TextStyle['fontWeight']; semibold: TextStyle['fontWeight']; bold: TextStyle['fontWeight'] };
  };
  density: 'comfortable' | 'compact'; // compact packs lists and tables for desktop screens with a pointer
  animation: { duration: number }; // ms: moves and overlays (month slide, sheet open (+60) / close, switches, tabs). Press and hover feedback use their own short timings
  shadows: { none: string; xs: string; sm: string; md: string; lg: string; xl: string }; // CSS box-shadow strings
}
```

### Defaults

| Token | Light | Dark |
| --- | --- | --- |
| `colors.background` | `#FFFFFF` | `#0E1312` |
| `colors.surface` | `#F4F2EE` | `#18201E` |
| `colors.sheet` | `#FFFFFF` | `#121816` |
| `colors.text` | `#171A19` | `#EDF0EC` |
| `colors.textSecondary` | `#5F5B54` | `#9AA39F` |
| `colors.textDisabled` | `#ABA69D` | `#4B5552` |
| `colors.primary` | `#1F6B63` | `#6CC4B3` |
| `colors.onPrimary` | `#FFFFFF` | `#06201B` |
| `colors.primaryMuted` | `rgba(31,107,99,0.10)` | `rgba(108,196,179,0.16)` |
| `colors.border` | `#E5E1D9` | `#242D2A` |
| `colors.outline` | `#8C877E` | `#6A7571` |
| `colors.backdrop` | `rgba(23,26,25,0.48)` | `rgba(0,0,0,0.6)` |
| `colors.indicator` | `rgba(23,26,25,0.06)` | `rgba(255,255,255,0.07)` |
| `colors.handle` | `#D3CEC5` | `#38433F` |
| `colors.hover` | `rgba(23,26,25,0.04)` | `rgba(255,255,255,0.05)` |
| `colors.ripple` | `rgba(23,26,25,0.12)` | `rgba(255,255,255,0.16)` |
| `colors.danger` | `#C2352B` | `#FF7B70` |
| `colors.onDanger` | `#FFFFFF` | `#1F0705` |
| `colors.success` | `#4D7C0F` | `#A8D46A` |
| `colors.warning` | `#A16207` | `#F2C94C` |

| Token | Value (both) |
| --- | --- |
| `radius` | `sm 8 · md 12 · lg 16 · full 999 · sheet 24` |
| `spacing` | `xs 4 · sm 8 · md 12 · lg 16 · xl 24` |
| `typography.sizes` | `xs 11 · sm 13 · md 16 · lg 19 · xl 22 · 2xl 26 · 3xl 32 · display 44 · hero 64` |
| `typography.tracking` | `display -1 · hero -1.6` (other steps: the font's own) |
| `typography.fonts` / `lineHeights` | none: the system font at its own line height |
| `typography.weights` | `regular '400' · medium '500' · semibold '600' · bold '700'` |
| `density` | `'comfortable'` |
| `animation.duration` | `240` |

These are the iOS design's values. Each design sets its own `shadows` (see [Shadows and elevation](#shadows-and-elevation)). The other designs change `radius` on top of them: the Patine design (the default) uses `sm 6 · md 10 · lg 14 · sheet 20`, Material uses `md 4 · sheet 28`, web uses `sm 6 · md 8 · lg 12 · sheet 12`. See [designs](./designs).

### Where each colour is used

| Token | Used by |
| --- | --- |
| `primary` | Selected day, today ring, calendar arrows, check marks, chips text, Done button, category underline, tap-to-type ring |
| `primaryMuted` | Range band, selected select row, chips background, selected skin tone |
| `indicator` | Wheel selection band |
| `surface` | Search inputs, skin-tone button |
| `hover` | Every pressable while the pointer is over it: field, rows, days, wheel rows, emoji, buttons |
| `ripple` | The same elements on press, on every platform, except the select field and wheel rows |
| `textSecondary` | Unselected wheel rows, weekday names, placeholders, descriptions, Cancel |
| `textDisabled` | Disabled days / rows, outside-month days |
| `danger` | Destructive actions in ActionSheet and DropdownMenu, a field's error border, label and message |

## Hover and ripple

Everything you can press (the select field, list and dropdown rows, calendar days, wheel rows, emoji, sheet buttons) tints while a pointer is over it. Items also ripple from the touch point when pressed; the select field and wheel rows don't, since the field opens a list and a wheel row scrolls into place. Hover only happens with a mouse or trackpad, so phones get just the ripple. In brand, iOS and web the ripple is a dim while held; the tint and the dim fade in and out, and buttons and chips also shrink a little and spring back on release (not in Material, nor with reduce motion on). Both are theme colours, so they follow light and dark mode:

```tsx live
import { useState } from 'react';
import { SelectList } from 'patine-ui';

const fruits = ['Apple', 'Banana', 'Cherry', 'Mango'].map((f) => ({
  label: f,
  value: f,
}));

export default function Example() {
  const [fruit, setFruit] = useState<string | null>('Banana');
  return (
    <SelectList
      options={fruits}
      value={fruit}
      onValueChange={setFruit}
      theme={{
        colors: {
          hover: 'rgba(200,70,13,0.08)',
          ripple: 'rgba(200,70,13,0.22)',
        },
      }}
    />
  );
}
```

Set either to `'transparent'` to turn that effect off. Hover and press both lists to compare:

```tsx live
import { useState } from 'react';
import { Text, View } from 'react-native';
import { SelectList } from 'patine-ui';

const sizes = ['Small', 'Medium', 'Large'].map((s) => ({ label: s, value: s }));

export default function Example() {
  const [a, setA] = useState<string | null>('Medium');
  const [b, setB] = useState<string | null>('Medium');
  return (
    <View style={{ flexDirection: 'row', gap: 16 }}>
      <View style={{ flex: 1 }}>
        <Text style={{ fontWeight: '600', marginBottom: 8 }}>Default</Text>
        <SelectList options={sizes} value={a} onValueChange={setA} />
      </View>
      <View style={{ flex: 1 }}>
        <Text style={{ fontWeight: '600', marginBottom: 8 }}>Turned off</Text>
        <SelectList
          options={sizes}
          value={b}
          onValueChange={setB}
          theme={{ colors: { hover: 'transparent', ripple: 'transparent' } }}
        />
      </View>
    </View>
  );
}
```

For the whole app, set them once on the provider:

```tsx
<PatineProvider theme={{ colors: { hover: 'transparent', ripple: 'transparent' } }}>…</PatineProvider>
```

Dark mode has its own defaults (a light tint instead of a dark one); override them through `darkTheme`:

```tsx
<PatineProvider
  theme={{ colors: { hover: 'rgba(14,165,233,0.08)', ripple: 'rgba(14,165,233,0.2)' } }}
  darkTheme={{ colors: { hover: 'rgba(56,189,248,0.12)', ripple: 'rgba(56,189,248,0.25)' } }}
>
  …
</PatineProvider>
```

## Shadows and elevation

Every shadow in the library comes from one scale, `theme.shadows`: `none`, `xs`, `sm`, `md`, `lg` and `xl`. Each value is a CSS `box-shadow` string, which React Native draws the same way on iOS, Android and the web (New Architecture, React Native 0.76 and later). Change a level once and every component that sits on it follows:

| Level | Used by |
| --- | --- |
| `xs` | Card at rest (Patine, web), the raised tab and segment, scroll arrows |
| `sm` | Switch thumb, slider and colour knobs |
| `md` | Raised tooltip, Material dialog and snackbar, a hovered card |
| `lg` | Popover, dropdowns and menus, Select's list, the emoji skin-tone picker, toasts |
| `xl` | Dialog, Modal (Patine, web) |

Each design fills the scale its own way: **Patine** (`brand`) uses soft, low layers tinted with its green-black ink; **iOS** uses wide, diffuse shadows and UIKit's two-layer knob shadow at `sm`; **Material** uses Material 3's elevation levels 1 to 5 (a key and an ambient shadow); **web** uses Tailwind's `shadow-xs` to `shadow-xl`. The values are exported as `DESIGN_SHADOWS`.

Override any level in `PatineProvider` (for every design) or in a component's `theme`. `'none'` turns it off. Components that cast a shadow also take a `shadow` prop that picks a level, such as `<Card shadow="lg">`.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, PatineProvider, SegmentedControl, Switch, Text, VStack } from 'patine-ui';

const PRESETS = {
  default: undefined,
  flat: { xs: 'none', sm: 'none', md: 'none', lg: 'none', xl: 'none' },
  deep: {
    xs: '0px 2px 6px rgba(0,0,0,0.12)',
    sm: '0px 4px 10px rgba(0,0,0,0.18)',
    md: '0px 10px 24px rgba(0,0,0,0.18)',
    lg: '0px 18px 40px rgba(0,0,0,0.22)',
    xl: '0px 28px 64px rgba(0,0,0,0.28)',
  },
};

export default function Example() {
  const [preset, setPreset] = useState('default');
  const [on, setOn] = useState(true);
  return (
    <VStack gap="lg" style={{ maxWidth: 380, width: '100%' }}>
      <SegmentedControl
        items={[
          { label: 'Design', value: 'default' },
          { label: 'Flat', value: 'flat' },
          { label: 'Deep', value: 'deep' },
        ]}
        value={preset}
        onValueChange={setPreset}
      />
      <PatineProvider theme={{ shadows: PRESETS[preset] }}>
        <View style={{ gap: 16, padding: 8 }}>
          <Card onPress={() => {}} accessibilityLabel="Pro plan">
            <CardHeader>
              <CardTitle>Pro plan</CardTitle>
              <CardDescription>Hover me: the card rises a step.</CardDescription>
            </CardHeader>
          </Card>
          <Card shadow="lg">
            <CardContent>
              <Text>A card on the `lg` level.</Text>
            </CardContent>
          </Card>
          <Switch label="The thumb's shadow follows too" checked={on} onCheckedChange={setOn} />
        </View>
      </PatineProvider>
    </VStack>
  );
}
```

```tsx title="App.tsx"
<PatineProvider
  theme={{ shadows: { xs: 'none', lg: '0px 12px 32px rgba(15,23,42,0.18)' } }}
  darkTheme={{ shadows: { lg: '0px 12px 32px rgba(0,0,0,0.6)' } }}
>
  …
</PatineProvider>
```

`stepShadow(level, steps)` walks the scale (a hovered card uses `stepShadow(shadow, 2)`), and `theme.shadows[level]` reads a value for your own components.

## Building a theme in code

```ts
import { createTheme, mergeTheme, lightTheme, darkTheme } from 'patine-ui';

// Full theme from overrides on top of light (or dark when overrides.dark is true)
const brand = createTheme({ colors: { primary: '#0EA5E9' } });

// Explicit base
const brandDark = createTheme({ colors: { primary: '#38BDF8' } }, darkTheme);

// Generic deep merge (objects are merged, arrays and primitives replaced)
const tweaked = mergeTheme(lightTheme, { radius: { md: 4 } });
```

## Using the theme in your own components

`useTheme()` returns the active, resolved theme, so your buttons and fields can match the pickers:

```tsx
import { Pressable, Text } from 'react-native';
import { useTheme, textStyle } from 'patine-ui';

function DoneButton({ onPress }: { onPress: () => void }) {
  const theme = useTheme();
  return (
    <Pressable onPress={onPress} style={{ backgroundColor: theme.colors.primary, borderRadius: theme.radius.md, padding: theme.spacing.md }}>
      <Text style={[textStyle(theme, 'md', 'semibold'), { color: theme.colors.onPrimary }]}>Done</Text>
    </Pressable>
  );
}
```

`textStyle(theme, size, weight?, font?)` returns `{ fontSize, lineHeight, letterSpacing, fontFamily, fontWeight, color }` from the tokens; `fontFace(theme, weight?, font?)` returns only the family and weight.

## Fonts

Patine ships no font files and adds no dependency for them. Load the files your way and give the theme their names by role and weight:

```tsx
import { Manrope_400Regular, Manrope_600SemiBold, useFonts } from '@expo-google-fonts/manrope';

const [loaded] = useFonts({ Manrope_400Regular, Manrope_600SemiBold });

<PatineProvider
  theme={{
    typography: {
      fonts: { body: { regular: 'Manrope_400Regular', semibold: 'Manrope_600SemiBold' } },
      lineHeights: { xs: 16, sm: 18, md: 24, lg: 26, xl: 28, '2xl': 34, '3xl': 40, display: 48, hero: 64 },
    },
  }}
>
```

- **Roles.** `body` is everything by default. `Heading` draws in `heading`; `Stat`, numeric table cells and `<Text font="numeric">` in `numeric`, with tabular figures so columns of amounts line up; `mono` is for codes and keys. A role you leave out uses `body`.
- **One family per weight.** Static fonts name each weight (`Manrope_600SemiBold`). When a weight has its own family, Patine draws it without `fontWeight`, so Android doesn't fake bold on top. A weight you leave out draws the `regular` family at that weight, which suits a variable font on the web (`{ regular: 'Manrope Variable' }`).
- **Line heights.** Fonts differ in their natural line height, so set `lineHeights` when you set `fonts`. On Android, Patine also turns off the extra font padding so labels centre in buttons.
- **Other scripts.** iOS and Android fall back glyph by glyph to the system font when yours lacks a script (Hebrew, Arabic). Swap the whole `fonts` object per language instead, and keep `numeric` on the Latin family so amounts don't change.

## Matching your design system

Map your existing tokens once:

```tsx
import { colors, radii, fonts } from './design-system';

const pickerTheme = {
  colors: { primary: colors.brand500, primaryMuted: colors.brand50, text: colors.gray900, textSecondary: colors.gray500, border: colors.gray200 },
  radius: { md: radii.md, sheet: radii.xl },
  typography: { fonts: { body: { regular: fonts.regular, semibold: fonts.semibold } } },
};
const pickerDarkTheme = { colors: { primary: colors.brand300, background: colors.gray950, sheet: colors.gray900 } };

<PatineProvider theme={pickerTheme} darkTheme={pickerDarkTheme}>…</PatineProvider>
```

→ For per-part tweaks beyond tokens, see [Styling](./styling).
