Skip to main content

Theming

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​

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>
);
}
PropTypeDefaultDescription
colorScheme'auto' | 'light' | 'dark''auto''auto' follows useColorScheme().
themeDeepPartial<Theme>—Overrides merged onto lightTheme. Also applied to dark mode when darkTheme is not given.
darkThemeDeepPartial<Theme>—Overrides merged onto darkTheme.
platform'ios' | 'android' | 'web' | …Platform.OSPickers behave as on this platform. See previewing other platforms.
design'auto' | 'ios' | 'material' | 'web''auto'The look pickers follow. 'auto' matches the platform. See designs.
childrenReactNoderequired
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:

Loading…
<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:

Loading…
<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>
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​

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​

TokenLightDark
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.primaryMutedrgba(31,107,99,0.10)rgba(108,196,179,0.16)
colors.border#E5E1D9#242D2A
colors.outline#8C877E#6A7571
colors.backdroprgba(23,26,25,0.48)rgba(0,0,0,0.6)
colors.indicatorrgba(23,26,25,0.06)rgba(255,255,255,0.07)
colors.handle#D3CEC5#38433F
colors.hoverrgba(23,26,25,0.04)rgba(255,255,255,0.05)
colors.ripplergba(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
TokenValue (both)
radiussm 8 · md 12 · lg 16 · full 999 · sheet 24
spacingxs 4 · sm 8 · md 12 · lg 16 · xl 24
typography.sizesxs 11 · sm 13 · md 16 · lg 19 · xl 22 · 2xl 26 · 3xl 32 · display 44 · hero 64
typography.trackingdisplay -1 · hero -1.6 (other steps: the font's own)
typography.fonts / lineHeightsnone: the system font at its own line height
typography.weightsregular '400' · medium '500' · semibold '600' · bold '700'
density'comfortable'
animation.duration240

These are the iOS design's values. Each design sets its own shadows (see 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.

Where each colour is used​

TokenUsed by
primarySelected day, today ring, calendar arrows, check marks, chips text, Done button, category underline, tap-to-type ring
primaryMutedRange band, selected select row, chips background, selected skin tone
indicatorWheel selection band
surfaceSearch inputs, skin-tone button
hoverEvery pressable while the pointer is over it: field, rows, days, wheel rows, emoji, buttons
rippleThe same elements on press, on every platform, except the select field and wheel rows
textSecondaryUnselected wheel rows, weekday names, placeholders, descriptions, Cancel
textDisabledDisabled days / rows, outside-month days
dangerDestructive 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:

Loading…
<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:

Loading…
<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:

<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:

<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:

LevelUsed by
xsCard at rest (Patine, web), the raised tab and segment, scroll arrows
smSwitch thumb, slider and colour knobs
mdRaised tooltip, Material dialog and snackbar, a hovered card
lgPopover, dropdowns and menus, Select's list, the emoji skin-tone picker, toasts
xlDialog, 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">.

Loading…
<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>
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​

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:

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:

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:

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.