For AI assistants
This documentation is published in machine-readable form, following the llms.txt convention:
| File | Contents |
|---|---|
/llms.txt | Index of every page with a one-line summary |
/llms-full.txt | The entire documentation in one Markdown file: every component, prop table and example |
/docs/**/*.md | Each page as plain Markdown |
Paste llms-full.txt into your assistant's context, or point Cursor / Claude / Copilot at the URL.
For Claude Code, Cursor and other MCP clients, add the MCP server: claude mcp add patine -- npx -y @patine-ui/mcp.
llms-full.txt also ships inside the npm package, so a coding agent can read it offline from node_modules/patine-ui/llms-full.txt, always matching the installed version.
Cheat sheet
Package: patine-ui (npm i patine-ui)
Zero native code (pure JS), no peer deps besides react >=18 and react-native >=0.72.
Works in Expo Go, bare RN, React Native Web. All exports are named exports from the package root.
Draws the Patine design on every platform by default (design 'brand'), with each platform's behaviour; design 'native' looks native per platform (iOS on iOS, Material on Android, web on web). One look everywhere:
<PatineProvider design="native">, or one platform's look everywhere: design="ios" (or 'material' | 'web'); per component: design="material" or design="native" (wins over the provider's). theme/styles/explicit props always win over the design.
Every component takes: theme (DeepPartial<Theme>), design ('brand'|'native'|'ios'|'material'|'web'), styles (slot styles), style, testID.
Native apps: prefer subpaths so Metro skips unused pickers (root import bundles ~130 KB of emoji data):
/button /text /stack /separator /layout /field /table /stat /kbd /descriptions /breadcrumbs /pagination /tabbar /checkbox /switch /radio /card /badge /avatar /alert /skeleton /segmented
/textfield /dialog /modal /popover /tooltip /toast /tabs /accordion /collapsible /header /list /progress /empty /chat /carousel /qrcode /sortable /swipeable /lightbox /signature /steps
/wheel /time /duration /date /calendar /month /datetime /select /country /timezone /emoji /color /slider /rating /otp /action /sheet /core
e.g. 'patine-ui/date'. PhoneField is in /country, TimeRangePicker in /time, DropdownMenu and ActionSheet in /action, TextArea in /textfield, AlertDialog in /dialog, Drawer in /modal, DisclosureIcon in /collapsible.
PatineProvider and theme/date utils live in /core. Subpaths need RN 0.79+ (Metro package exports).
Controlled: value + onValueChange. Uncontrolled: defaultValue. Select/SelectList/SegmentedControl/ChipGroup are controlled-only.
onValueChange fires on user changes only (not when value is set programmatically). Wheels fire onValueChange when they settle;
onValueChanging fires on every row crossing, or every Slider step while dragging (use for haptics).
Shorthand or parts: every compound component (Dialog, AlertDialog, Modal, Drawer, Popover, Tabs, Accordion, Collapsible,
Card, Alert, RadioGroup) takes props-first shorthand on its root, so the simple case is one element:
<Dialog trigger={<Button>Edit</Button>} title="Edit profile" description="…" actions={[{ label: 'Cancel', variant: 'outline' }, { label: 'Save', onPress: save }]}>{body}</Dialog>
<AlertDialog trigger={<Button>Delete</Button>} title="Delete file?" description="…" confirmLabel="Delete" destructive onConfirm={del} />
<Tabs items={[{ value: 'a', label: 'Account', content: <A /> }]} /> <Accordion items={[{ title, content }]} />
Give any shorthand prop and the root draws the parts itself (children become the body/content); leave them out and compose
the shadcn parts below for full control. Prefer the shorthand unless the layout needs the parts.
Basics (shadcn names and props):
Text size 'xs'..'3xl'|'display'|'hero' weight 'regular'|'medium'|'semibold'|'bold' font 'body'|'heading'|'display'|'numeric'(tabular)|'mono' color (theme color key, e.g. 'textSecondary')
Heading level 1-4 (role heading + level) size (semibold, font 'heading')
Stack/HStack/VStack direction gap padding ('xs'|'sm'|'md'|'lg'|'xl'|number) align justify wrap
Separator orientation 'horizontal'|'vertical' decorative=true
Box padding paddingX paddingY margin marginX marginY gap (Space) background (theme color key) radius (theme radius key) border shadow (level) row align justify flex
Spacer size (Space; omit = grows to fill) Center fill Container size 'sm'|'md'|'lg'=default|'xl'|'full' padding='lg'
Grid columns=2 | minColumnWidth (fits as many as fit, re-flows) gap='md' rowGap columnGap
AspectRatio ratio=1 (e.g. 16/9) width='100%'; children fill it
VisuallyHidden children (read by screen readers, takes no space) Slot (merges its props into its one child; handlers both run, styles stack)
Portal/PortalHost wrap the app once in <PortalHost>; <Portal> draws its children over the app inside it (inline without a host)
Button children (label) variant 'default'|'secondary'|'outline'|'ghost'|'destructive'|'link' size 'default'|'sm'|'lg'|'icon' (icon: give accessibilityLabel)
loading disabled startIcon endIcon onPress labelStyle
ButtonGroup children (Buttons, joined; inner corners square, Material: 2pt gap + soft corners) variant size (passed to each Button that doesn't set its own) orientation aria-label
Link children href onPress (preventDefault keeps href closed) external (new tab + ↗) underline 'always'|'hover'|'none' disabled; Text props
Fab icon (node | ({color}) => node) label (extended) size 'sm'|'md'|'lg' placement 'bottomEnd'|'bottomStart'|'bottomCenter' offset=16 onPress (no label: accessibilityLabel)
CopyButton value onCopy(value) (default: web clipboard; native: pass e.g. expo-clipboard setStringAsync) label copiedLabel='Copied' timeout=2000 variant='ghost' size
ToggleButton pressed defaultPressed onPressedChange(bool) variant 'default'|'outline' size startIcon endIcon (button with aria-pressed)
ToggleGroup type 'single'|'multiple' (required) items [{ value label? icon? accessibilityLabel? disabled? }] or children <ToggleGroupItem value …ToggleButtonProps>
value defaultValue onValueChange (single: string|null, null = un-pressed; multiple: string[]) variant size attached orientation disabled
Checkbox checked (boolean|'mixed') defaultChecked onCheckedChange(bool) label description controlPosition 'start'(default)|'end' disabled
CheckboxGroup options [{ value label description? disabled? }] value defaultValue onValueChange(string[] in options order) selectAllLabel (parent box, mixed) orientation controlPosition disabled aria-label
Switch checked defaultChecked onCheckedChange(bool) loading(spinner in thumb, ignores presses, aria-busy) label description controlPosition 'end'(default)|'start' disabled
RadioGroup value defaultValue onValueChange(string) disabled orientation 'vertical'|'horizontal' aria-label; options [{ value label description? disabled? }] or children: <RadioGroupItem value label description disabled />
Card shorthand: title description footer (children = body); or <Card><CardHeader><CardTitle/><CardDescription/></CardHeader><CardContent/><CardFooter/></Card>
shadow 'none'|'xs'|'sm'|'md'|'lg'|'xl' (theme level) onPress onLongPress (whole card = button: hover lift, press feedback, focus ring; give accessibilityLabel) interactive (lift without onPress) disabled
Avatar src name (initials fallback, read by screen readers) size 'sm'|'md'|'lg'|number shape 'circle'|'square'
Image src alt (no alt = decorative) width='100%' height aspectRatio fit 'cover'|'contain'|'stretch'|'center' radius (step|'full'|px) placeholder fallback onLoad onError; holds its size while loading, fades in, fallback on error. Shares RN's Image name: import { Image as PatineImage } if you need both
AvatarGroup avatars [{ name src? }] max (last slot becomes +N) size shape overlap=0.25 accessibilityLabel (default: the names)
Badge children variant 'default'|'secondary'|'outline'|'success'|'warning'|'destructive'
Alert variant 'default'|'destructive'|'success'|'warning' icon live (announce; default true for destructive) title description (shorthand); or children: <AlertTitle/> <AlertDescription/>
Skeleton width='100%' height=16 radius 'sm'|'md'|'lg'|'full'|number (hidden from screen readers; still with reduce motion)
Progress value (0..max; omit/null = indeterminate sweep, still with reduce motion) max=100 height indicatorStyle accessibilityLabel (role progressbar)
Spinner color (theme key, 'primary') size 'small'|'large' accessibilityLabel='Loading'
EmptyState title description icon (emoji or node) action (Buttons) children
List title (section heading) footer (note) contentStyle; children: <ListItem title description leading trailing value showChevron destructive disabled onPress />
ios: inset grouped, chevrons on rows with onPress; material: full-width rows, no dividers; web: outlined box
Table columns [{ key title align? width? flex? accessor?(row) render?(row,i) sortable? }] data keyExtractor onRowPress(row,i) caption striped
sort defaultSort onSortChange({key,direction:'asc'|'desc'}|null) manualSort (server) emptyText minWidth (scrolls sideways below)
DescriptionList items [{ term details(node) }] orientation 'horizontal'|'vertical' (default from design) dividers=true
Stat label value change('+12.5%'|number) trend('up'|'down'|'neutral', default from sign) invertTrend (down is good) description icon children
Kbd children (one key) | keys ['⌘','K'] separator ('+') size 'sm'|'md' (read as 'Command K')
BottomTabBar items [{ value label icon (node | ({selected,color}) => node) badge (number|true) disabled }] value defaultValue onValueChange (also on re-press) bottomInset (safe area)
NavigationRail same items/value props header (menu/FAB) topInset; for tablets and desktop
Breadcrumbs items [{ label onPress? icon? }] (last = current page) separator (default from design) maxItems (folds middle into …)
Pagination pageCount page defaultPage onPageChange(page) siblingCount=1 boundaryCount=1 variant 'numbers'|'compact' iconOnly disabled labels {nav previous next page(n) status(n,count)}
Header title subtitle onBack backLabel='Back' leading (replaces back) actions size 'default'|'large' (no safe-area inset: pad it yourself)
TypingIndicator name ("Maya is typing" for screen readers) accessibilityLabel; three dots in an incoming bubble, still with reduce motion
SuggestionChips suggestions: string[] onPress(suggestion) disabled accessibilityLabel='Suggestions'; quick replies in a sideways-scrolling row
MessageBubble children from 'me'|'them' name meta (e.g. time) bubbleStyle textStyle
ChatComposer onSend(trimmed text) (then clears) value defaultValue onValueChange placeholder sending (spinner, blocks) onStop (send becomes Stop while sending; Escape stops) disabled leading maxRows=5 labels {input, send, stop}; Enter sends on hardware keyboards, Shift+Enter = newline
TextField label value defaultValue onValueChange(text) placeholder helperText error(string|boolean) required clearable showCount (needs maxLength) secureTextEntry (+ show/hide toggle; passwordToggle=false hides it) prefix suffix startIcon endIcon readOnly disabled; any TextInput prop
TextArea TextField props + minRows=3 maxRows (grows with the text, then scrolls) rows (fixed)
SearchField value defaultValue onValueChange(text) onSubmit(text) (Search key / Enter) onCancel (iOS-style Cancel while focused; clears, dismisses keyboard) placeholder='Search' disabled labels {clear, cancel} inputStyle
NumberField TextField props + value defaultValue (number|null) onValueChange (on step, blur or Enter; clamped) min max step=1 (decimals from step) formatValue(n) (shown when not editing) hideButtons stepLabels {decrement, increment}; spinbutton, arrow keys step
Stepper value defaultValue onValueChange(number) min max step showValue (default: all but iOS) formatValue accessibilityLabel disabled labels; hold − / + to repeat; adjustable for screen readers
Tabs value defaultValue onValueChange(string) orientation 'horizontal'|'vertical' variant 'pills'|'underline' (default from design); items [{ value label content icon? disabled? }] (first enabled opens first) or children: <TabsList aria-label><TabsTrigger value icon disabled>Label</TabsTrigger></TabsList> <TabsContent value forceMount/>
Accordion type 'single'=default|'multiple' items [{ title content value?=index disabled? }] or children (below) value defaultValue onValueChange(string, '' = none | string[]) collapsible (single) disabled; children: <AccordionItem value disabled><AccordionTrigger>Heading</AccordionTrigger><AccordionContent>…</AccordionContent></AccordionItem>
AccordionTrigger icon options (same on CollapsibleTrigger and TreeView): icon (any node, turns; null = none) renderIcon({open}) (not turned) iconPosition 'start'|'end'|'none' rotation {closed,open} degrees | false
Collapsible open defaultOpen onOpenChange(open) disabled trigger (string label or element; children = content) or <CollapsibleTrigger asChild? + icon options>Label</CollapsibleTrigger> <CollapsibleContent>…</CollapsibleContent> (animated height, unmounts closed)
Dialog open defaultOpen onOpenChange(open) (user actions only) dismissible=true (backdrop, Escape, Android back) shorthand: trigger title description actions [{ label onPress? variant? …ButtonProps }] (each closes after); parts: DialogTrigger (wraps 1 pressable) DialogContent DialogHeader DialogTitle DialogDescription DialogFooter DialogClose (wraps 1 pressable)
role=dialog aria-modal, labelled by title; web: focus trap, focus returns to opener; scrolls when tall; ios: 270pt alert; material: radius 28, text buttons at end
Modal Dialog's root props incl. shorthand (trigger title description actions; children = scrolling body) + size fullScreen; or <ModalTrigger> <ModalContent size 'sm'|'md'=default|'lg'|'xl'|'full' fullScreen (default: <600pt wide, all but sm) showCloseButton=true closeLabel='Close'> <ModalHeader><ModalTitle/><ModalDescription/></ModalHeader> <ModalBody> (ScrollView) <ModalFooter> <ModalClose>; nests; web: focus trap + return, Esc, scroll lock. Use for rich content; Dialog for short, AlertDialog to confirm
Drawer same as Modal (shorthand + side size), parts Drawer*; <DrawerContent side 'start'|'end'=default size 'sm'=320|'md'|'lg'|'xl'|'full'> full-height side panel
AlertDialog shorthand: trigger title description confirmLabel='Continue' cancelLabel='Cancel' destructive onConfirm onCancel; or same props/parts (AlertDialogTrigger/Content/Header/Title/Description/Footer) + AlertDialogAction (onPress then closes; variant='destructive') AlertDialogCancel (closes; focused first on web); backdrop never closes it; role=alertdialog
Popover open defaultOpen onOpenChange trigger (shorthand: children = content, plus side align sideOffset arrow presentation accessibilityLabel); or <PopoverTrigger> wraps 1 pressable; <PopoverContent side 'bottom'|'top'|'left'|'right' align 'start'|'center'|'end' sideOffset arrow presentation 'popover'|'sheet' accessibilityLabel>; <PopoverClose>; flips and stays on screen; closes on outside tap, Escape, Android back
Tooltip <Tooltip content="Copy link"><Button size="icon" accessibilityLabel="Copy link">…</Button></Tooltip> side align delayDuration=500 open defaultOpen onOpenChange; web: hover/keyboard focus; touch: long press; optional <TooltipProvider delayDuration skipDelayDuration>. Trigger needs its own name; no interactive content (use Popover)
Toaster mount once, last in the root: position 'top'|'bottom' (default top on iOS, bottom elsewhere) offset insets max=3 duration=4000 closeButton (default web + persistent) closeLabel id
toast(message, { description, action: {label, onPress}, duration (Infinity = stay), id (update in place), toasterId }) → id
toast.success/.error/.warning/.info/.loading toast.dismiss(id?) toast.promise(p, {loading, success, error}) (works outside React; action toasts stay until closed)
WheelPicker<T> items: (T | {label, value, disabled?})[] value onValueChange(value, index) loop itemHeight=40 visibleItems=5
variant '3d'|'flat' keyboardInput=true isEqual renderItem({item,index,selected,theme}) styles
MultiWheelPicker columns: [{ key, items, value, onValueChange, flex?, width?, loop?, suffix? }] separator: node | (leftIndex)=>node (suffix = unit text after a column)
TimePicker value: Date onValueChange(date) format '12h'|'24h'|'auto' minuteInterval showSeconds minTime/maxTime locale
TimeRangePicker value: {start: Date, end: Date} onValueChange(range) minDuration maxDuration (minutes) allowOvernight=true (end before start → next day) startLabel endLabel
+ every TimePicker prop; moving the start keeps the length; TimeRangePickerSheet/Field onConfirm(range); formatTimeRange(range) getTimeRangeSeconds(range)
display 'wheel'(ios) | 'dial'(material clock) | 'input'(typed fields) | 'list'(web columns); default from the design
DurationPicker a length of time, not a time of day: value: number (seconds) onValueChange(seconds) showHours=true showSeconds=false
display 'wheel'(ios) | 'input'(material number boxes) | 'list'(web columns); default from the design
min max (seconds; default max 23h59m59s, or 59m59s without hours) minuteInterval secondInterval loop (minutes/seconds)
labels {hours:'h',minutes:'min',seconds:'s'} formatDuration(5400) → '1 h 30 min'
DateTimePicker value: Date onValueChange(date) display 'wheel'(ios default)|'calendar'(material/web default) minDate maxDate (moments)
timePosition 'beside'|'below' timeDisplay 'wheel'|'dial'|'input'|'list' minuteInterval format locale calendarProps
DatePicker display 'calendar'(default)|'wheel'
mode 'single' value: Date|null onValueChange(date)
mode 'range' value: {start,end} onValueChange(range) minRangeDays maxRangeDays allowSingleDayRange presets (getRangePresets(): Today…Last month chips) presetsProps (ChipGroup props, + variant 'segmented')
mode 'multiple' value: Date[] onValueChange(dates) maxSelections
mode 'ranges' value: DateRange[] onValueChange(ranges) maxRanges minRangeDays maxRangeDays allowSingleDayRange
minDate maxDate isDateDisabled(date) markedDates{'YYYY-MM-DD':{dots?,label?,textColor?,disabled?}}
locale firstDayOfWeek(0=Sun) initialMonth onMonthChange renderDay(state,theme) dayHeight=44
DateWheelPicker value: Date onValueChange order e.g. ['day','month','year'] (default from locale) monthFormat 'long'|'short'|'numeric' min/maxDate
MonthPicker a month without a day: value: Date (first of the month) onValueChange(month) display 'wheel'(ios: month+year wheels) | 'grid'(material/web: months under the year, tap the year for years)
minDate maxDate (any day in the month) yearRange monthFormat 'long'|'short'|'numeric' (wheels) locale
WeekStrip one week of days in a row: value: Date|null onValueChange(date) swipe/arrows page weeks onWeekChange(weekStart) initialWeek
ExpandableCalendar a WeekStrip that opens into its month (drag down, the month follows the finger, or the handle: iOS grabber, chevron in Material/web) and folds back (drag up)
value onValueChange expanded/defaultExpanded=false/onExpandedChange initialDate onWeekChange (folded) onMonthChange (open)
opens into the selected day's month; folds into the selected day's week, else today's, else the 1st; picks a day only, list events yourself
minDate maxDate isDateDisabled markedDates firstDayOfWeek locale showHeader formatTitle(weekStart) weekdayFormat renderDay (calendar's day cells and slots)
Select<T> options: {label,value,description?,icon?,group?,disabled?,keywords?}[] value (controlled) | defaultValue (uncontrolled) onValueChange(value, option) open defaultOpen onOpenChange(bool)
multiple → value T[], onValueChange(values, options), maxSelected, chips
label placeholder searchable(dropdown: type in field, default on; sheet: >8 auto) clearable+onClear (single: reset value in onClear) renderTrigger({open,selected,disabled,error}) renderChevron({open,theme})
error (string|boolean: red field, message under it) helperText required (asterisk) — display only, set error from your form library
presentation 'auto'(dropdown on web, bottom sheet on native)|'bottomSheet'|'modal'|'dropdown'|'inline'(expands under the field)
onCreate(text) → option|void: an 'Add "text"' row while no label matches the search; add the option to options and return it to select it createLabel(text)
SelectList<T> same list inline: options value onValueChange multiple listHeight
server search: loadOptions(query) => Promise<options> (debounced by searchDebounce=300ms, loader until results, stale answers ignored; options = shown before typing; searchPrompt='Type to search' when none, emptyText after an empty search)
or manual: onSearchChange(query) + loading + onEndReached; loadingText renderLoading(theme); no local filtering with either
CountryPicker a Select with ~250 countries built in: value CountryCode ('IL') or CountryCode[] with multiple onValueChange(code, option)
preferred (pinned on top) countries exclude showDialCode locale (names via Intl.DisplayNames, English fallback; search matches English/native names, ISO code, +dial)
every Select prop except options/loadOptions/server search; getCountry(code) → {code,name,nativeName?,dialCode,flag,keywords} getAllCountries() getCountryFlag(code)
LanguagePicker a Select with 86 languages built in: value LanguageCode, a BCP 47 tag ('es', 'pt-BR', 'zh-Hant'), or LanguageCode[] with multiple
each row: the language's own name ('Español') with its name in locale below ('Spanish', Intl.DisplayNames, English fallback), sorted by that name
languages exclude preferred preferredLabel allLanguagesLabel locale; search matches either name and the tag
showFlag=true (emoji flag of the country it's most spoken in: es → 🇪🇸) flags={{ en: 'GB' }} to change some
getLanguage(tag) → {code,name,nativeName,country,rtl} getAllLanguages() getLanguageName(language, locale) isRtlLanguage(anyTag)
PhoneField phone number input: flag + calling code button (CountryPicker list) then the number, formatted as typed ('(201) 555-0123', '54-123-4567')
value/defaultValue: E.164 string ('+972541234567', '' when empty) onValueChange(value, {country, nationalNumber, valid}) valid = length fits the country
country/defaultCountry='US'/onCountryChange label placeholder(default example) disabled error helperText required presentation countrySheetTitle='Country code' sheet
preferred countries exclude locale preferredLabel allCountriesLabel; styles: label field input countryButton dialCode chevron helperText
a leading trunk 0 is dropped (not IT/SM/VA); pasting '+44…' switches country; ~50 country formats, others grouped in threes
utils: parsePhone(intl, current?) → {country?, nationalNumber} formatNationalNumber(digits, code) isValidPhone(digits, code) toE164(digits, code)
TimeZonePicker a Select with all 418 IANA zones built in: value IANA name ('Europe/Lisbon') or string[] with multiple onValueChange(id, option)
label = city, description 'GMT+1 · Central European Standard Time' (zone name where the engine has it, else region); sorted by offset
preferred (default: the device's zone, under 'Your time zone'; [] pins none) timeZones (only these) date (offsets for that moment, DST-aware) locale
old names ('Asia/Calcutta', 'Europe/Kiev') accepted as value, reported as current ('Asia/Kolkata'); search matches city, IANA name, region, GMT/UTC offset, zone name
utils: getDeviceTimeZone() getTimeZoneOffset(id, date?) → minutes formatGmtOffset(330) → 'GMT+5:30' getTimeZoneName(id, locale?, date?) normalizeTimeZone(id) getTimeZone(id) getAllTimeZones()
SegmentedControl<T> / ChipGroup<T> (same props) items: {label,value,disabled?,icon?}[] (icon: node or ({selected,disabled,color}) => node) value onValueChange(value, item) iconPosition 'left'|'right'|'top'|'bottom' showArrows (‹ › scroll buttons, default false) arrowPosition 'outside'|'overlay' (default 'outside') renderArrow(side, disabled) renderItem (tap at the edge scrolls the next item into view)
EmojiPicker onSelect(emoji, data) columns=8 height=380 categories exclude maxEmojiVersion skinTone (✋ button: every emoji; long-press: one emoji's tones, skinTone unchanged) recent onRecentChange categoryBarPosition 'auto'(bottom on ios/material, top on web)|'top'|'bottom'
ColorPicker value: hex ('#E4572E', or '#E4572E80' with showAlpha) onValueChange('#RRGGBB'|'#RRGGBBAA', fires while dragging)
display 'tabs'(ios: Grid/Spectrum/Sliders) | 'swatches'(material: circles + Custom) | 'spectrum'(web: square, hue, hex, eyedropper); default from the design
colors (hex | {value,label})[]=DEFAULT_COLORS showCustom=true showAlpha=false onCopy(hex) (copy button; web clipboard by default, native needs it, e.g. expo-clipboard) labels normalizeHex hexToHsv hsvToHex withAlpha
Slider value: number onValueChange(value) (on release, or a key/screen-reader step) onValueChanging(value) (every step while dragging) min=0 max=100 step=1 (0: continuous)
range → value [start,end], onValueChange([start,end]), thumbLabels=['Minimum','Maximum']; a touch grabs the nearest thumb, thumbs never cross
showSteps (dots per step) marks (number | {value,label})[] (dots + labels under the track) snapToMarks (only the marks) valueLabel 'never'|'drag'|'always' (default 'drag' Material, else 'never') formatValue(v) (bubble + screen readers) minimumIcon maximumIcon (nodes beside the track) disabled
looks: ios white knob on a 4pt track | material M3 bar handle, 16dp track, gaps, stop dots | web 18px dot on a 6px track; web: pointer cursor + a halo on hover/focus/press; slots container track activeTrack thumb mark markLabel valueLabel valueLabelText
InputOTP value: string (the code so far) onValueChange(code) (typing, deleting, pasting) onComplete(code) (last cell filled) length=6 inputMode 'numeric'|'text' (digits on a number pad | letters and digits) secureTextEntry (dots) autoFocus disabled error (string|boolean: red boxes, message under them) helperText accessibilityLabel='Verification code'
one hidden TextInput over the cells: paste and SMS autofill work (oneTimeCode on iOS/web, sms-otp on Android); a pasted message keeps only the code chars; no ref: clear with value='', blur with Keyboard.dismiss() in onComplete
cells look like the design's text fields; slots container cell focusedCell filledCell cellText caret
Rating value: number onValueChange(value) (tap, end of a drag, key/screen-reader step) max=5 step=1 (0.5: half stars) size=32 color='#FFB400' (filled) emptyColor=theme border
readOnly (shows any fraction, e.g. 4.3; no touches) disabled renderIcon({index,filled,color,size}) (drawn empty + filled, cut to the value; default ★ text, no SVG) formatValue(v,max)='3 of 5' accessibilityLabel='Rating'
adjustable for screen readers; arrows step, Home 0, End max; web: pointer previews the value; RTL; the row stretches like a View (stars at its start, taps past them ignored; alignSelf:'center' to centre); slots container item icon
Carousel children (one slide each) value defaultValue onValueChange(index) (swipe/arrow/dot/key/autoplay settle; not on value change) itemWidth '100%'|'85%'|number (peek) align 'center'|'start' gap (theme md) loop autoplay true(4000)|ms (pauses on touch/hover/focus; off with reduce motion)
showIndicator=true (dots follow the finger) showArrows (default web) orientation 'horizontal'|'vertical' scrollEnabled accessibilityLabel (role region) labels {previous,next,slide:'Slide {page} of {count}'} slots container item indicator arrow
paging ScrollView: native swipe on iOS/Android, CSS scroll snap on web; web: focus + arrows/Home/End; phones: dots are one adjustable control. Replaces react-native-reanimated-carousel
Pager Carousel with full-size pages: gap=0 showIndicator=false showArrows=false, no itemWidth/loop/autoplay; give it a height (style flex:1). Replaces react-native-pager-view (initialPage→defaultValue, onPageSelected→onValueChange, setPage→value)
PageIndicator count value onValueChange (tap a dot / screen-reader step) label — dots for a Pager or your own steps
QRCode value (UTF-8) size=200 errorCorrection 'L'|'M'(default)|'Q'|'H'(default with logo) color='#000' backgroundColor='#fff' (dark mode too: scanners need dark on light) quietZone=4 (modules) logo (node, centred, modules cleared) logoSize=0.22 (≤0.3) onError (too long: draws nothing) accessibilityLabel='QR code'
createQRCode(text, {errorCorrection, minVersion, mask}) → {version,size,modules[y][x]} for your own SVG/PDF. Pure TS, ISO 18004 byte mode, versions 1–40, plain Views. Replaces react-native-qrcode-svg
SortableList<T> data keyExtractor renderItem({item,index,isActive}) onReorder(nextData, {from,to}) activation 'longPress'|'handle' getItemLabel(item) (screen readers) disabled onDragStart labels {moveUp,moveDown,moved,keyboardHint} + ScrollView props
<SortableHandle/> inside a row lifts it on press (iOS 3 lines, else 6 dots); auto-scrolls near edges; web: focus row, Space pick up, ↑↓ move, Space/Enter/Esc drop (announced); phones: Move up/down actions; not virtualized (hundreds of rows). moveItem(arr, from, to). Replaces react-native-draggable-flatlist
SwipeableRow children (e.g. <ListItem/> inside <List>) trailingActions leadingActions: {label, icon?, variant 'default'|'primary'|'destructive', color?, onPress}[] (first = edge) fullSwipe (long swipe runs the edge action) backgroundColor (default List fill) disabled onOpenChange(side|null)
one open row app-wide; tap an open row closes it; phones: screen readers reach the action buttons; web: focus row, ←/→ open, Esc close. Replaces react-native-swipe-list-view
ImageViewer images: {source, alt?}[] open onOpenChange value defaultValue onValueChange(index) swipeToClose=true labels {close,previous,next,image}
swipe between, pinch / double-tap zoom, pan when zoomed, drag down to close, black backdrop; web: ←/→, + − 0 zoom, Esc, arrow buttons. Replaces react-native-image-viewing
SignaturePad value defaultValue onValueChange(strokes: {x,y}[][]) ([] clears) onBegin onEnd strokeColor strokeWidth=3 height=200 showClear=true disabled labels
plain Views, no WebView/SVG; signatureToSvg(strokes, {width,height,color,strokeWidth,backgroundColor}) → SVG string; signatureToPath(strokes) → path d; isSignatureEmpty. Replaces react-native-signature-canvas
Steps steps: {title, description?, error?}[] value (current index; steps.length = all done) onValueChange (done steps become buttons) variant 'steps'|'progress' (Progress bar + 'Step 2 of 4') orientation 'horizontal'|'vertical' labels {step,completed,error}
BottomSheet open onOpenChange(false on backdrop/swipe/Back/Escape) title headerLeft headerRight footer height(<=1 fraction | px) enableSwipeToClose draggable(header drags too; native:true web:false; handle always drags) expandable expandedHeight showHandle=true showCloseButton=true(✕ on the centered modal) closeLabel='Close'(backdrop's and ✕'s screen reader name)
ActionSheet open onOpenChange actions: {label, onPress?, description? (2nd line), icon?, selected? (✓), destructive? (theme colors.danger), disabled?, testID?}[] title message showCancel (default true on iOS design, false Material/web) cancelLabel='Cancel' presentation sheetProps
a tap calls onOpenChange(false), then runs the action's onPress after the sheet has closed (so it can open another modal); iOS: grouped cards + separate Cancel; Material/web: rows with icons; slots group header title message action actionLabel actionDescription check cancel cancelLabel
DropdownMenu actions (same shape as ActionSheet) children: trigger node (wrapped in a pressable; name it with accessibilityLabel) | ({open, visible}) => your button title align 'auto'(end edge when trigger in right half)|'start'|'end' width=250 iOS/200 presentation 'menu'|'sheet'(ActionSheet) openOnLongPress (context menu) disabled open defaultOpen onOpenChange(bool)
drops under the trigger (above if more room); action onPress runs after it closes; iOS: icons after label + hairlines; pure JS (Expo Go, web); slots trigger menu header title action actionLabel actionDescription check
useActionSheet() → { show(options), hide(), actionSheet }: render actionSheet once, show({title, actions, …ActionSheet props}) from any handler; no provider (like @expo/react-native-action-sheet's showActionSheetWithOptions)
Sheets (draft; commit on Done):
DatePickerSheet open onOpenChange value onConfirm + all calendar props + mode + display + confirmOnSelect
TimePickerSheet open onOpenChange value onConfirm + TimePicker props
TimeRangePickerSheet open onOpenChange value onConfirm(range) + TimeRangePicker props
WheelPickerSheet open onOpenChange items value onConfirm
EmojiPickerSheet open onOpenChange onSelect closeOnSelect=true
ColorPickerSheet open onOpenChange value onConfirm(color) + ColorPicker props
DateTimePickerSheet open onOpenChange value onConfirm + DateTimePicker props
DurationPickerSheet open onOpenChange value onConfirm(seconds) + DurationPicker props
MonthPickerSheet open onOpenChange value onConfirm(month) + MonthPicker props
PickerSheet open onOpenChange onConfirm children + useDraft(value, open, { resetKey?, commit? }) (commit: each change in an inline field)
Fields (a Select-style field that opens the sheet and shows the confirmed value; field owns open state):
DatePickerField / TimePickerField / TimeRangePickerField / DateTimePickerField / DurationPickerField / MonthPickerField / ColorPickerField / WheelPickerField / EmojiPickerField
= the matching *Sheet props WITHOUT open/onOpenChange (value, onConfirm | onSelect, mode, locale, title...)
+ label placeholder='Select…' displayValue(default: value formatted for locale) clearable+onClear(reset value there)
error (string|boolean: red field, message under it) helperText required (asterisk); display only, set error from the form
disabled renderTrigger({open,displayValue,disabled,error}) renderChevron({open,theme}) open defaultOpen onOpenChange(bool) style testID
presentation 'auto'(dropdown on web, bottom sheet on native)|'bottomSheet'|'modal'|'dropdown'|'inline'(expands under the field, no Done: each change fires onConfirm, second tap collapses); design is passed on to the sheet
styles = field slots (label trigger triggerText placeholder chevron clear helperText) + the picker's slots
EmojiPickerField also takes value: string (the emoji shown). Sheet title defaults to label.
PickerField same field props, children: (sheet: {open, onOpenChange}) => <AnySheet {...sheet} .../>
Theme: <PatineProvider colorScheme='auto'|'light'|'dark' theme={...} darkTheme={...} platform?='ios'|'android'|'web' design='brand'|'native'|'ios'|'material'|'web'>; per-component `theme` and `design` props. `platform` makes pickers behave as on that OS (preview native in a browser). `design` is the look: 'brand' (default) = one look everywhere; 'native' = ios on iOS, web on web, material elsewhere; sheet actions in the header (ios: Cancel/Done) or footer (material: Cancel/OK), radios for single select and outlined floating-label fields in material, a date headline above Material calendars, TimePicker display: 'wheel' (ios) | 'dial' (material clock dial with a keyboard-entry toggle) | 'input' (typed hour/minute fields) | 'list' (web: hour/minute/AM-PM columns to click); dial and input fall back to wheels with showSeconds. DateTimePicker display defaults: 'wheel' on ios, 'calendar' in material (time input under it) and web (time columns beside it); timePosition 'beside'|'below' overrides where the time goes (beside moves below when both don't fit), timeDisplay 'wheel'|'dial'|'input'|'list' how it's picked. Calendar: ios tints the chosen day, material fills it and rings today with narrow S M T weekdays, web uses filled rounded squares, ripple in material and a dim while pressed on ios/web.
tokens: colors{background,surface,sheet,text,textSecondary,textDisabled,primary,onPrimary,primaryMuted,border,backdrop,indicator,handle,hover,ripple,danger,onDanger,success,warning}
radius{sm,md,lg,full,sheet} spacing{xs..xl} typography{fonts{body,heading,display,numeric,mono: {regular,medium?,semibold?,bold?} family names},sizes{xs..3xl,display,hero},lineHeights?,tracking?,weights{regular,medium,semibold,bold}} density 'comfortable'|'compact' animation{duration}
shadows{none,xs,sm,md,lg,xl}: CSS box-shadow strings, per design (DESIGN_SHADOWS); every shadow reads them (cards xs, knobs sm, menus/popovers/toasts lg, dialogs/modals xl). Override: theme={{ shadows: { lg: '0px 8px 24px rgba(0,0,0,0.2)' } }}; 'none' turns off. stepShadow(level, steps).
Motion: one system for every component: durations 100 (press) / 160 (hover, checkmarks) / theme animation.duration 240 (moves, overlays); a standard ease-in-out for moves, decelerate in, accelerate out; overlays start animating once their first frame is painted. Press: hover tint and dim fade in and out; Button and chips shrink (97% brand/ios, 98% web) and spring back; Material ripples instead. Every animation respects the OS reduce-motion setting (jumps to its end; loops hold still; no press shrink).
Keyboard (web, built in): arrows move focus through calendars, lists and grids by position (RTL-aware) and step wheels, sliders and the dial; Home/End; Esc closes sheets; focus returns to the field.
Slots: every component takes `styles={{ slotName: style }}`.
Utils: toDateKey(d) 'YYYY-MM-DD' local; addDays addMonths isSameDay compareDay isBetweenDays formatDate(d, locale, opts)
searchEmojis findEmoji withSkinTone getAllEmojis; defaultFilter for select search.
Motion hooks: useReducedMotion() useBlink(active, restartKey?) usePulse({active, min, period}) useAnimatedTo useAnimatedToggle usePop usePresence useCollapse useSlideIn timing spring (all still with reduce motion); useControllableState(value, default, onChange). usePlatform(): the platform components behave as on (PatineProvider's `platform`, else Platform.OS; type PlatformOS). ImageViewer is in /lightbox, Pager and PageIndicator in /carousel, SortableHandle in /sortable.
Pro (@patine-ui/pro, paid; RN core only) AI chat, replaces react-native-gifted-chat:
const chat = useChat({ adapter, initialMessages?, loadOlder?(oldest) => Promise<older[]> ([] = no more) }); <Chat {...chat} suggestions emptyState onAttach onCopy />
adapter({ messages, signal }) => string | AsyncIterable<chunk> (may be async; throw = failed + Retry). chunk: string (text) | {type:'reasoning',text} | {type:'tool',id,name,status:'running'|'done'|'error',input?,output?} (same id updates)
Helpers: streamText(fetchResponse) (body as it downloads; RN's own fetch yields once, use expo/fetch to stream) streamServerEvents(res) (SSE data strings, stops at [DONE]) simulateStream(text, {delay, reasoning, signal})
ChatMessage {id, role 'user'|'assistant', text (Markdown, [1] cites sources[0]), reasoning?, reasoningMs?, toolCalls?, steps? {id,label,status 'pending'|'running'|'done'|'error',detail?}[], sources? {id,title,url,snippet?,site?}[], followUps? string[], feedback? 'up'|'down', attachments? {id,name,uri?,mimeType?,size?,progress?}[], status? 'sending'|'streaming'|'done'|'stopped'|'failed', error?, createdAt?}
ChatChunk: string | {type:'text'|'reasoning',text} | {type:'tool',...ChatToolCall} | {type:'step',...ChatStep} | {type:'source',...ChatSource} | {type:'followUps',items}; demoAssistant = a ready demo adapter
Chat (controlled; useChat optional): messages onSend(text, attachments) status 'idle'|'streaming' onStop onRetry(id) onLoadOlder hasOlder loadingOlder suggestions onSuggestionPress onAttach() => files emptyState renderMessage(message, defaultRender) onLinkPress onCopy onRegenerate(id) onFeedback(id, 'up'|'down'|undefined) onEdit(id, text) onSourcePress(source) onFollowUpPress composerTop placeholder keyboardOffset labels renderToolCall(call, message) => node|undefined (a tool's card from call.data) onToolApproval(call, approved) (calls with status 'approval' show Approve/Cancel); tool statuses 'running'|'approval'|'done'|'error'|'denied'
inverted virtualized FlatList (older history keeps scroll position), jump-to-latest button, caret while streaming, KeyboardAvoidingView. ios: reply bubbles; brand/material/web: replies full width.
Parts: Markdown (children, caret, color, onLinkPress; headings, lists, quotes, GFM tables, code fences, inline; only http/https/mailto/tel links open) Reasoning ToolCall {call} ChatSuggestions AttachmentList
Charts (Pro, react-native-svg peer): rows like recharts: data=[{month:'Jan', revenue:120}] ; every chart: height=240 width(fills) showLegend legendPosition 'bottom'|'top' showTooltip renderTooltip(readout) onPointSelect({index,row,label}|null; haptics on scrub) valueFormat 'number'|'compact'|'currency'|'percent'(fractions) currency='USD' valueFormatter loading error emptyLabel rtl accessibilityLabel (+ generated summary) animate (grow in + glide to new data; off with reduce motion) style theme design; tooltip by touch-drag, hover or arrow keys; legend items toggle series (defaultHidden)
cartesian (Line/Area/Bar/Combo): xKey series [{key,label?,color?,dashed?,dashFrom?(index → dashed forecast),type?,axis?}] grid 'value'|'category'|'both'|'none' showXAxis showYAxis minValue maxValue tickCount referenceLines [{value,label?,color?,dashed?}] referenceBands [{from,to,label?,color?}] xFormatter
LineChart/AreaChart curve 'monotone'|'linear'|'step'|'stepAfter'|'stepBefore' showDots true|false|'auto' connectNulls strokeWidth; AreaChart stacked true|'percent' gradient=true (Dates → time axis; null breaks the line)
BarChart stacked true|'percent' horizontal goalKey showValues barWidth=0.72 radius ComboChart series type 'bar'|'line'|'area' axis 'left'|'right' stacked curve rightFormatter
PieChart/DonutChart nameKey valueKey series innerRadius startAngle endAngle (-90/90 = half donut) padAngle showLabels centerLabel RadialChart nameKey valueKey max (number | row field) series centerLabel (activity rings)
GaugeChart value min=0 max=100 segments [{to,color?,label?}] target label startAngle=-120 endAngle=120 thickness=0.16 showNeedle showMinMax color
HeatmapChart data [{date (Date|'YYYY-MM-DD'), value}] dateKey valueKey valueLabel startDate endDate weekStartsOn levels=4 color cellSize=16 showMonthLabels showWeekdayLabels showScale (contribution calendar)
ScatterChart xKey yKey sizeKey (bubbles) groupKey series xLabel yLabel sizeLabel showTrend grid='both' minValue maxValue referenceLines maxRadius FunnelChart nameKey valueKey series percentOf 'first'|'previous' colorful SankeyChart data (a row per flow) sourceKey targetKey valueKey series linkColor 'target'|'source' shareLabel nodeWidth nodePadding; proportionalFlows(sources, targets) RadarChart nameKey series max levels=4 gridShape 'polygon'|'circle' fill
Sparkline data:number[] variant 'line'|'area'|'bar' height=32 color curve showLast StatusTracker data:{status, tooltip?}[] statuses {ok,warning,error,none → {label,color}} height=32 loading (uptime bars)
Free icons: @patine-ui/icons (npx expo install @patine-ui/icons react-native-svg): <Icon name="bell" /> 227 outline icons, same names and props as Pro's Icon (size 'sm'|'md'|'lg'|number, color theme key, strokeWidth, accessibilityLabel, mirror); <Glyph icon={iconBell} /> for one-by-one imports; ICON_META for search. The MCP server's search_icons tool finds names.
Icons (Pro, react-native-svg peer): <Icon name="bell" /> name: IconName (669, camelCase: arrowLeft chevronRight plus x check search settings trash edit copy share download upload filter sliders more cart bag card wallet receipt invoice bank coins chart barChart lineChart user users calendar clock sun cloud smartphone lock shield checkCircle alert info xCircle sparkles agent brain wand mapPin plane heart star …; full list ICONS / ICON_META)
variant 'outline'=default|'solid'|'duotone'|'color' (own palette, for empty states) size 'sm' 16|'md' 20=default|'lg' 24|number color (theme key or CSS; default 'textSecondary') secondaryColor (duotone tint / color fill) strokeWidth=1.5 accessibilityLabel (none = decorative, hidden) mirror (default: directional icons flip in RTL) filled = variant 'solid'
Tree-shakeable: import { iconBell } from '@patine-ui/pro/icons/bell'; <Glyph icon={iconBell} /> (Icon by name ships the whole set)
BrandIcon (Pro): <BrandIcon name="github" /> 147 brand/social logos (x instagram tiktok whatsapp telegram discord youtube spotify google apple github stripe paypal visa figma notion anthropic …; not LinkedIn/Microsoft/Slack/Amazon/OpenAI)
variant 'color'=default (brand hex; black logos use text color in dark mode)|'mono' (textSecondary or color)|'tile' (app-icon tile, white/black logo; Google, Gmail, Drive, Maps, Chrome draw full color in color/tile) size 'sm'|'md'=20|'lg'|'xl' 32|number color shape 'rounded'|'circle'|'square' (tile) accessibilityLabel (BRANDS.github.title)
Tree-shakeable: import { brandGithub } from '@patine-ui/pro/brands/github'; <BrandGlyph brand={brandGithub} /> BRANDS (data by name), BRAND_META (category)
AIChatScreen (Pro): adapter? | onSend(text, history) => Promise<string> title subtitle suggestions (string | {title,description?,icon?,prompt?})[] conversations {id,title,updatedAt}[] activeConversation onConversationSelect onNewChat models {id,label,description?}[] model onModelChange onAttach onCopy onSourcePress
MessengerThread (Pro): messages {id,senderId,text? (*bold* _italic_ ~strike~ `code` ```block``` links @mentions),createdAt,status? 'sending'|'sent'|'delivered'|'read'|'failed',replyTo?,reactions? {emoji,userIds}[],attachments? {id,name,uri?,size?,mimeType?,progress?,thumbnail?,durationMs?,downloaded?}[],voice? {durationMs,waveform?},link? {url,title,description?,site?,image?},location? {latitude,longitude,title?,address?,liveUntil?},contact?,poll? {question,options {id,text,voterIds}[],multiple?,closed?},sticker?,edited?,deleted?,forwarded?,starred?,readBy?/deliveredTo? {userId,at}[],system?}[] users Record<id,{id,name,avatar?,online?,role?}> me group lastReadAt typing string[] onSend(text,{replyTo,attachments}) onReact(id,emoji) onEdit(id,text) editWindowMs onDelete(ids,forEveryone) onForward(ids,targetIds) forwardTargets onPin pinnedIds onStar(ids) onCopy onAttach(kind)→files? attachKinds onSendPoll onVote(id,optionIds) onSendVoice({durationMs,waveform}) onRecordStart onRecordEnd amplitude onPlayVoice playing onOpenLink onOpenAttachment onDownload onOpenLocation onContactAction onLoadOlder hasOlder loadingOlder searchOpen onSearchOpenChange banner labels; long-press (hover on web) for react/reply/forward/copy/edit/pin/star/select/info/delete, swipe to reply, tap a quote to jump, hold mic to record (slide left cancels, up locks)
ConversationList (Pro): conversations {id,title,avatar?,group?,online?,lastMessage?,unread?,muted?,pinned?,typing?}[] me users active onSelect(id) onPin onMute onArchive (swipe actions) header; draft shows "Draft: …"
MessengerComposer (Pro): value onValueChange onSend(text) variant 'pill'=default|'box' (Slack) users me (@ list) context {kind 'reply'|'edit',title,text,onCancel} pending onRemovePending onAttach attachKinds onSendVoice onRecordStart onRecordEnd amplitude footer placeholder labels
ChatDetails (Pro): title avatar subtitle group participants MessengerUser[] messages me muted onMutedChange onSearch onAudioCall onVideoCall onSelectMessage onClose; starred, Media/Files/Links tabs, members
ChannelThread (Pro, Slack-style): messages (thread? {count,userIds,lastReplyAt}) users me lastReadAt typing onSend(text,{attachments}) onOpenThread(id) onReact onEdit onDelete onPin pinnedIds onStar onCopy onAttach plain (thread panel: parent first) header composerFooter; reaction chips, hover toolbar. TeamChatScreen (Pro): the whole Slack-style screen, demo data
DashboardGrid (Pro): renderItem(item,{editing,breakpoint,fullScreen}) layout|defaultLayout {id,type?,x,y,w,h,minW?,maxW?,minH?,maxH?,static?}[] (widest breakpoint, cells) layouts|defaultLayouts {compact?,medium?,expanded?} onLayoutChange(layout,layouts,breakpoint) editing|defaultEditing onEditingChange templates {type,title,description?,icon?,category?,w,h,min/max?}[] (Add widget gallery) galleryOpen onGalleryOpenChange onAdd(item,template) onRemove(item) getItemLabel columns={compact:1,medium:6,expanded:12} breakpoints={medium:640,expanded:1024} (grid's own width) rowHeight=56 gap rtl labels; drag to move, corner resizes, ✕ removes with Undo, arrow keys move and Shift+arrows resize on the web, long-press reorders on phones
Widget (Pro): title subtitle icon period {value,options,onValueChange} onRefresh actions {label,icon?,onPress,destructive?}[] loading skeleton error onRetry empty emptyTitle emptyDescription updatedAt now headerRight footer padded=true children (node or ({width,height})=>node to size a chart); inside DashboardGrid the menu adds Full screen, Duplicate, Remove. NumberTicker value format duration; useDashboardItem()
AnalyticsDashboardScreen (Pro): demo 'ready'|'loading'|'empty'|'error' seed=7 today defaultEditing site; data from analyticsFor(range,seed,filters) → AnalyticsData; ANALYTICS_WIDGETS ANALYTICS_LAYOUT ANALYTICS_LAYOUTS
DataGrid (Pro): rows columns {key,title,value(row),type? text|number|currency|percent|progress|rating|date|boolean|select|status|multiSelect|tags|avatar|link|sparkline,render?,options?,variants?,currency?,max?,format?,href?,image?,subtitle?,series?,aggregate? sum|avg|min|max|count,width?,minWidth?,align?,sortable?,filter? 'text'|string[]|false,pinned? true|'left'|'right',hidden?,editable?,validate(value,row)?,groupable?}[] rowKey accessibilityLabel title paging 'pages'|'scroll'|'infinite' pageSize=25 height initialSort (one or list; shift-click adds) initialGroupBy quickFilters {key,label,match?,count?}[] views {id,name,state}[] defaultViewId onViewsChange bulkActions {label,icon?,destructive?,onPress(ids,{all})}[] rowActions(row)=>{label,icon?,destructive?,disabled?,onPress(row)}[] renderExpanded getChildren(row) onRowPress onCellChange(row,key,value) onCellEdit(row,key,text) onRowReorder(id,toIndex) showTotals rowCount (server mode) onQueryChange({search,sort,filters,filter,quickFilter,groupBy,page,pageSize}) loading onEndReached hasMore error onRetry renderCard onExport(csv) exportName defaultDensity locale. Exports sortGrid(rows,sorts,columns), filterGrid(rows,{columns,search,model}) for mock servers
MapView (Pro): initialCenter {lat,lng} initialZoom=12 fitTo onRegionChange({center,zoom}) onPress(coord) tiles (URL template; default OpenStreetMap, pass a provider for production) attribution muted controls onLocate; children MapMarker {coordinate,anchor 'bottom'|'center',onPress,accessibilityLabel} MapRoute {coordinates,color,width,dashed}; clusterPoints fitBounds
StoreLocatorScreen (Pro): stores Store[] {id,name,area,address,postcode,coordinate,phone,hours (7 days, Sunday first, [openMin,closeMin]|null),services,rating,reviews} location {lat,lng} now onDirections(store) (default Apple/Google Maps, directionsUrl) onCall(store) onChooseStore(store) title='Find a store'; openStatus(store,now)→{open,closingSoon,label} findStores(stores,from,{query,openNow,services},now) STORE_SERVICES
CourierTrackingScreen (Pro): trip TripPlan {id,from,to {name,address,coordinate},courier {name,vehicle,rating,trips,phone},items,total,approach,route,prepare,pickupDwell,speed,arriving} speed=8 (1 with a live feed) startAt=300 onCall onChat onRate({stars,tip,compliments}) onBack onHelp; tripState(trip,t)→{phase,coordinate,heading,eta,remaining,progress} TRIP_STEPS DEMO_TRIP
DispatchScreen (Pro): initialFleet Fleet {vans,orders,clock} onCall(van) onMessage(van) title='Dispatch' subtitle; live map, KPIs, van/order lists, stop timeline, assign and reassign with undo. Pure logic: tickFleet fleetStats attention stopStatuses suggestVans assignOrder reassignStops; useFleetSimulation (swap for your feed)
NotificationCenter (Pro): notifications {id,title,body?,createdAt,read?,kind? 'mention'|'activity'|'system',actor? {name,avatar?},icon?,tone?,context?,actions? {label,primary?,onPress}[],archived?,snoozedUntil?}[] onPress onMarkRead(id) onMarkUnread(id) onMarkAllRead onArchive(id) (+Archived tab) onSnooze(id,until) onOpenSettings loading open/onOpenChange width=400; NotificationInbox = same without the bell
CommandPalette (Pro): open onClose commands {id,label,group,icon,description?,hint?,shortcut? string[],keywords?,children? (opens a page),placeholder?,disabled?,onSelect?}[] source(query,signal)=>Promise<Command[]> recent/defaultRecent/onRecentChange placeholder emptyLabel footer; CommandMenu = same in place; fuzzyMatch(q,text) rankCommands
Navbar (Pro): brand logo? onLogoPress items {key,label,onPress?,menu? {columns {title?,links {label,description?,icon?,badge?,onPress?}[]}[],featured? {eyebrow?,title,description?,icon?,color?,cta?,onPress?},footer? NavbarLink[]}}[] active cta/secondaryCta {label,onPress} actions scrolled (default window scroll) sticky=true maxWidth=1200; useNavbarScroll() → {scrolled,onScroll} for your ScrollView
TreeView (Pro): data: TreeNode[] {id,label,children?,hasChildren? (lazy),disabled?,icon?,data?} expanded defaultExpanded onExpandedChange(ids) selectionMode 'none'|'single'=default|'multiple' (checkboxes; parents cascade, 'mixed') selected defaultSelected onSelectedChange(ids)
loadChildren(node) => Promise<TreeNode[]> onNodePress expandOnPress renderLabel(node,{expanded,selected,checked,level}) icon options indentGuides indent accessibilityLabel style (give a height: virtualized FlatList)
role tree/treeitem; web keys: arrows (WAI-ARIA tree), Home/End, Enter press, Space select. Free alternative for small trees: nested Collapsible.
useUpload (Pro): { upload(file,{onProgress(loaded,total),signal}) => Promise<{url?,response?}>, accept 'image/*,.pdf'|string[], maxSize minSize maxFiles, concurrency=3, autoUpload=true, initialFiles, onReject onComplete onSettled onChange, labels } → { files {id,name,size,type,uri,file?,status 'queued'|'uploading'|'paused'|'success'|'error',loaded,speed,error?,url?}[], add(picked)=>rejections, start pause(id) resume(id) retry(id) remove(id) clear move(from,to) replace(id,file), progress 0–1, busy, rules }. Adapters: xhrUpload(url,{headers,field,method}), mockUpload({speed,fail(name)}) for demos
Dropzone (Pro): controller (useUpload) | onFiles(accepted,rejected) accept maxSize minSize maxFiles multiple paste (web Cmd+V) pickFiles({accept,multiple})=>Promise<PickedFile[]> (native: expo-document-picker/expo-image-picker; web built in) size 'default'|'compact' title description icon showErrors children(fn {dragging,open}) disabled
FileUploadList (Pro): controller density 'default'|'compact' showSummary onPressFile labels. AvatarUploader (Pro): value/defaultValue onChange(uri,file) upload pickFiles cropFile(file,crop)=>Promise<PickedFile> (native, expo-image-manipulator) name size=96 maxSize=5MB removable labels; crops in a circle (web canvas, 512px JPEG). ImageGalleryUploader (Pro): controller (accept 'image/*', maxFiles) columns pickFiles showCover=true sortable=true onPressItem; drag/long-press or Shift+arrows reorder
ImageCropper (Pro): source imageSize? aspect=1 (number | null = free with corner handles) onAspectChange aspects {label,value}[] ([] hides) shape 'rect'|'circle' maxZoom=6 grid 'auto'|'always'|'never' toolbar=true initialCrop onCropChange(CropRect {x,y,width,height,rotation 0|90|180|270,flipX,flipY} in source pixels) height=360 labels. cropToDataUrl(uri,crop,{maxSize,type,quality}) web canvas; native: expo-image-manipulator [crop, flip, rotate]
VideoPlayer (Pro): src poster title tracks {src,label,language,default?}[] (WebVTT) renderVideo({src,poster,style,emit,register}) (native: expo-video VideoView; web uses <video>) aspectRatio=16/9 autoPlay muted loop rates seekStep=5 hideAfter=2500 getThumbnail(time)=>uri onTimeUpdate(s) onEnded labels; keys Space/K, ←/→, J/L, ↑/↓, M, F, C, 0–9
useAudioPlayer (Pro): { track?, autoPlay, adapter(src,emit)=>MediaController (native: expo-audio createAudioPlayer; web HTMLAudioElement), rates, onEnded(track) } → { track, state {playing,currentTime,duration,buffered,rate,waiting,ended,error}, load(track,{autoPlay}), play pause toggle seek seekBy setRate cycleRate }. AudioTrack {id,src,title,artist?,artwork?,duration?,peaks? 0–1[],meta?}
AudioPlayer (Pro): player (shared) | track variant 'card'|'compact' skipBack=15 skipForward=30 onPrevious onNext labels. MiniPlayer (Pro): player onPress onClose skipForward. TrackList (Pro): tracks player numbered
RichTextEditor (Pro): value/defaultValue (RichTextDoc {blocks:[{id,type 'paragraph'|'heading1'|'heading2'|'heading3'|'bullet'|'numbered'|'todo'|'quote'|'code'|'divider'|'image'|'callout',text,marks?[{type 'bold'|'italic'|'strike'|'code'|'link'|'mention',start,end,href?,id?}],checked?,indent?,language?,url?,tone?}]} or a Markdown string) onChange(doc) readOnly placeholder mentions [{id,label,description?,avatar?}] commands (BLOCK_COMMANDS) toolbar ToolbarItem[]|false ('|' divider) toolbarMode 'floating' (web default)|'docked' (phones; iOS input accessory) toolbarEnd showCount reorderable=true onPickImage()=>Promise<url|null> onLinkPress onMentionPress onSubmit (Cmd/Ctrl+Enter) autoFocus menuPlacement 'auto'|'above' scrollEnabled contentPadding labels
Typing: '/' block menu, '@' mentions, '# ' '## ' '### ' '- ' '1. ' '[] ' '> ' '```' '---' at a block's start, **bold** *italic* ~~strike~~ `code` inline; Enter splits, Backspace at start joins/unwraps, Tab nests lists, Cmd+B/I/E/K/Shift+X, Cmd+Z / Shift+Cmd+Z. toMarkdown(doc) fromMarkdown(md): GFM, task lists, callouts as > [!NOTE], mentions as [@Name](mention:id)
CommentComposer (Pro): onSubmit(doc, markdown) (return false to keep the text) value/defaultValue/onChange placeholder mentions toolbar onAttach attachments (node) allowEmpty submitting submitLabel='Comment' footerStart menuPlacement autoFocus disabled labels
Blocks (Pro, from @patine-ui/pro): every block takes design theme density 'compact'|'comfortable'|'spacious' animate (off with reduce motion) labels accessibilityLabel style; data blocks also loading error(string|true) onRetry emptyTitle emptyDescription renderEmpty. State is value/defaultValue/onValueChange-style; callbacks fire for user changes only. Money in cents.
StatsRow items [{key,label,value,previous?,delta? (0.12=+12%),good 'up'|'down',period?,icon?,trend?,description?,valueFormat?}] variant 'cards'|'plain'|'divided'|'tinted' size sm|md|lg columns minTileWidth=160 scrollable valueFormat 'number'|'compact'|'currency'|'percent' currency period showTrend trendVariant value/onValueChange (tiles become tabs) onItemPress renderItem
Timeline items [{key,title,description?,time?,icon?,status 'complete'|'current'|'upcoming'|'error'|'warning',color?,content?}] current (key) variant 'default'|'opposite'|'alternate'|'card' orientation marker 'dot'|'ring'|'icon'|'number' line 'solid'|'dashed'|'none' reverse groupByDay timeFormat 'time'|'date'|'datetime'|'relative' maxVisible expanded/onExpandedChange onItemPress renderMarker renderContent
ActivityFeed items [{id,actor?{name,avatar?},action,target?,timestamp,icon?,color?,type?,content?,unread?,meta?}] variant 'timeline'|'list'|'cards' title groupByDay=true timeFormat 'relative' filters [{value,label}] filter/onFilterChange onMarkAllRead hasMore loadingMore onLoadMore onActorPress onTargetPress renderItem
OrderTracker current (key|index) steps (default Ordered/Shipped/Out for delivery/Delivered) status 'active'|'delayed'|'exception'|'cancelled'|'delivered' orientation variant 'card'|'plain' orderNumber eta deliveredAt carrier trackingNumber onCopyTracking onTrackingPress events [{time,description,location?}] eventsOpen actions
Wizard steps [{value,title,description?,content (node | (wizard)=>node),validate?()=>true|false|message (async ok),optional?}] or <WizardStep value title validate>children</WizardStep>; value/onValueChange onComplete (async: Finish spins) onCancel linear=true indicator 'steps'|'progress'|'dots'|'none' layout 'top'|'sidebar' transition 'slide'|'fade'|'none' renderFooter(wizard {next,back,skip,goTo,index,count,isLast,busy,error})
PricingTable plans [{id,name,description?,price (cents | {monthly,yearly} | null custom),priceLabel?,priceNote?,badge?,highlighted?,current?,featuresTitle?,features (string | {label,value? bool|string,note?,group?})[],cta?}] layout 'cards'|'comparison'|'list' (paywall radios + Continue) billingOptions billing/onBillingChange perMonth value/onValueChange onSelect(plan,billing) footnote renderPlan
ProductCard product {id,title,subtitle?,image?,price,compareAtPrice?,rating?,reviewCount?,badges?,swatches [{value,label,color,image?}],inStock?,stockCount?} variant 'vertical'|'horizontal'|'compact'|'overlay' size favorite/onFavoriteChange swatch/onSwatchChange onPress onAddToCart(product,swatch) quantity/onQuantityChange (stepper once >0) lowStockAt=5 loading renderImage
ReviewList reviews [{id,author{name,avatar?},rating,title?,body,date,verified?,helpfulCount?,images?,variant?,reply?{author,body}}] summary {average,total,distribution} sort 'recent'|'helpful'|'highest'|'lowest' sortOptions ratingFilter/onRatingFilterChange (summary bars filter) onHelpful helpful bodyLines=4 pageSize hasMore onLoadMore onWriteReview onImagePress variant 'list'|'cards'
Kanban columns [{id,title,color?,limit? (WIP)}] cards/defaultCards [{id,columnId,title,description?,tags?[{label,color?}],assignees?,dueDate?,priority 'low'|'medium'|'high'|'urgent',cover?,locked?,data?}] (array order = order in column) onCardsChange(cards,move) onCardMove({card,from,to}) canMove(card,toColumnId) onCardPress onAddCard draggable (drags after 4pt of movement, auto-scroll) dragDelay=0 (ms; e.g. 250 = long press so swipes scroll the board on phones) showMoveMenu (accessible Move to…) columnWidth=280 renderCard; screen-reader actions + web Shift+arrows move cards
EventCalendar events [{id,title,start,end?,allDay?,color?,location?,description?}] view 'month'|'week'|'day' (+defaultView/onViewChange) views date/onDateChange onEventPress onSlotPress(date, allDay) startHour endHour scrollToHour=8 hourHeight=48 height=560 maxEventsPerDay=3 showNowIndicator firstDayOfWeek renderEvent; overlaps side by side
Agenda events (same) date/onDateChange days=14 showWeekStrip showEmptyDays showNowIndicator height (scrolls, sticky day headings) onEventPress renderEvent
Gantt tasks/defaultTasks [{id,name,start,end (last day),progress?,dependencies?,color?,milestone?,assignee?,locked?}] onTasksChange(tasks,change) onTaskChange({task,start,end,kind 'move'|'resize'}) scale 'day'|'week'|'month' columnWidth rowHeight=44 showList listWidth editable (drag bar/end; web arrows, Shift+arrows) showDependencies showProgress startDate endDate
AIUsageMeter used limit (null = unlimited) unit='tokens' valueFormat 'compact'|'number'|'currency' breakdown [{key,label,value,color?}] variant 'card'|'bar'|'ring'|'gauge'|'compact' resetAt warnAt=0.8 dangerAt=1 forecast history onUpgrade showUpgrade
ApprovalCard title description? changes [{label,before?,after}] icon status 'pending'|'running'|'approved'|'denied'|'error' onApprove onDeny approveLabel destructive error announce=true labels (put it in Chat with renderToolCall for a write tool; reversible changes get an Undo toast instead)
AgentActivity steps [{id,kind 'thinking'|'plan'|'search'|'browse'|'tool'|'code'|'file'|'message',title,detail?,status 'pending'|'running'|'waiting'|'done'|'error'|'skipped',startedAt?,endedAt?,durationMs?,input?,output?,sources?,children?}] status title task variant 'card'|'timeline'|'compact' expanded/onExpandedChange collapsed/onCollapsedChange onStop onRetry onApprove onDeny (waiting steps) renderDetail
App layout (Pro), responsive by the width it's given: compact <640 (tab bar), medium 640+ (rail), expanded 1024+ (sidebar), wide 1360+.
AppShell brand {name, mark?, color?} nav {key,label,icon,badge?,dot?,tag?,shortcut? (G then letter),section?,children?}[] active onNavigate(key) tabs? (phone tab keys; default first 4 + More sheet) phoneNav? 'tabs'|'drawer' secondary? NavItem[] userActions? DropdownMenuAction[] actions? (top bar node) collapsed?/defaultCollapsed?/onCollapsedChange (⌘B) user {name,email,avatar?} onSearch insets {top,bottom} commands?/commandSource? (⌘K palette, Navigation group added) workspaces {id,name,mark?,color?,plan?,members?}[] workspace onWorkspaceChange onCreateWorkspace favorites NavItem[] sidebarWidth/defaultSidebarWidth/onSidebarWidthChange (drag 208–400) sidebarFooter (e.g. UsageCard {title,value,max,format?,description?,actionLabel?,onAction?,onDismiss?})
Page title subtitle onBack actions {label,icon,onPress,primary?,disabled?}[] (icon buttons in the top bar on phones, labelled buttons wider) footer (pinned on phones) scroll=true maxWidth=1200
useLayout() → {width, breakpoint, wide, desktop, insets}: the space beside the navigation; branch layouts on wide/desktop, never on Platform.
Panel {title, description, action {label,onPress}, headerRight, flush} StatCard {label, value, delta (0.12 = +12%), good 'up'|'down', period, icon, trend number[]} Grid {columns} fitColumns(width, min, gap, max) Num (tabular figures) StatusBadge {status, label?}
DataTable<T> {columns: {key,title,flex?,width?,align?,sortValue?,render}[], rows, rowKey, accessibilityLabel, renderCard (phones), onRowPress, rowLabel, sort, onSort, selected, onToggle, onToggleAll, allSelected} ← spread useTable(rows, {id, columns, search?, initialSort?}) → {visible, query, setQuery, sort, onSort, selected, onToggle, onToggleAll, allSelected, clearSelection}
QueryState {status 'ready'|'loading'|'error', onRetry, empty, emptyTitle, emptyDescription, emptyIcon, emptyAction, errorTitle, skeleton, inset} CommandPalette {open, onClose, commands {id,label,group,icon,description?,hint?,shortcut?,keywords?,children?,onSelect}[], source?}
AuthShell {brand, headline, quote {text,author,role}, insets, scroll=true} useStack({route, param?}) → {route, param, canGoBack, push, back, reset}
Icon {name, size 'sm'|'md'|'lg'|number, color, filled} IconButton {icon, label (required), onPress, color, variant} formatMoney(cents, currency='USD', locale='en-US', compact)
Pro apps, each one component on sample data (initialRoute, param?, demo 'ready'|'loading'|'empty'|'error', insets) with every screen exported; data screens take rows + status + onRetry, amounts in cents:
CryptoApp (portfolio, welcome, markets, coin detail, swap with fees, receive by QR, activity, security) StoreApp (discover, shop, product, bag, four-step checkout, order tracking, saved, account)
BudgetApp (overview, activity with split, budgets, insights, goals, bills, add expense, settings) FitnessApp (today rings, setup, programs, workout, live session with heart-rate zones, progress, classes, profile)
FoodApp (home, restaurant menu, dish options, basket with tip, live tracking, courier chat, rate, past orders) TravelApp (explore, destination, flights, book with seat map, boarding pass, itinerary, AI planner, shared expenses)
SaasApp (analytics overview, funnels, audience, reports, AI copilot, roadmap Gantt, sprint board, status, billing)
Auth screens for AuthShell: SignInScreen, SignUpScreen + PasswordMeter, VerifyScreen (OTP + resend countdown, useCountdown), ForgotPasswordScreen, NotFoundScreen, OfflineScreen
Canonical examples
import { useState } from 'react';
import {
DatePicker,
DatePickerField,
DatePickerSheet,
DateTimePicker,
PatineProvider,
SegmentedControl,
Select,
TimePicker,
TimePickerField,
WheelPicker,
} from 'patine-ui';
import type { DateRange } from 'patine-ui';
function Examples() {
const [size, setSize] = useState('M');
const [time, setTime] = useState(new Date());
const [date, setDate] = useState<Date | null>(null);
const [range, setRange] = useState<DateRange>({ start: null, end: null });
const [country, setCountry] = useState<string | null>(null);
const [open, setOpen] = useState(false);
const [view, setView] = useState('day');
return (
<>
<WheelPicker items={['S', 'M', 'L']} value={size} onValueChange={setSize} />
<TimePicker value={time} onValueChange={setTime} minuteInterval={5} />
<DateTimePicker value={time} onValueChange={setTime} />
<SegmentedControl items={[{ label: 'Day', value: 'day' }, { label: 'Week', value: 'week' }]} value={view} onValueChange={setView} />
<DatePicker value={date} onValueChange={setDate} minDate={new Date()} />
<DatePicker mode="range" value={range} onValueChange={setRange} />
<Select label="Country" options={[{ label: 'Israel', value: 'IL' }]} value={country} onValueChange={setCountry} />
<DatePickerSheet open={open} onOpenChange={setOpen} mode="range" value={range} onConfirm={setRange} />
{/* In forms: a field that opens the sheet and shows the value, no open state needed */}
<DatePickerField label="Stay" mode="range" value={range} onConfirm={setRange} placeholder="Add dates" />
<TimePickerField label="Time" value={time} onConfirm={setTime} />
</>
);
}
// Optional, once at the root: brand colors, and one design on every platform instead of the native one per OS
export const App = () => (
<PatineProvider theme={{ colors: { primary: '#FF5A5F' } }} design="ios">
<Examples />
</PatineProvider>
);