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
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. |
design | 'auto' | 'ios' | 'material' | 'web' | 'auto' | The look pickers follow. 'auto' matches the platform. See designs. |
children | ReactNode | required |
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:
<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:
<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>
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
| 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). 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
| 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:
<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:
<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:
| 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">.
<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>
<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.
bodyis everything by default.Headingdraws inheading;Stat, numeric table cells and<Text font="numeric">innumeric, with tabular figures so columns of amounts line up;monois for codes and keys. A role you leave out usesbody. - One family per weight. Static fonts name each weight (
Manrope_600SemiBold). When a weight has its own family, Patine draws it withoutfontWeight, so Android doesn't fake bold on top. A weight you leave out draws theregularfamily 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
lineHeightswhen you setfonts. 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
fontsobject per language instead, and keepnumericon 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.