# For AI assistants

> Machine-readable documentation for Patine UI — llms.txt, llms-full.txt and per-page Markdown — plus a compact usage cheat sheet for code generation.

This documentation is published in machine-readable form, following the [llms.txt](https://llmstxt.org) convention:

| File | Contents |
| --- | --- |
| [`/llms.txt`](pathname:///llms.txt) | Index of every page with a one-line summary |
| [`/llms-full.txt`](pathname:///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](./mcp): `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

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

```tsx
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>
);
```
