` is not a `` — label-styled text with nothing to point `htmlFor` at. React Native has neither element nor association, so it and `Field.Label` would render the same `Text`. **No `errors` array prop.** shadcn's exists to accept react-hook-form and Standard Schema shapes, and this package takes no form dependency. **No type scale in the slots.** The text parts render the `Text` presets and pass a *colour*, never a scale. A `text-sm font-medium` written into a slot here would be a second definition of `Text.Label` that could drift from it — the same reason `Input` ships no label part at all. A test asserts the text slots carry no size, weight or colour. ## Exported constants [#exported-constants] ```tsx import { FIELD_ORIENTATIONS, FIELD_LEGEND_VARIANTS, FIELD_TEXT_PARTS, fieldVariants, resolveFieldTextColor, resolveFieldInteractive, } from "@delacour/native-ui/field"; ``` # Icon (/docs/native/components/icon) ```tsx import { Icon } from "@delacour/native-ui/icon"; import { IconHeart } from "@delacour/native-ui/icons/central"; ; ``` **Sizes:** `xs` 14, `sm` 16, `md` 18, `lg` 20, `xl` 24, `2xl` 32 — the shared icon scale, which `Spinner` reads too. The full guide is [Icons](/docs/native/getting-started/icons); the precedence ladder is in [Sizing](/docs/native/getting-started/sizing#precedence-weakest-first). ## Props [#props] ## Publishing defaults [#publishing-defaults] ```tsx import { IconDefaultsProvider } from "@delacour/native-ui/icon"; {children} ; ``` `Button`, `Badge` and `ListGroup.ItemPrefix` all publish into this, so a bare `` inside one needs nothing at the call site. ## Exports [#exports] ```tsx import { Icon, type IconProps, type IconComponent, IconDefaultsProvider, useIconDefaults, ICON_SIZES, ICON_FALLBACK_COLOR, ICON_FALLBACK_SIZE_CLASS, iconVariants, isIconSize, resolveIconSizeClass, } from "@delacour/native-ui/icon"; ``` # All Components (/docs/native/components) Nineteen components, each on its own import subpath. There is no package-wide barrel — that is what lets an app skip resolving optional peers it never uses. Every component here can be copied into your own repository with the [`delacour` CLI](/docs/native/cli) — `bunx delacour@latest add button`. The name after `add` is the same one as the import subpath. Same components, different delivery: you edit the file rather than upgrade a package. # Input (/docs/native/components/input) ```tsx import { Input } from "@delacour/native-ui/input"; ``` ```tsx ``` **Variants:** `primary`, `secondary`. **Sizes:** `sm`, `md`, `lg` — the box height, the value's type scale and a decorator's icon step, on one axis. ## Groups [#groups] ```tsx $ NZD ``` **The box is one slot with two homes, and that is the whole design.** The `root` slot lands on the `TextInput` when a field stands alone and on `Input.Group`'s row when it does not. A grouped field is therefore the *same* box rather than a similar one — the test sweeps the entire matrix and asserts every chrome utility a lone field wears is present on the group's row. Do not give `Input.Group` a border, background or height of its own. A second class string is a second thing that can drift, and the drift would be a one-pixel difference nobody notices until it is shipped. **The group owns the axes, because it owns the box.** `variant`, `size`, `isInvalid` and `isDisabled` live on `Input.Group`, and an `Input` inside one reads them from context. Pressing the group focuses the field: a lone field is its own tap target edge to edge, but a grouped one only covers the middle of the box. A `Button` inside a decorator still receives its own press. Prefix and suffix share one `decorator` slot and one implementation — they are the same box in different places, and the row's `gap` is what separates them. ## State precedence [#state-precedence] `Input.Group` → the `Input`'s own prop → the enclosing `Field`. Both are `??` chains, so an explicit `false` is a value rather than an absence. **Invalid outranks focus.** A field that went grey the moment it was tapped would drop the only signal it has that its value is wrong, exactly while the value is being corrected. ## Placeholder, caret and selection colours [#placeholder-caret-and-selection-colours] These take a colour *value*, not a style. Uniwind's own `TextInput` accepts a className for each and compiles it to `styles.accentColor` — so this component wraps nothing in `withUniwind`. `accent-muted-foreground`, never `text-muted-foreground`. Uniwind reads only `accentColor` off the compiled class, so anything else resolves to nothing: it warns once in development and leaves the prop undefined, which renders as the platform default rather than as an error. `placeholderTextColorClassName` is `Omit`ed from `InputProps` — Uniwind's name and ours would otherwise both reach the same colour. `selectionColorClassName` keeps Uniwind's name; only its default is supplied here. ## Multiline [#multiline] A multiline field turns its height into a floor, and the row aligns to the top with it — centred decorators would drift down the side of a paragraph instead of sitting on its first line. ## No label, description or error parts [#no-label-description-or-error-parts] `Text.Label` and `Text.Caption` already are those, and a label defined twice is a type scale that can drift. Use [`Field`](/docs/native/components/field) for the surrounding structure. ## API [#api] Extends React Native's `TextInputProps`. `placeholderTextColorClassName` is withheld in favour of `placeholderColorClassName`, which is the name the rest of the library uses. ### `Input.Group` [#inputgroup] Puts a prefix or a suffix inside the input's own border, and publishes the shared axes so the input inside does not restate them. ### `Input.Prefix` / `Input.Suffix` [#inputprefix--inputsuffix] Content drawn inside the group's border, before or after the field. An `Icon` inside one inherits the input's icon size and a muted foreground. # ListGroup (/docs/native/components/list-group) ```tsx import { ListGroup } from "@delacour/native-ui/list-group"; ``` ```tsx Profile Name, photo and handle ``` **Variants:** `default`, `secondary`, `tertiary`, `transparent`. **Sizes:** `sm`, `md`, `lg`. Size is not decoration — it drives the row metrics, the title and description type scale, both icon sizes *and* the divider inset. Those five numbers live in one axis rather than five magic values. ## Dividers are inserted, not written out [#dividers-are-inserted-not-written-out] The root walks its children and puts a `Separator` between adjacent ones, inset to line up with the rows' padding. A `Separator` placed by hand suppresses the automatic one on either side of it, so you can make one gap full-bleed without turning the feature off. `isDivided={false}` turns it off entirely. `Children.toArray` drops the nulls a conditional child leaves behind, so a row rendered only some of the time does not strand a divider. The root clips. `overflow-hidden` is load-bearing: a pressed row fades to the edge of its own box, and the first and last rows would square off the group's corners without it. ## A row is a Pressable [#a-row-is-a-pressable] `ListGroupItemProps` extends `PressableProps`, so `feedback`, `haptic`, `pressedScale` and the rest are inherited rather than restated. Only the default differs: `fade`, because a full-bleed row that scales reads as the whole card flexing rather than as one row responding. ## Slots are flat [#slots-are-flat] `ListGroup.ItemPrefix`, never `ListGroup.Item.Prefix` — the keys are deliberately flat, and the `displayName`s match (`DelacourUI.ListGroup.ItemPrefix`). `ItemPrefix` wraps its subtree in an `IconDefaultsProvider`, so a bare `` needs nothing said. `ItemSuffix` draws a chevron when it has no children of its own; `iconProps` tunes that glyph and is ignored once it does. String children are wrapped in an `ItemContent` around an `ItemTitle` automatically. Title colour goes on the title. The `item` slot carries no `text-*` — a row is a `View` and cannot cascade colour to a `Text`. The tests assert this. ## API [#api] ### `ListGroup.Item` [#listgroupitem] A row. A `Pressable`, so `feedback`, `haptic` and the rest are inherited — only the default differs: `fade`, because a full-bleed row that scales reads as the whole card flexing. ### `ListGroup.ItemPrefix` / `ItemContent` / `ItemSuffix` [#listgroupitemprefix--itemcontent--itemsuffix] The row's three regions. `ItemPrefix` wraps its subtree in icon defaults, so a bare `Icon` needs nothing said at the call site. `ItemSuffix` draws a chevron when it has no children of its own. ### `ListGroup.ItemTitle` / `ItemDescription` [#listgroupitemtitle--itemdescription] The row's two lines of text. Extend React Native's `TextProps`. Title colour goes on the title, never on the row. A row is a `View`, and a React Native `View` does not cascade colour to a `Text` descendant the way a DOM element would — so the `item` slot carries no `text-*` at all. The variants tests assert it. # Pressable (/docs/native/components/pressable) ```tsx import { Pressable } from "@delacour/native-ui/pressable"; ``` ```tsx Open ``` ## Feedback [#feedback] `scale`, `fade`, `scale-fade`, `none` — the shared vocabulary, defined once. Every pressable in the library resolves through it rather than keeping a private map: `Button` narrows it, `ListGroup.Item` forwards it whole. `scale-fade` is **composed**, not spelled out: its scale comes from `scale` and its opacity from `fade`, so tuning either single-axis mode carries through. `pressedScale` and `pressedOpacity` win on the axis they name and leave the other to `feedback`. They are the escape hatch for a value the named modes do not cover — `??` is the merge, so an explicit `0` is a value rather than an absence. A bare `Pressable` with no `feedback` presses to `{ opacity: 0.9, scale: 0.97 }`, which fades less than `fade` does. That fallback is unnamed on purpose: naming it would either change what a bare pressable has always done, or force `scale-fade` to fade less than `fade`. ## `disabled` vs `busy` [#disabled-vs-busy] Both block the gesture; only `disabled` announces the control as disabled. Use `busy` for a temporary state the component clears itself, so assistive tech reports a control that is momentarily unavailable rather than one that is inert. Neither applies any opacity — that is the caller's variant's job. ## `asChild` [#aschild] Renders into the single child element instead of emitting a `View`. ## Why there is no `tv()` here [#why-there-is-no-tv-here] Its values are opacity and scale **interpolation targets** read by a worklet on the UI thread (`1 - pressed.value * (1 - targetOpacity)`), not styles. A worklet cannot compile a className, so `tv` is the wrong tool — a deliberate exception, not an oversight. A worklet cannot rely on a module-scope helper. Factoring a shared clamp into a `clampUnit` helper — itself marked `"worklet"` — crashes the UI thread with `undefined is not a function`: it is not captured into the worklet's closure. No unit test sees it, because on the JS thread the helper resolves perfectly. ## Crossing back to JS [#crossing-back-to-js] Use `scheduleOnRN` from `react-native-worklets`, never Reanimated's `runOnJS` — since Reanimated 4 that is a deprecated shim forwarding to exactly this call. ```tsx scheduleOnRN(onPress); // not runOnJS(onPress)() ``` A Biome `noRestrictedImports` rule in `@delacour/biome-config` fails the build on the deprecated names, so this cannot regress quietly. ## Exports [#exports] ```tsx import { Pressable, type PressableProps, type HapticFeedback, PRESSABLE_FEEDBACK, PRESSABLE_FEEDBACKS, PRESSABLE_FEEDBACK_FALLBACK, resolvePressedState, } from "@delacour/native-ui/pressable"; ``` ## API [#api] Every pressable in the library extends this — `Button`, `ListGroup.Item`, `Accordion.Trigger`, `Checkbox` and `Radio` all inherit the vocabulary rather than restating it. `ViewProps` passes through, minus `style`. Neither `disabled` nor `busy` applies any opacity of its own — that is the caller's variant's job. A bare `Pressable` with no `feedback` presses to `{ opacity: 0.9, scale: 0.97 }`, which fades less than `fade` does; the fallback is unnamed on purpose, so naming it could not change what a bare pressable has always done. # DelacourProvider (/docs/native/components/provider) ```tsx import { DelacourProvider } from "@delacour/native-ui/provider"; {children}; ``` Four layers, outermost first: `GestureHandlerRootView` → `SafeAreaProvider` → `KeyboardProvider` → `` beside the children. The full explanation — why the order is load-bearing, why the safe-area provider is seeded, why the keyboard sync is required and why the component is deliberately not idempotent — is in [Provider](/docs/native/getting-started/provider). ## API [#api] ## No gallery route [#no-gallery-route] `DelacourProvider` has no playground screen and no row on its index. The playground's own `_layout.tsx` is its harness, and every route in the app renders downstream of it — a stronger check than a readout page could be. The routes that prove each layer: `/pressable` for the gesture root, `/screen/navbar` for the insets, `/screen/form` for the keyboard. # Radio (/docs/native/components/radio) ```tsx import { Radio } from "@delacour/native-ui/radio"; ``` ```tsx Monthly Annual ``` **Variants:** `primary`, `secondary`. **Sizes:** `sm`, `md`, `lg`. **Orientations:** `vertical`, `horizontal`. ## Anatomy [#anatomy] | Part | What it is | | ----------------- | ------------------------------------------------------------------------- | | `Radio` | One option. A `Pressable` that selects its `value` in the enclosing group | | `Radio.Label` | The option's text, inside the tap target | | `Radio.Indicator` | The dot. Accepts custom children to replace the default glyph | | `Radio.Group` | Owns the selected value and the shared axes | The row puts the indicator **last** — the label leads, the state trails. That is the opposite of `Checkbox`, and it is deliberate: a radio group is read as a list of choices, and a column of leading dots turns the labels into a second column. ## The dot [#the-dot] A spring, not a timing — `RADIO_DOT_SPRING`. A dot that eases in reads as a fade; a dot that springs reads as a selection landing. ## Groups [#groups] The group owns the selected value; a `Radio` inside one takes no `checked` prop. Precedence follows `Checkbox.Group`'s ladder — `own ?? group ?? field ?? default` — for the shared axes. ```tsx import { useRadio, useRadioGroup } from "@delacour/native-ui/radio"; ``` ## Exports [#exports] ```tsx import { Radio, type RadioProps, RADIO_VARIANTS, RADIO_SIZES, RADIO_ORIENTATIONS, RADIO_DOT_SPRING, RADIO_DEFAULT_SIZE, RADIO_DEFAULT_VARIANT, RADIO_LABEL_TEXT_SIZE, } from "@delacour/native-ui/radio"; ``` ## API [#api] A radio is a `Pressable`, so `feedback`, `haptic` and the rest are inherited — see [Pressable](/docs/native/components/pressable). ### `Radio.Group` [#radiogroup] Owns which radio is selected. Extends `ViewProps`. ### `Radio.Indicator` [#radioindicator] The dot. Composed in when a radio holds none of its own; write it out to restyle it or to replace the glyph entirely. ### `Radio.Label` [#radiolabel] The radio's text, wired as its accessible name. Extends React Native's `TextProps`. # Screen (/docs/native/components/screen) ```tsx import { Screen } from "@delacour/native-ui/screen"; ``` ```tsx Settings {children} ``` ## The point of the component [#the-point-of-the-component] **The navbar and footer measure themselves into a Reanimated context, and every scrollable reserves exactly that.** No screen carries a hand-tuned padding number that is right on one device and wrong on the next. The reserves are spacer *views* whose height is an animated style, not content-container padding — padding cannot animate on the UI thread, and the heights are only known after layout. ## Placement, not variant [#placement-not-variant] `overlay` (the default) floats the chrome over the content, which insets itself to match. `static` puts it in the flow. In this package `variant` always means a visual variant, so the axis that decides where a part *sits* gets its own name. A `static` footer is opaque; an `overlay` footer is not — content is meant to scroll under it, and whatever you put inside brings its own surface. ## Parts [#parts] | Part | What it is | | -------------------------------------------------- | ----------------------------------------------------------------- | | `Screen.Navbar` | Pinned top chrome. Compound: `.Title`, `.Subtitle`, `.BackButton` | | `Screen.Content` | The content region between the chrome | | `Screen.View` | A non-scrolling body | | `Screen.Header` | A scrolling header inside the content region | | `Screen.Footer` | Pinned bottom chrome, keyboard-aware | | `Screen.ScrollArea` | A `ScrollView` with the reserves applied | | `Screen.FlatList` / `.SectionList` / `.LegendList` | Virtualised lists, same reserves | | `Screen.ChatList` | An inverted or oldest-first chat list | | `Screen.Loading` / `Screen.Error` | Whole-screen states | ## Chat lists [#chat-lists] `Screen.ChatList` is a discriminated union on `variant`. `legend` (the default) takes chronological oldest-first data and LegendList's own `renderItem`; `flat` is an inverted `FlatList` with newest-first data and React Native's. The two `renderItem` contracts genuinely differ, so each variant exposes its engine's own rather than adapting one into the other — an adapter would have to fabricate the `separators` object RN's signature promises, and nothing would honour it. The footer publishes its real height a commit or two after the list's first layout, and the list has already scrolled to the end by then. Without the seed the newest message hides under the composer — intermittently, which is the worst kind of wrong. ## Borders [#borders] Both hairlines are drawn at rest. `fadeBorderOnScroll` — the same prop name on `Screen.Navbar` and `Screen.Footer` — opts into a scroll-linked ramp instead. The two read **opposite ends of the scroll**: the navbar's answers "is there content above?" and brightens as you leave the top, while the footer's answers "is there content below?" and fades out as the content runs out. One `SCREEN_BORDER_FADE_DISTANCE` drives both. ## Debugging [#debugging] `` paints every layer. Opt-in per screen and deliberately **not** gated behind `__DEV__`, so a reserve can still be inspected on a release build. The green occupancy band's edge must land on the footer's red one; a red sliver past it means the reserve is short. `SCREEN_DEBUG_COLORS` is exported so a composer can paint matching bands. ## Requirements [#requirements] The app must mount [`DelacourProvider`](/docs/native/components/provider) at its root. `Screen` reads the safe-area and keyboard providers, and `` is what keeps the keyboard's shared values honest between screens. Safe-area insets come from `useSafeAreaInsets()`, never from Uniwind's `*-safe` utilities — those compile to `env(safe-area-inset-top)`, which resolves to **zero** on React Native. The class applies, nothing moves, and a navbar draws over the status bar with no error anywhere. ## No navigation dependency [#no-navigation-dependency] `Screen.Navbar.BackButton` takes an `onPress`; wire `router.back()` yourself. `Screen.Footer`'s `isFocused` is the same trade: an app with a router passes `useIsFocused()`, and without one the footer behaves as focused. There is no `Navbar.Action` — `Button` already owns that vocabulary, so a navbar action is ` ``` `Button.Label` names no variant and no size. It reads both. ## The `useX()` hooks [#the-usex-hooks] Every compound root exports a hook so a **custom** child can match the parent without prop drilling. ```tsx import { Button, useButton } from "@delacour/native-ui/button"; function ButtonBadge({ count }: { count: number }) { const { variant, size, isDisabled } = useButton(); return {count}; } ; ``` ## Icons and text inherit [#icons-and-text-inherit] A root that can publish **one** treatment covering its whole subtree does. `Button` and `Badge` wrap their children in both an `IconDefaultsProvider` and a `TextClassProvider`, so a bare `` or `` inside one comes out matching with nothing said at the call site. A root whose parts carry **two** treatments does not publish — one provider cannot serve both. A `ListGroup` row has a title and a description; a navbar has a title and a subtitle; `Screen.Error` has a title and a message. Those keep per-part classes. ## String children are wrapped [#string-children-are-wrapped] React Native crashes on bare text outside a ``, so every component that accepts free-form children wraps a string child in its own label part. ```tsx // is ``` **Consecutive** strings collapse into one label. `Row {i}` is a single piece of text — wrapping each part separately would space them apart by the component's own `gap`. ## State cascades through context, not through selectors [#state-cascades-through-context-not-through-selectors] Uniwind has no `group-*`, no `peer-*` and no `:has()`. Its compiler reads `data-*` off a single flat selector, and its runtime matches them against props on the component carrying the class — so no class on a parent can reach a child. That is why `` reddens the `Input` inside it through a React context rather than through a parent-scoped selector. Do not go looking for a selector-based path; there isn't one. ## Precedence, and why it differs between components [#precedence-and-why-it-differs-between-components] Two ladders exist in the library and they are deliberately different. **`Input.Group` puts itself first**: `group → own prop → field`. It owns the one box a grouped field renders into, and two answers to one question is not a state worth expressing. **`Checkbox.Group` puts the child first**: `own → group → field → default`. It owns no box. It is a state controller that also carries shared defaults, which makes it the same kind of thing as `Field` — a wrapper a control overrides. "Make the group `lg`" and "make this one danger" are different questions and both get an answer. Both are `??` chains and never `||`, so an explicit `isDisabled={false}` opts a child out of a disabled group. ## Writing your own part [#writing-your-own-part] Read the shared state from the component's context hook, and merge the caller's `className` through `cn()`. ```tsx import { cn } from "@delacour/native-ui/lib/cn"; import { useButton } from "@delacour/native-ui/button"; import { Text } from "@delacour/native-ui/text"; export function ButtonHint({ className, ...props }: TextProps) { const { size } = useButton(); return ; } ButtonHint.displayName = "App.ButtonHint"; ``` # Design Principles (/docs/native/getting-started/design-principles) ## Compose, do not configure [#compose-do-not-configure] Icons are children, never props. A `Button` wraps its subtree in an `IconDefaultsProvider` carrying the right size and the variant's foreground colour, so a bare `` inside one needs nothing said at the call site. ```tsx ``` Reach for a compound part before adding a boolean prop. A boolean answers one question; a part answers every question of that shape. ## Text colour goes on the `Text`, never the parent [#text-colour-goes-on-the-text-never-the-parent] A React Native `View` does not cascade colour to a `Text` descendant the way a DOM element does. Every slot set in the library puts `text-*` on its label slot and keeps it off the root. Tests assert this per component. ## Semantic tokens, never raw palette colours [#semantic-tokens-never-raw-palette-colours] Components name `bg-background`, `text-muted-foreground`, `border-input`. Never `bg-neutral-900`, never a `dark:` prefix — the CSS variable swap handles the theme. Where a prop needs a colour *value* rather than a class (an icon's `color`, a gradient stop), use `useThemeColor`. `X-foreground` always means "content drawn on an `X` surface". Keep that meaning when adding a token. ## One scale, indexed at your own step [#one-scale-indexed-at-your-own-step] `SPINNER_SIZES` *is* `ICON_SIZES`, so a spinner can stand in for an icon with nothing moving. A button's `sm`/`md`/`lg` icon is `icon-sm`/`icon-md`/`icon-lg` — indexed, not restated. A `Checkbox`'s square reads the same scale two steps above its own tick rather than minting a private one. A control that shares another's heights still gets its own namespace: `--spacing-input-*` names the same 36/44/52 as `--spacing-button-*` so the two can be retuned independently. A test asserts they stay level, which is the difference between a coupling that is checked and one that is merely hoped for. See [Sizing](/docs/native/getting-started/sizing). ## Pure decisions live where tests can reach them [#pure-decisions-live-where-tests-can-reach-them] `bun test` cannot render components — React Native ships Flow-typed source that Bun's transpiler cannot parse. So every pure decision moves into a `*.variants.ts` file free of React Native imports, where the whole matrix is reachable. `resolveButtonLayout`, `resolveIconSizeClass`, `resolveCheckboxFilled`, `toggleCheckedValue`, `footerOccupancy` — all of them are ordinary functions with ordinary tests. ## No package-wide barrel [#no-package-wide-barrel] Import from the subpath. This is what lets an app skip resolving optional peers it never uses, and it is also what keeps import cycles impossible: a component folder's `index.ts` is its entry point, not a re-export hub. ## Native modules are peers, never dependencies [#native-modules-are-peers-never-dependencies] Two copies of a native module register twice and break at runtime. Every native dependency in this library is a peer, and the granular exports make the optional ones genuinely optional. ## No framework dependency [#no-framework-dependency] The library takes no navigation dependency and no form dependency. `Screen.Navbar.BackButton` takes an `onPress`; `Screen.Footer` takes an `isFocused`. Anything that must import an Expo package lives under `src/expo/` behind an optional peer, so an app on a different navigator keeps the rest of the library. # Icons (/docs/native/getting-started/icons) The library uses [Central Icons](https://centralicons.com) exclusively, re-exported from a single subpath. ```tsx import { Icon } from "@delacour/native-ui/icon"; import { IconHeart, IconPlus, IconTrash } from "@delacour/native-ui/icons/central"; ; ``` Never Lucide, Hugeicons, or any other set. One icon set is what keeps stroke weight, corner radius and optical sizing consistent across every component. ## Icons inherit [#icons-inherit] A bare `` inside a `Button`, `Badge` or `ListGroup.ItemPrefix` needs no `size` and no `color` — the parent publishes both through an `IconDefaultsProvider` wrapping its subtree. ```tsx ``` An explicit `size` or `color` on the icon still wins. See [Sizing](/docs/native/getting-started/sizing#precedence-weakest-first) for the full ladder. ## Publishing defaults yourself [#publishing-defaults-yourself] ```tsx import { IconDefaultsProvider } from "@delacour/native-ui/icon"; ; ``` ## Sizes [#sizes] Named steps are classes on the shared icon scale — `xs` 14, `sm` 16, `md` 18, `lg` 20, `xl` 24, `2xl` 32. A number is an escape hatch that bypasses the class chain entirely. ```tsx ``` A runtime template class is never compiled. ``className={`size-[${n}px]`}`` has nothing in Uniwind's store to look up and silently draws nothing. Use the numeric prop. ## Colours [#colours] `color` takes a theme token name or a literal. ```tsx ``` A Tailwind palette name like `emerald-500` only resolves if some utility class already pulled that variable into the build. Prefer the semantic tokens. ## Why there is exactly one `withUniwind` wrapper [#why-there-is-exactly-one-withuniwind-wrapper] `View`, `Text`, `Pressable` and `Animated.View` already accept `className`. `withUniwind` is only for third-party components, and a given component may only be wrapped once, in one file. Central Icons is the one carve-out and it is already spent: `icon.tsx` wraps a local `IconGlyph` proxy that takes the glyph as **data**, so a single wrapper covers the whole two-thousand-icon set instead of one per glyph. Do not wrap a Central Icon directly, do not wrap the proxy anywhere else, and do not add a second wrapper for `Svg`. The wrapper is also called at **module scope**. In render it would mint a new component type every frame and remount the icon. # Introduction (/docs/native/getting-started) Delacour UI Native is a React Native component library styled with [Uniwind](https://uniwind.dev) (Tailwind CSS v4 for React Native), animated with [Reanimated](https://docs.swmansion.com/react-native-reanimated/), and driven by the [Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/) API. Every component composes rather than configures: you build a button out of a label and an icon, not out of fifteen boolean props. ```tsx import { Button } from "@delacour/native-ui/button"; import { Icon } from "@delacour/native-ui/icon"; import { IconArrowRight } from "@delacour/native-ui/icons/central"; ; ``` The icon above names no size and no colour. The button publishes both to its subtree, so a bare `` inside one comes out matching the label it sits beside. ## The three patterns [#the-three-patterns] Every component in the library is one of three shapes. Knowing which one you are looking at tells you where its styles live and how to extend it. No state. Props map to classes. `Icon` is the reference — it also reads `IconDefaultsProvider`, so a parent can set size and colour for a whole subtree. A root shares `variant`, `size` and `isDisabled` through context with dot-notation parts, plus a `useX()` hook so a custom child can match the parent without prop drilling. Size and variant axes are declared in a `tv()` slot set, never inline at the call site. ## What makes it different [#what-makes-it-different] Icons are children, not props. Loading state swaps the icon it replaces rather than joining it, so nothing shifts when work begins. `Icon` and `Spinner` resolve `md` to the same edge length. A `Checkbox`'s square reads the icon scale two steps up rather than minting its own. Components name `bg-background` and `text-muted-foreground`, never a raw palette colour and never a `dark:` prefix. Swapping the variables swaps the theme. No build step. Uniwind's transform has to run inside your app's Metro pipeline, so the package ships raw `.tsx` and your bundler compiles it. ## Scope [#scope] This library is React Native only — iOS and Android, Expo or bare. It takes no navigation dependency and no form-library dependency. Where a component needs to talk to a router it takes a callback instead: `Screen.Navbar.BackButton` has an `onPress`, not a `router.back()`. ## Next [#next] Install the package, wire up the CSS, mount the provider. The full list, grouped by what they do. # Installation (/docs/native/getting-started/installation) [`delacour`](/docs/native/cli) writes the components into your own repository, so you own and edit `button.tsx` rather than upgrading a package. Same components, different delivery — `bunx delacour@latest init`. This page covers the package. ## Install [#install] The library ships raw `.tsx` — Uniwind's transform must run in **your** app's Metro pipeline, so a precompiled build would arrive with its classNames already dead. That means its native dependencies are peers, not dependencies: two copies of a native module register twice and break at runtime. npm pnpm yarn bun ```bash npm install @delacour/native-ui ``` ```bash pnpm add @delacour/native-ui ``` ```bash yarn add @delacour/native-ui ``` ```bash bun add @delacour/native-ui ``` ### Peer dependencies [#peer-dependencies] Required: ```bash bun add react-native-reanimated react-native-worklets react-native-gesture-handler \ react-native-safe-area-context react-native-keyboard-controller react-native-svg \ react-native-pulsar uniwind tailwindcss @gorhom/bottom-sheet \ @central-icons-react-native/round-outlined-radius-1-stroke-1.5 ``` Optional — resolved only if you import the subpath that needs them: | Package | Needed by | | ---------------------- | --------------------------------------------------------------------- | | `@legendapp/list` | `Screen.LegendList`, `Screen.ChatList` (the default `legend` variant) | | `expo-router` | `@delacour/native-ui/expo/navigation-theme` | | `react-native-screens` | native stack navigation | ## Wire up the CSS [#wire-up-the-css] Import the library's styles into your app's Tailwind entry, then point Tailwind's scanner at the package source. ```css title="global.css" @import "@delacour/native-ui/styles"; @source "../../../../packages/native-ui/src"; ``` Bun symlinks workspace packages, and Tailwind's scanner **cannot follow symlinks**. A `@source` pointing at `node_modules/@delacour/native-ui` resolves to nothing, and every class the library uses is silently dropped from your production build. Point it at the actual directory. The `@delacour/native-ui/styles` barrel is three files: `base.css` (`tailwindcss` + `uniwind`), `tokens.css` (the `@theme` scale) and `theme.css` (the light/dark palette). Import them individually if you need to reorder them. ## Mount the provider [#mount-the-provider] Wrap your app's root — once, around everything. ```tsx title="app/_layout.tsx" import { DelacourProvider } from "@delacour/native-ui/provider"; export default function RootLayout() { return {children}; } ``` `DelacourProvider` is four layers, outermost first: `GestureHandlerRootView` → `SafeAreaProvider` → `KeyboardProvider` → `` beside the children. The order is load-bearing — see [Provider](/docs/native/getting-started/provider) for what breaks at each layer. Without the gesture root, presses stop landing. Silently — no error, no warning. ### Composing the layers by hand [#composing-the-layers-by-hand] Only if your app already has a root stack of its own. `` is **required**, not optional polish, and must be a child of `KeyboardProvider`. ```tsx import { KeyboardStateSync } from "@delacour/native-ui/hooks/use-keyboard-state-sync"; import { GestureHandlerRootView } from "react-native-gesture-handler"; import { KeyboardProvider } from "react-native-keyboard-controller"; import { initialWindowMetrics, SafeAreaProvider } from "react-native-safe-area-context"; {children} ; ``` ## Import from subpaths [#import-from-subpaths] There is no package-wide barrel, and that is deliberate: it is what lets an app skip resolving optional peers it never uses. ```tsx import { Button } from "@delacour/native-ui/button"; import { Icon } from "@delacour/native-ui/icon"; import { IconHeart } from "@delacour/native-ui/icons/central"; ``` ```tsx // This does not exist, and will not be added. import { Button } from "@delacour/native-ui"; ``` ## Verify [#verify] ```tsx import { Button } from "@delacour/native-ui/button"; ; ``` A string child is wrapped in a `Button.Label` for you. If the button renders but does not respond, the gesture root is missing above it. # LLMs.txt (/docs/native/getting-started/llms) Every page here is available as plain Markdown, and the whole site is available as a single file. | Endpoint | What it is | | ---------------------------------- | -------------------------------------------------------------- | | [`/llms.txt`](/llms.txt) | An index of every page, with titles and descriptions | | [`/llms-full.txt`](/llms-full.txt) | Every page's full content, concatenated | | `.md` | Any docs URL with `.md` appended returns that page as Markdown | ```bash curl https://delacour.co.nz/docs/native/components/button.md ``` Content negotiation also works: a request to any docs page with `Accept: text/markdown` is redirected to the `.md` representation. ```bash curl -L -H "Accept: text/markdown" https://delacour.co.nz/docs/native/components/button ``` ## Copying a page [#copying-a-page] Every docs page has a **Copy Markdown** control at the top, next to the title. It copies the source of the page you are reading — frontmatter stripped, code blocks intact — which is the form to paste into a model's context. # Provider (/docs/native/getting-started/provider) Mount `DelacourProvider` once, around everything. ```tsx title="app/_layout.tsx" import { DelacourProvider } from "@delacour/native-ui/provider"; {children}; ``` ## The four layers [#the-four-layers] Outermost first. The order is not stylistic. | Layer | Why it is where it is | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | `GestureHandlerRootView` | Must be an ancestor **native view** of every handler a `Pressable` creates. Its absence is silent — no error, presses simply stop landing. | | `SafeAreaProvider` | Seeded with `initialWindowMetrics`. | | `KeyboardProvider` | Owns one pair of shared animation values for the whole app. | | `` | Must be a **child** of `KeyboardProvider` — it calls `useKeyboardContext()`. | ## Why the safe-area seed matters [#why-the-safe-area-seed-matters] `SafeAreaProvider` renders `null` — not unstyled children, *nothing* — until its native view reports the first `onInsetsChange`. Without the seed, every cold start shows a blank frame. The seed is a snapshot taken at native module init, so it is stale when the app launches into a rotated or split-screen window — stale for exactly one commit, because the native measurement overwrites it. A blank frame on every launch is the worse trade. Pass `initialMetrics={null}` to opt out. A default parameter only fires on `undefined`, so `null` is a value rather than an absence. ## Why the keyboard sync is required [#why-the-keyboard-sync-is-required] `KeyboardProvider` owns exactly one pair of shared animation values for the whole app, and on iOS they are written only from the `will` events. Any teardown that skips one — an interactive dismiss interrupted by navigation, a stack pop, an app suspend — pins them open app-wide. Every screen then renders "keyboard open" over a keyboard that is not there. `Screen.Footer` runs the same repair on mount as a backstop, but the provider-level sync is what keeps the values honest between screens. ## `style` reaches the gesture root, and carries no default [#style-reaches-the-gesture-root-and-carries-no-default] `GestureHandlerRootView` applies its own `{ flex: 1 }` whenever `style` is undefined. Pass a style and that `flex: 1` is gone — include it yourself. ```tsx {children} ``` ## What it deliberately does not do [#what-it-deliberately-does-not-do] **No per-layer escape hatches.** No `gestureHandler={false}`, no `safeAreaProps`, no `keyboardProps`. A boolean that turns off the gesture root has "nothing responds to a press" as its failure mode, which is the least debuggable outcome in the package. And a prop surface that names the layers changes shape every time a layer is added. **Not idempotent.** It does not detect an enclosing copy of itself. Nesting `GestureHandlerRootView` costs a `View`; nesting `SafeAreaProvider` costs a native view; nesting `KeyboardProvider` actually breaks — two pairs of shared values, two sets of native observers. That is also the one layer that cannot be detected, so a guard covering the two harmless layers and missing the harmful one would be worse than none. If you genuinely need a different stack, compose the providers by hand. They are all public from their own packages — see [Installation](/docs/native/getting-started/installation#composing-the-layers-by-hand). # Sizing (/docs/native/getting-started/sizing) Sizes are semantic tokens, not raw utilities. `tokens.css` owns the values in Tailwind's own namespaces, so they compile to ordinary utilities. | Token | Utility | What it sizes | | ------------------------- | ------------------------------ | ------------------------------------------------------------- | | `--spacing-button-*` | `h-button-md`, `w-button-md` | a button's height, and its square footprint when icon-only | | `--spacing-icon-*` | `size-icon-md` | any glyph — `Icon`, `Spinner`, a row's chevron | | `--text-button-*` | `text-button-md` | a button's label, paired with its height | | `--spacing-input-*` | `h-input-md`, `min-h-input-md` | a field's height — fixed on one line, a floor when multiline | | `--text-input-*` | `text-input-md` | a field's value, paired with its height | | `--spacing-navbar-row` | `h-navbar-row` | the navbar's control row, without its safe-area band | | `--spacing-screen-gutter` | `px-screen-gutter` | the gutter `Screen.Header`, `Screen.Navbar` and content share | A token is named for what it sizes, not for an abstract category. A control that shares another's heights gets its own namespace rather than borrowing one — `--spacing-input-*` names the same 36/44/52 as `--spacing-button-*` so a field and the button beside it can be retuned independently. They are meant to stay level, and a test asserts that outright. ## `Icon` and `Spinner` share one scale [#icon-and-spinner-share-one-scale] `SPINNER_SIZES` *is* `ICON_SIZES` — `xs` through `2xl`, 14/16/18/20/24/32pt — so `size="md"` is the same edge length in both and one can stand in for the other with nothing moving. That is what makes a button's loading swap free: both glyphs are drawn at the button's own `size-icon-*` token, so replacing one with the other costs no layout. A component indexes that scale at its own step name rather than restating a number. A `Checkbox`'s square reads it two steps above its own tick — 18/14, 20/16, 24/18 — and the test pins the *offset* rather than the points, so the icon scale can be retuned without the test becoming a transcript of it. ## An icon's size is a class that drives a prop [#an-icons-size-is-a-class-that-drives-a-prop] `CentralIconBase` spreads its props onto `