# nativecn

> nativecn is shadcn for Expo apps: Components, Primitives and Blocks you copy into your app with `nativecn-cli` and own, built so AI agents can build and verify whole mobile apps.

- Every docs page has a markdown twin: append `.md` to its URL.
- The Registry is JSON at https://nativecn.dev/r/styles/<style>/registry.json (index) and https://nativecn.dev/r/styles/<style>/<item>.json (one item, with source).
- The remote MCP server is https://nativecn.dev/mcp (Streamable HTTP, read-only); `npx -y nativecn-cli@latest mcp` is the local one that reads your project's components.json.
- The JSON Schema for components.json is https://nativecn.dev/schema/components.json.

---

## Introduction

Source: https://nativecn.dev/docs

> nativecn is shadcn for Expo apps: Components you copy into your app and own, built so AI agents can build and verify whole mobile apps.

nativecn is **shadcn for the Expo ecosystem**. It is not a component library you install from npm. You run `nativecn-cli`, and the source of each Component is copied into your Expo app, where you own it and edit it freely.

It targets iOS and Android first, and it is built so that AI agents can build, check and fix whole mobile apps with it.

### Principles

- **You own the code.** Components, Blocks and the Theme are plain source files in your app. There is no runtime package to upgrade around.
- **One Theme, the same look on both platforms.** Every Component reads Tokens from the Theme and never hardcodes a colour or size, so iOS and Android match.
- **Plain React Native.** Styling is React Native's `StyleSheet` plus a TypeScript Theme. There is no Tailwind, NativeWind or `className`, and no build-time CSS step.
- **nativecn builds its own Primitives.** Dialogs, sheets, pickers and menus are written by nativecn rather than wrapped native controls, so they follow your Theme and you can edit them.
- **Few dependencies.** Components depend only on the Expo SDK's pinned modules, plus a short list of recorded exceptions (zustand, react-hook-form, zod, @hookform/resolvers and lucide-react-native).
- **Agent first.** Every project gets Rules, Skills and the nativecn MCP server, so an agent knows what exists, how to add it and how to check the result on a device.

### What you get

- **Components**: the reusable building blocks, such as Button, Text, Icon and Container.
- **Blocks**: pre-designed Screens (such as sign-in) and navigation pieces that you install, rename and adapt. Each purpose comes in several Block Variants (`sign-in-01`, `sign-in-02`, …).
- **The Theme**: the single source of truth for every Token in your app: Colour Roles, spacing, radius, the type ramp, elevation and motion. See [Theming](https://nativecn.dev/docs/theming).
- **A Preset**: your project's Style, colours, radius and fonts, chosen once when you create the app. See [Presets & Styles](https://nativecn.dev/docs/presets).
- **The Agent Kit**: Rules, Skills, the nativecn MCP server and the Plugin. See [AI agents](https://nativecn.dev/docs/ai-agents).

### How it works

1. [`nativecn-cli create`](https://nativecn.dev/docs/installation) builds a new Expo app from the nativecn Starter, or `nativecn-cli init` sets nativecn up in an existing one.
2. Your choices are recorded in [`components.json`](https://nativecn.dev/docs/components-json).
3. [`nativecn-cli add`](https://nativecn.dev/docs/cli#add) fetches Registry Items from the nativecn Registry at nativecn.dev and writes them into your app's folders, following your [folder structure](https://nativecn.dev/docs/folder-structure).

### Following shadcn

If you know shadcn, nativecn will feel familiar: the same command names and flags, the same `init`/`create` flow, the same Preset model and builder, the same copy-and-own approach and the same MCP tool shape. nativecn departs from shadcn only where React Native or Expo's own conventions require it:

- `StyleSheet` and a TypeScript Theme instead of Tailwind;
- Expo's folder layout (`src/components`, `src/hooks`, …) instead of `components/ui` and `lib`;
- its own `components.json` shape.

nativecn is **not** compatible with the shadcn CLI, the shadcn MCP or shadcn's registry directory. Use `nativecn-cli` and the nativecn MCP server.

### Requirements

- Expo SDK 57 or newer, with Expo Router. SDK 57 is the permanent support floor.
- Bare React Native apps are not supported.

---

## Installation

Source: https://nativecn.dev/docs/installation

> Create a new Expo app with nativecn, or add nativecn to an existing one.

### Requirements

- **Expo SDK 57 or newer, with Expo Router.** nativecn supports every SDK from 57 to the latest.
- Bare React Native apps are not supported.

The CLI checks this first, before it creates or writes anything. On an older SDK it stops with:

```txt
nativecn supports Expo SDK 57 and newer; SDK <57 is not supported. Upgrade with `npx expo install expo@latest --fix`.
```

### Create a new app

```sh
npx nativecn-cli@latest create my-app
```

The CLI asks for the app name, the [Preset](https://nativecn.dev/docs/presets), the [folder structure](https://nativecn.dev/docs/folder-structure) and which AI agents you use. Then it:

1. fetches the nativecn **Starter**, a base Expo app pinned to the current Expo SDK with no Expo default theming;
2. renames the app (`package.json`, and `name` and `slug` in `app.json`);
3. installs dependencies with your package manager;
4. applies the Preset: writes the Theme's colours, radius and fonts, downloads only the chosen fonts into `assets/fonts/` and adds the `expo-font` Config Plugin;
5. adds the Starter's promo Screen and the Registry Items it uses, plus any items you named;
6. writes [`components.json`](https://nativecn.dev/docs/components-json);
7. writes the [Agent Kit](https://nativecn.dev/docs/ai-agents) for your agents;
8. runs `git init` and makes one commit, `feat: initial commit`.

Name items after the app name to install them straight away:

```sh
npx nativecn-cli@latest create my-app button card
```

`create` is an alias of `init`: in a folder with no app, or with `--name`, `init` creates one.

### Add to an existing app

Inside an Expo app, run:

```sh
npx nativecn-cli@latest init
```

Init asks for the Preset, structure and agents, then writes the Theme, `components.json` and the Agent Kit, plus any items you named. It **never rewrites your existing files and never commits**. Instead it prints two things:

1. **The root Layout snippet** to paste into `src/app/_layout.tsx` (or `app/_layout.tsx`).
2. **Existing files that overlap** with the nativecn Theme, such as Expo's `constants/theme.ts` or `themed-text`. Keep them for now; the `nativecn-theme` Skill can migrate them later.

The root Layout snippet has this shape:

```tsx
<ThemeProvider>
  <KeyboardProvider>
    <Stack />
    <Toaster />
  </KeyboardProvider>
</ThemeProvider>
```

- `ThemeProvider` (from `@/theme`) wraps the whole app. `useTheme()` throws outside it. It also keeps the native window background on the Scheme's background (with `expo-system-ui`, installed with the Theme), so the strips behind the status bar and the Android navigation bar are dark in dark mode and light in light mode.
- `KeyboardProvider` comes from `react-native-keyboard-controller`.
- `<Toaster />` renders once, after the navigator, so Toasts appear above every Screen.

With `--yes`, an agent applies the snippet itself, guided by the `nativecn-setup` Skill.

#### Apps without `src/`

- Init points the aliases at root folders (`@/components` → `components/`) and sets `routes` to `app`.
- If `tsconfig.json` has no `@/*` path alias, Init shows the change and asks before adding it (`--yes` accepts it).
- Init never moves existing files.

### Without a terminal

When there is no terminal to prompt in (for example, an agent running the CLI), the CLI behaves as if you passed `--yes`: it uses your flags, falls back to the defaults for anything missing, and prints every choice it made. Agents should always pass explicit flags.

### Flags

Both `create` and `init` take these flags. See the [CLI reference](https://nativecn.dev/docs/cli#init) for details.

| Flag                                                     | What it does                                                       |
| -------------------------------------------------------- | ------------------------------------------------------------------ |
| `-p, --preset <code>`                                    | Use a Preset short code from the builder, such as `a1Q17B`.        |
| `--style --base --accent --radius --font --heading-font` | Set the Preset with long flags.                                    |
| `--folder-feat`                                          | Use the feature Structure.                                         |
| `--agents <list>`                                        | Agents to set up: any of `claude,codex,cursor,antigravity`.        |
| `--qa-permissions`                                       | Write opt-in auto-approve rules for the Visual QA Loop's commands. |
| `-n, --name <name>`                                      | The app name; creates a new app.                                   |
| `-y, --yes`                                              | Skip prompts and use defaults for anything not given.              |
| `-d, --defaults`                                         | Use the default Preset.                                            |
| `-f, --force`                                            | Overwrite existing configuration.                                  |
| `-c, --cwd <dir>`                                        | The working directory.                                             |
| `-s, --silent`                                           | Print less output.                                                 |

### After installing

- Fonts are embedded by a Config Plugin, so a development build needs a native rebuild (`npx expo run:ios` or `npx expo run:android`). Expo Go works without one.
- Keep `"userInterfaceStyle": "automatic"` in `app.json` (Expo's default, and the Starter's), so the system's dark mode reaches the app and the Scheme can follow it.
- Add Components with [`nativecn-cli add`](https://nativecn.dev/docs/cli#add).
- Ask your agent to build something: it already has the Rules, Skills and MCP server.

---

## components.json

Source: https://nativecn.dev/docs/components-json

> The project file that records your Preset, Structure, aliases and agents.

`components.json` sits at the root of your app. `create` and `init` write it, and `add`, the nativecn MCP server and your agent read it. You need it to use `nativecn-cli add`.

It is nativecn's own file. It looks like shadcn's but is **not compatible with it**: the shadcn CLI would reject it, and that is expected.

```json
{
  "$schema": "https://nativecn.dev/schema/components.json",
  "version": 1,
  "preset": {
    "code": "a0",
    "style": "vega",
    "baseColor": "neutral",
    "accentColor": "neutral",
    "radius": "default",
    "bodyFont": "inter",
    "headingFont": "inherit"
  },
  "structure": "flat",
  "aliases": {
    "components": "@/components",
    "hooks": "@/hooks",
    "utils": "@/utils",
    "theme": "@/theme",
    "screens": "@/screens"
  },
  "routes": "src/app",
  "agents": ["claude", "codex", "cursor", "antigravity"]
}
```

### $schema

The JSON Schema for the file, so your editor can validate it and autocomplete keys.

### version

The version of the file format. It is `1`.

### preset

Your project's [Preset](https://nativecn.dev/docs/presets): the Style, Base Colour, Accent Colour, Radius, Body Font and Heading Font, plus the short `code` that encodes them. `headingFont: "inherit"` means the Heading Font is the same as the Body Font.

The Preset is chosen once and **fixed for the life of the project**. Don't edit this block: `add` uses `preset.style` to fetch Components in your Style, and changing it would leave your app with a mix of Styles. To change the look later, edit your Theme and Component files directly.

### structure

How your app arranges its files: `"flat"` (the default) or `"feature"`. It is set at `create`/`init`, with `--folder-feat` for feature mode. See [Folder structure](https://nativecn.dev/docs/folder-structure).

### aliases

The import aliases that resolve each [Destination](https://nativecn.dev/docs/folder-structure#destinations). `add` writes files to these folders and rewrites the imports in each file to match.

| Alias        | Default        | Holds                                                     |
| ------------ | -------------- | --------------------------------------------------------- |
| `components` | `@/components` | Components, and Primitives that render (in `primitives/`) |
| `hooks`      | `@/hooks`      | hooks                                                     |
| `utils`      | `@/utils`      | helpers                                                   |
| `theme`      | `@/theme`      | the Theme                                                 |
| `screens`    | `@/screens`    | Screen Blocks                                             |
| `features`   | `@/features`   | Features (feature mode only)                              |

There is no `components/ui` and no `lib`. In apps without `src/`, Init points the aliases at root folders instead.

### routes

The folder that holds your Expo Router routes: `src/app`, or `app` in apps without `src/`. It is a folder, not an alias. `add` creates route files for Screen Blocks here.

### agents

The agents whose Rules, Skills and MCP config nativecn manages: any of `claude`, `codex`, `cursor` and `antigravity`. `nativecn-cli agents` uses this list.

### What's not in the file

- **`tailwind`, `rsc`, `tsx` and `iconLibrary`.** nativecn has nothing web-only, and Lucide is its only icon set.
- **`registries`.** There are no third-party or private registries. The nativecn Registry's address is built into the CLI.
- **Installed items.** Like shadcn, nativecn knows what is installed only from the files on disk.

---

## CLI

Source: https://nativecn.dev/docs/cli

> Every nativecn-cli command and flag: init, create, add, agents and mcp.

`nativecn-cli` is the only published nativecn package and command. Run it with `npx`, so you always get the latest version:

```sh
npx nativecn-cli@latest <command>
```

### init

Sets up nativecn in an existing Expo app, or creates a new app. `create` is an alias.

```sh
npx nativecn-cli@latest init [items...] [options]
npx nativecn-cli@latest create [name] [items...] [options]
```

Before anything else it checks for **Expo SDK 57 or newer with Expo Router**, and stops with the upgrade command if the app is older. In a folder without an app, or with `--name`, it creates one from the Starter; inside an app it runs Init. Items named after the command are installed straight away. See [Installation](https://nativecn.dev/docs/installation) for each step.

| Option                  | Description                                                                               |
| ----------------------- | ----------------------------------------------------------------------------------------- |
| `-p, --preset <code>`   | A Preset short code from the builder, such as `a1Q17B`.                                   |
| `--style <style>`       | The Style: `vega` or `nova`.                                                              |
| `--base <colour>`       | The Base Colour, such as `neutral` or `zinc`.                                             |
| `--accent <colour>`     | The Accent Colour, such as `blue` or `violet`.                                            |
| `--radius <radius>`     | `default`, `none`, `small`, `medium` or `large`.                                          |
| `--font <font>`         | The Body Font, such as `inter` or `geist`.                                                |
| `--heading-font <font>` | The Heading Font: `inherit` (the same as the Body Font) or a font id.                     |
| `--folder-feat`         | Use the feature Structure (`"structure": "feature"`).                                     |
| `--agents <list>`       | Agents to set up, comma-separated: `claude,codex,cursor,antigravity`.                     |
| `--qa-permissions`      | Write opt-in auto-approve rules for the Visual QA Loop's device commands. Off by default. |
| `-n, --name <name>`     | The app name. Creates a new app.                                                          |
| `-y, --yes`             | Skip prompts. Anything not given uses its default.                                        |
| `-d, --defaults`        | Use the default Preset: Vega · neutral · neutral · default radius · Inter.                |
| `-f, --force`           | Overwrite existing configuration.                                                         |
| `-c, --cwd <dir>`       | The working directory. Defaults to the current directory.                                 |
| `-s, --silent`          | Print less output.                                                                        |

The option values are listed on [Presets & Styles](https://nativecn.dev/docs/presets). Without a terminal, `init` behaves as if `--yes` were passed and prints every choice.

### add

Adds Registry Items to your app.

```sh
npx nativecn-cli@latest add [items...] [options]
```

```sh
npx nativecn-cli@latest add button card
npx nativecn-cli@latest add sign-in-02 --route "(auth)/sign-in"
```

Items are names only: no URLs, local paths or namespaces. `add` needs a `components.json`; without one it stops with "Run `npx nativecn-cli init` first".

| Option             | Description                                                                      |
| ------------------ | -------------------------------------------------------------------------------- |
| `-y, --yes`        | Skip the confirmation prompt. On its own it **never overwrites** a changed file. |
| `-o, --overwrite`  | Overwrite existing files that differ.                                            |
| `-c, --cwd <dir>`  | The working directory.                                                           |
| `-a, --all`        | Add every Registry Item.                                                         |
| `-p, --path <dir>` | Write Components to this folder instead of `{components}`, for this run only.    |
| `-s, --silent`     | Print less output.                                                               |
| `--dry-run`        | Show the plan (files and packages) and stop.                                     |
| `--diff [path]`    | Compare your files with the latest upstream version. Never writes.               |
| `--view [path]`    | Print the upstream file.                                                         |
| `--feature <name>` | The Feature a Screen Block goes into, in feature mode.                           |
| `--route <path>`   | The route file to create for a Screen Block, such as `(auth)/sign-in`.           |

#### What add does

1. Reads `components.json` for your Style, aliases and Structure.
2. Fetches each item for your Style from the Registry, then its dependencies, recursively. Dependencies come first.
3. Shows the plan: the files and packages. `--dry-run` stops here.
4. Handles existing files: identical files are skipped silently, a changed file gets a prompt, `-o` overwrites all, and `-y` alone never overwrites.
5. Writes each file to its [Destination](https://nativecn.dev/docs/folder-structure#destinations) and rewrites imports to your aliases.
6. Installs packages: Expo SDK packages with `npx expo install`, and the few recorded exceptions (zustand, react-hook-form, zod, @hookform/resolvers, lucide-react-native) at the version range the item pins.
7. Adds any Config Plugins to `app.json`. With `app.config.ts`, it prints the line to add instead of editing your code.
8. Prints a summary, saying clearly when a native rebuild is needed rather than a reload.

#### Screen Blocks

- **Routes.** The CLI asks "Create a route?" with a suggested route (such as `(auth)/sign-in`), a custom one, or skip. Agents pass `--route`. With `--yes` and no `--route`, the suggested route is created only if the file doesn't exist; otherwise it is skipped and the three-line route file is printed. An existing route is never overwritten.
- **Feature mode.** Pass `--feature <name>`. Without it, the Block's category is the default (`auth` for sign-in and sign-up) and the CLI prints where it went. Interactively, it lists your existing Features plus "new feature…".

#### What's installed

Like shadcn, nativecn tracks nothing: what is installed is whatever is on disk. Use `--diff` to see how your copy differs from the latest upstream before updating, and `--view` to read the upstream file.

### agents

Writes or refreshes the [Agent Kit](https://nativecn.dev/docs/ai-agents) (Rules, Skills and MCP config) for your agents.

```sh
npx nativecn-cli@latest agents [options]
```

| Option             | Description                                                               |
| ------------------ | ------------------------------------------------------------------------- |
| `--agents <list>`  | Agents to set up: `claude,codex,cursor,antigravity`.                      |
| `--update`         | Refresh existing Rules, Skills and MCP config to the latest versions.     |
| `--qa-permissions` | Write opt-in auto-approve rules for the Visual QA Loop's device commands. |

If you have edited the nativecn section of `AGENTS.md`, `agents` shows a diff before replacing it.

### mcp

Runs the nativecn MCP server locally, over stdio. `create`, `init` and `agents` write this command into each agent's MCP config, so you rarely run it yourself.

```sh
npx -y nativecn-cli@latest mcp
```

The local server reads your project's `components.json`, so its answers fit your Style, Structure and routes. See [the nativecn MCP server](https://nativecn.dev/docs/ai-agents#the-nativecn-mcp-server) for its tools.

### Environment variables

These exist for developing nativecn itself.

| Variable                | Description                                                        |
| ----------------------- | ------------------------------------------------------------------ |
| `NATIVECN_REGISTRY_URL` | Fetch Registry Items from another Registry, such as a local build. |
| `NATIVECN_STARTER_DIR`  | Build new apps from a local Starter folder instead of fetching it. |

---

## Changelog

Source: https://nativecn.dev/docs/changelog

> What changed in each nativecn release.

nativecn has not been released yet. The first release is 0.1.0. From then on, every release's notes appear here, generated from the same Changesets entries as each package's `CHANGELOG.md` and the GitHub Release.

---

## Theming

Source: https://nativecn.dev/docs/theming

> Tokens, Colour Roles, Scale, Scheme, createStyles and fonts.

The **Theme** is the single source of truth for every Token in your app. Components read Tokens from it and never hardcode colours or sizes, so you change the look of the whole app in one place.

### The Theme files

`create` and `init` write the Theme into `src/theme/` (or `theme/` in apps without `src/`). You own these files.

| File            | Holds                                                                                 |
| --------------- | ------------------------------------------------------------------------------------- |
| `colors.ts`     | the Colour Roles, light and dark                                                      |
| `tokens.ts`     | spacing, radius, the type ramp, elevation, motion, control heights, opacity and fonts |
| `config.ts`     | `fontScaling` (off), `defaultScheme` (`'system'`) and the Scale baseline and clamp    |
| `scale.ts`      | the Scale computation and `scaleValue(n)`                                             |
| `provider.tsx`  | `ThemeProvider`, `useTheme`, `createStyles` and the Scheme store                      |
| `navigation.ts` | Expo Router's navigation theme, derived from the Tokens                               |
| `index.ts`      | the public exports                                                                    |

Edit `colors.ts`, `tokens.ts` and `config.ts` freely. The other files are the Theme's runtime.

### Tokens

A **Token** is a named visual value: a colour, spacing step, radius, type step, shadow or motion value. All values in `tokens.ts` are base values; the Theme adapts them to each device with the [Scale](#scale).

#### Colour Roles

A **Colour Role** is a colour Token with a fixed purpose, defined once for light and once for dark, in hex.

- **Paired with a `…Foreground` role** for content drawn on top: `background`, `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, `success`, `warning`, `info`. For example, `primary` and `primaryForeground`.
- **Unpaired:** `border`, `input`, `ring`, `overlay`.

The Accent Colour of your [Preset](https://nativecn.dev/docs/presets) sets `primary` and `ring`. Every role and its Foreground pair meets WCAG AA contrast (4.5:1) in both Schemes.

To add your own role, such as `brand`, add `brand` and `brandForeground` to both the light and dark objects. The two must keep identical keys. Types are inferred from your files, so the new role type-checks immediately.

#### Spacing

A 4px grid, named like Tailwind's steps.

| Step  | 0.5 | 1   | 2   | 3   | 4   | 5   | 6   | 8   | 10  | 12  | 16  |
| ----- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Value | 2   | 4   | 8   | 12  | 16  | 20  | 24  | 32  | 40  | 48  | 64  |

#### Radius

Every step derives from one base, which your Preset's Radius sets (10 by default).

| Step  | sm  | md  | lg  | xl  | 2xl | full |
| ----- | --- | --- | --- | --- | --- | ---- |
| Value | 6   | 8   | 10  | 14  | 18  | 9999 |

Components also use `borderCurve: 'continuous'` for smooth corners.

#### Type ramp

The `Text` Component's Variants. Weight is chosen by font face, never with `fontWeight`. `display` and `h1`–`h4` use the Heading Font; the rest use the Body Font.

| Variant   | Size / line height | Face     | Letter spacing |
| --------- | ------------------ | -------- | -------------- |
| `display` | 36/40              | Bold     | -0.8           |
| `h1`      | 30/36              | Bold     | -0.6           |
| `h2`      | 24/32              | SemiBold | -0.4           |
| `h3`      | 20/28              | SemiBold | -0.2           |
| `h4`      | 17/24              | SemiBold | 0              |
| `lead`    | 18/28              | Regular  | 0              |
| `body`    | 16/24              | Regular  | 0              |
| `label`   | 14/20              | Medium   | 0              |
| `small`   | 14/20              | Regular  | 0              |
| `caption` | 12/16              | Regular  | 0              |
| `button`  | 15/20              | SemiBold | 0              |

#### Elevation, motion and controls

- **Elevation:** three `boxShadow` levels with light and dark values: `sm` (Card), `md` (raised and pressed surfaces) and `lg` (Toast and overlays).
- **Motion:** durations `fast` 150ms, `base` 250ms and `slow` 400ms; easings `standard`, `enter` and `exit`; Reanimated spring presets `snappy` and `gentle`.
- **Control heights:** `sm` 36, `md` 44, `lg` 52. The minimum touch target is 48 on both platforms; smaller controls extend their tap area with `hitSlop`.
- **Borders:** `default` 1, and `hairline` for separators only.
- **Opacity:** `disabled` 0.5.

### Scale

The **Scale** adapts Tokens to the current device:

```txt
Scale = clamp(shorter screen side ÷ 390, 0.85, 1.25)
```

- It is measured against a 390pt baseline phone. Using the shorter side means rotating the device doesn't change it.
- It is recomputed whenever the window changes (foldables, split screen).
- Scaled values are rounded to the nearest pixel.

| Scales                                 | Doesn't scale               |
| -------------------------------------- | --------------------------- |
| spacing                                | the 48 minimum touch target |
| radius (except `full`)                 | border widths and hairlines |
| control heights                        | shadows                     |
| text size, line height, letter spacing | motion                      |
| icon sizes                             | opacity                     |

The Theme hands Components already-scaled Tokens. For a genuine one-off value in your own code, use `t.scaleValue(n)` (from `useTheme()`) instead of a raw number; `t.scale` is the zoom factor itself. The unscaled base Tokens stay exported.

Phones are the 0.1 target. Tablets work at the 1.25 cap, and `Container` caps content width.

#### Font scaling

System font scaling is **off by default**: Text ignores the OS font-size setting, and nativecn adapts type with the Scale instead, so Components look as designed on every device. Set `fontScaling: true` in `config.ts` to turn it back on. Text size then becomes base × Scale × OS font scale, with the OS factor capped at 1.5× for the `button`, `label` and `caption` Variants. This is a whole-app accessibility decision.

### Scheme

The **Scheme** is whether the light or dark Colour Role values are in use.

- `ThemeProvider` takes `scheme: 'system' | 'light' | 'dark'`, defaulting to `defaultScheme` in `config.ts`.
- `useTheme()` returns the scaled Tokens plus `scheme`, `scale` (the zoom factor), `scaleValue(n)` and `setScheme()`.
- `setScheme()` also sets the native appearance, so system UI such as the keyboard follows.
- The choice is persisted with zustand and AsyncStorage under the `nativecn-theme` key. Only the Scheme is persisted.
- The splash screen stays up until the persisted Scheme and the fonts have loaded, so the wrong Scheme never flashes.
- `useNavigationTheme()` feeds Expo Router's navigation theme, and the status bar follows the Scheme.

For a user-facing switch, add the SchemeSwitcher Component:

```sh
npx nativecn-cli@latest add scheme-switcher
```

### ThemeProvider

`ThemeProvider` is required. It wraps your root Layout (`src/app/_layout.tsx`), which `create` sets up for you and `init` prints a snippet for. `useTheme()` outside it throws a development error that points at the root Layout.

### createStyles

`createStyles` builds a Component's styles from the Theme and returns a hook:

```tsx
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({
  card: {
    padding: t.spacing[4],
    borderRadius: t.radius.lg,
    backgroundColor: t.colors.card,
  },
}));

export function ProfileCard() {
  const styles = useStyles();
  // ...
}
```

Styles are built with `StyleSheet.create` once per Scale and Scheme and cached, never rebuilt on each render. Colours live in the same cached styles, and Variant styles are extra keys. Never style from React Native's `useColorScheme()` directly; read the Theme.

### Fonts

Your Preset picks a Body Font and a Heading Font from eight OFL fonts: Inter, Geist, DM Sans, Figtree, Lora, Source Serif 4, Geist Mono and JetBrains Mono.

- Each font is four static faces (Regular, Medium, SemiBold, Bold) downloaded from nativecn.dev into `assets/fonts/`. Only the chosen fonts are downloaded.
- They are embedded by the `expo-font` Config Plugin in `app.json`, and named in `tokens.ts`. `ThemeProvider` also loads them with `useFonts`, which is what makes Expo Go work.
- Each font carries a small letter-spacing correction for the type ramp.
- After changing fonts, rebuild the native app; a reload is not enough.

nativecn never uses `@expo-google-fonts` packages. To use another font, add its four faces to `assets/fonts/`, update the `expo-font` plugin entry and the font names in `tokens.ts`, and check that its licence allows bundling.

---

## Presets & Styles

Source: https://nativecn.dev/docs/presets

> Style, Base Colour, Accent Colour, Radius and fonts: chosen once, baked into your code.

A **Preset** is your project's one-time design choice: a Style, a Base Colour, an Accent Colour, a Radius, a Body Font and a Heading Font. You pick it at `create` or `init`, it is stored in [`components.json`](https://nativecn.dev/docs/components-json), and it is **fixed for the life of the project**.

### Fixed per project, baked into your code

- **Colours, radius and fonts** are written into your Theme files (`colors.ts` and `tokens.ts`).
- **The Style** is written into each Component's source when you add it. `add` fetches the copy of each Component made for your Style, so you get plain, literal code with no Style lookups at runtime.
- **There is no `apply` command and no runtime Style switching.** Variant props such as `variant` and `size` still work as usual.

After setup you change the look by editing your own files: the Theme, and the Component files you copied. Never edit `preset` in `components.json`, and don't re-add Components with `-o` to get another Style.

### Options

| Setting       | Options                                                                                                                                                                                                               | Default   |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| Style         | `vega` (clean, balanced), `nova` (compact)                                                                                                                                                                            | `vega`    |
| Base Colour   | `neutral`, `stone`, `zinc`, `mauve`, `olive`, `mist`, `taupe`                                                                                                                                                         | `neutral` |
| Accent Colour | `neutral`, `stone`, `zinc`, `mauve`, `olive`, `mist`, `taupe`, `amber`, `blue`, `cyan`, `emerald`, `fuchsia`, `green`, `indigo`, `lime`, `orange`, `pink`, `purple`, `red`, `rose`, `sky`, `teal`, `violet`, `yellow` | `neutral` |
| Radius        | `default` (the Style's own), `none`, `small` (7), `medium` (10), `large` (14)                                                                                                                                         | `default` |
| Body Font     | `inter`, `geist`, `dm-sans`, `figtree` (sans); `lora`, `source-serif-4` (serif); `geist-mono`, `jetbrains-mono` (mono)                                                                                                | `inter`   |
| Heading Font  | `inherit` (the same as the Body Font), or any of the eight fonts                                                                                                                                                      | `inherit` |

#### Style

The **Style** decides every Component's shape and density. 0.1 ships two: **Vega** (clean and balanced, the default) and **Nova** (compact). More Styles will follow after 0.1. Style is unrelated to React Native's `style` prop.

#### Base Colour

The family of greys used by the neutral Colour Roles, such as `background`, `muted` and `border`.

#### Accent Colour

The colour of `primary` and `ring`. shadcn calls this setting "Theme". All 7 × 24 Base and Accent Colour combinations pass WCAG AA contrast for every Foreground pair, in light and dark.

#### Radius

Overrides the base radius that every [radius step](https://nativecn.dev/docs/theming#radius) derives from. `default` keeps the Style's own.

#### Body Font and Heading Font

The Body Font sets body and control text. The Heading Font sets the `display` and `h1`–`h4` Text Variants, and by default is the same as the Body Font. Only the fonts you choose are downloaded into your app. See [Fonts](https://nativecn.dev/docs/theming#fonts).

### Short codes

A Preset can be written as a short code, which the Preset builder on nativecn.dev gives you:

```sh
npx nativecn-cli@latest create my-app --preset a1Q17B
```

The same Preset as long flags:

```sh
npx nativecn-cli@latest create my-app --style nova --accent violet --heading-font lora
```

Any setting you leave out takes its default. The default Preset, Vega · neutral · neutral · default radius · Inter, is the code `a0`; `--defaults` or `--yes` picks it without prompting.

### For agents

Agents translate a request such as "Nova, violet, Lora headings" into flags or a code. They use the nativecn MCP server's `list_preset_options` for the exact option values and `build_preset_code` for the code, and they never fall back to the defaults silently: if you gave no preferences, they confirm the default with you first.

---

## Folder structure

Source: https://nativecn.dev/docs/folder-structure

> Flat and feature Structures, Destinations and the placement rule.

nativecn writes into Expo's recommended project layout, not shadcn's `components/ui` and `lib`. How your app arranges its files is its **Structure**: `flat` (the default) or `feature`. You choose it at `create` or `init`, and it is recorded in [`components.json`](https://nativecn.dev/docs/components-json#structure).

### Flat

Expo's folders only:

```txt
src/
  app/                  routes only (Screens and Layouts)
  components/           Components
    primitives/         Primitives that render
  hooks/                hooks
  utils/                helpers
  theme/                the Theme
  screens/              Screen Blocks, each in its own folder
assets/fonts/           your Preset's fonts
```

- Route files in `src/app/` stay small: a Screen Block lives in `src/screens/<block>/`, and its route file renders it.
- Drawer Blocks go in `src/components/`.
- A Screen Block's private parts stay inside its own folder, such as `src/screens/sign-up-02/components/`.

### Feature

For larger apps, `--folder-feat` adds a layer of **Features**: self-contained areas of your app, such as auth or billing, that each own their components, hooks, Screens and utils.

```sh
npx nativecn-cli@latest create my-app --folder-feat
```

```txt
src/
  app/
  components/  hooks/  utils/  theme/
  features/
    auth/
      components/  hooks/  screens/  utils/
    billing/
      components/  hooks/  screens/  utils/
```

In feature mode:

- nativecn Components and Primitives **always stay global**, in `src/components/`.
- Screen Blocks go to a named Feature: `add sign-in-02 --feature auth` writes to `src/features/auth/screens/sign-in-02/`.
- Without `--feature`, the Block's category is used (`auth` for sign-in and sign-up), and the CLI prints where it went.

### Destinations

A **Destination** is the kind of place a Registry Item's file installs to. `add` resolves each one to a real folder from your aliases and Structure.

| Destination    | flat             | feature (`--feature auth`)  |
| -------------- | ---------------- | --------------------------- |
| `{components}` | `src/components` | `src/components`            |
| `{hooks}`      | `src/hooks`      | `src/hooks`                 |
| `{utils}`      | `src/utils`      | `src/utils`                 |
| `{theme}`      | `src/theme`      | `src/theme`                 |
| `{screens}`    | `src/screens`    | `src/features/auth/screens` |
| `{app}`        | `src/app`        | `src/app`                   |

Which Destination each kind of Registry Item uses:

| Registry Item       | Destination                                             |
| ------------------- | ------------------------------------------------------- |
| Component           | `{components}`                                          |
| Rendering Primitive | `{components}/primitives`                               |
| Hook Primitive      | `{hooks}`                                               |
| Helper              | `{utils}`                                               |
| Theme runtime       | `{theme}`                                               |
| Screen Block        | `{screens}/<block>/`, plus an optional route in `{app}` |
| Drawer Block        | `{components}/drawer-0X/`                               |

In apps without `src/`, the same folders sit at the root (`components/`, `app/`, …).

### The placement rule

The rule agents follow when they place code in your app (it is one of the [Rules](https://nativecn.dev/docs/ai-agents#rules)). It applies equally to components, hooks, utils and Screens.

1. **Follow `structure`.**
2. **Reuse global items first.** If it already exists in `src/components`, `src/hooks` or `src/utils`, use it.
3. **An item used by one Feature lives in that Feature.**
4. **Promote it to global the moment a second Feature needs it**, and update the imports.

### Changing Structure

The Structure is chosen once. nativecn never moves your existing files to change it.

---

## AI agents

Source: https://nativecn.dev/docs/ai-agents

> Rules, Skills, the nativecn MCP server, the Plugin and the Visual QA Loop.

nativecn is built so that AI agents can build whole mobile apps with it and check the result on a real device. Every project gets the **Agent Kit**: the Rules, Skills and nativecn MCP server, with a Plugin for agent hosts.

`create` and `init` write the Agent Kit for the agents you choose with `--agents`. Supported agents are Claude Code (`claude`), Codex (`codex`), Cursor (`cursor`) and Antigravity (`antigravity`). To add agents or refresh the kit later, run:

```sh
npx nativecn-cli@latest agents --agents claude,cursor --update
```

If fetching the Skills fails (for example, offline), `create` and `init` still finish and print how to retry.

### Rules

A **Rule** is a project-level instruction file that constrains how an agent writes code in your app. nativecn writes its Rules into `AGENTS.md` (or appends a nativecn section to yours) and adds `@AGENTS.md` to `CLAUDE.md` for Claude Code. `AGENTS.md` stays under 24 KB.

1. **Styling:** Tokens only, via `createStyles`. No hard-coded colours or sizes; `t.scaleValue(n)` for genuine one-offs. No Tailwind, NativeWind or `className`.
2. **Building blocks:** all text uses `Text`, all glyphs use `Icon`, and Screens are wrapped in `Container`.
3. **Feedback:** never `Alert.alert` or any platform alert. Use nativecn's own `toast()` and Alert Components.
4. **Navigation:** the drawer comes only from `expo-router/drawer`; never install `@react-navigation/*` or the npm package `expo-drawer`. `SegmentedTabs` is for tabs inside a Screen and `TabNavigation` for the bottom bar; neither is Expo Router's `Tabs`.
5. **Dependencies:** `npx expo install` for Expo SDK packages. Anything else: ask the user first.
6. **Storage:** AsyncStorage holds only non-sensitive preferences. Tokens, credentials and personal data go in `expo-secure-store`.
7. **Placement:** follow `structure` and the [placement rule](https://nativecn.dev/docs/folder-structure#the-placement-rule).
8. **The Preset is fixed.** Never change `preset` in `components.json` or try to switch Style.
9. **Adding items:** use the MCP tool `get_add_command` or `nativecn-cli add`. Always pass `--route` for Screen Blocks, and `--feature` too in feature mode. Run `--diff` before updating, and use `-o` only when the user asks for their edits to be replaced.
10. **Forms:** react-hook-form and zod, wired through `FormField`, with fields inside `FocusChain`.
11. **Accessibility:** meet the accessibility checklist. Never remove `role` or `aria-*` props.
12. **After changes:** run `get_audit_checklist` and fix anything it flags.

`AGENTS.md` also lists the Skills, the MCP tools and the key commands.

### Skills

A **Skill** is a packaged set of instructions that teaches an agent one mobile task with nativecn. nativecn ships five. The CLI writes one copy of each to `.agents/skills/<name>/` (read by Codex, Cursor and Antigravity) and links `.claude/skills/<name>` to it for Claude Code (a copy on Windows).

| Skill                          | Use it for                                      | What it teaches                                                                                                                    |
| ------------------------------ | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `nativecn-setup`               | "start a new app", "add nativecn"               | `create`/`init` flags, custom Presets, applying the Init Layout snippet, choosing agents. Carries the Rules for Plugin-only users. |
| `nativecn-build-screen`        | "build a login screen", "add a settings screen" | Picking a Block with `list_block_variants`, adding it with `--route`/`--feature`, composing Components, wiring routes and Layouts. |
| `nativecn-theme`               | "change colours", "dark mode", "different font" | Editing Tokens in the Theme, Scheme switching, migrating Expo's default theme files.                                               |
| `nativecn-component-authoring` | "new component", "add a variant"                | The Component contract, the accessibility checklist, Primitives, `createStyles` and the placement rule.                            |
| `nativecn-visual-qa`           | "match the design", "screenshot and fix"        | The [Visual QA Loop](#visual-qa-loop).                                                                                             |

### The nativecn MCP server

The **nativecn MCP server** tells an agent which Components, Blocks, Block Variants and Themes exist and what they contain, like shadcn's MCP. It is **read-only**: it never writes files or runs the CLI.

| Tool                                        | Returns                                                                                                  |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `list_items`                                | every Component, Primitive and Block, by type and category                                               |
| `search_items`                              | items matching a query (for example, "dark mode toggle" finds SchemeSwitcher)                            |
| `view_items`                                | files, props, Variants and docs, rendered in the project's Style                                         |
| `get_item_examples`                         | ready-to-copy usage examples                                                                             |
| `get_add_command`                           | the exact `nativecn-cli add` command, with the right `--route` and `--feature` for this project          |
| `get_project_config`                        | the project's `components.json`                                                                          |
| `get_audit_checklist`                       | a post-change checklist from the Rules: Tokens only, no `Alert.alert`, the placement rule, accessibility |
| `list_block_variants`                       | the Block Variants for a purpose, with what makes each one different                                     |
| `list_preset_options` + `build_preset_code` | every Style, colour, radius and font, and the short code for a custom Preset                             |

#### Local and remote

- **Local** (`npx -y nativecn-cli@latest mcp`, over stdio) reads your `components.json`, so its answers fit your Style, Structure and routes. This is what `create`, `init` and `agents` configure.
- **Remote** (`https://nativecn.dev/mcp`) is for browsing without a project. It has the same tools except `get_project_config`, and answers with the default settings.

Both fetch live data from the nativecn.dev Registry, cache it for a few minutes, and return a clear error rather than a guess when the Registry is unreachable.

#### MCP config files

The CLI writes one config file per chosen agent:

| Agent       | File                                                               |
| ----------- | ------------------------------------------------------------------ |
| Claude Code | `.mcp.json`                                                        |
| Cursor      | `.cursor/mcp.json`                                                 |
| Codex       | `.codex/config.toml`                                               |
| Antigravity | `.agents/mcp_config.json` (uses `serverUrl` for the remote server) |

For example, `.mcp.json`:

```json
{
  "mcpServers": {
    "nativecn-cli": {
      "command": "npx",
      "args": ["-y", "nativecn-cli@latest", "mcp"]
    }
  }
}
```

Codex loads `.codex/config.toml` only in a trusted project.

To browse without a project, point an agent at the remote server instead. In Claude Code:

```sh
claude mcp add --transport http nativecn https://nativecn.dev/mcp
```

### AI-friendly docs

Everything on nativecn.dev is also available as plain text for agents, generated from the same sources as the pages:

- **Copy for AI**, at the top of every docs page, copies the page as clean markdown.
- **`.md` twins:** append `.md` to any docs URL, e.g. [`/docs/installation.md`](https://nativecn.dev/docs/installation.md).
- **[`/llms.txt`](https://nativecn.dev/llms.txt)** indexes every page and Registry item; **[`/llms-full.txt`](https://nativecn.dev/llms-full.txt)** has every page in one file.
- **Copy to LLM**, on every Component and Block page, copies one item's description, `add` command, props, usage examples and source as a single prompt-ready block. For example, the Pressable Primitive:

### Plugin

A **Plugin** is an agent-host package that bundles the Agent Kit for one-step installation. The nativecn Plugin contains the five Skills and the local MCP server, packaged as a Claude-format marketplace (for Claude Code and Codex) plus Cursor and Antigravity manifests.

Plugins install per user, not per project, so `create` and `init` print the install command for each chosen agent rather than running it. A Plugin can't write `AGENTS.md`, so the `nativecn-setup` Skill carries the Rules and tells the agent to run `init` (or `agents`) the first time it is used in a project.

### Visual QA Loop

The **Visual QA Loop** is an agent-driven design and UX review of your running app, run by the `nativecn-visual-qa` Skill. The agent navigates Screens and User Flows on a device, captures screenshots, judges them against the Reference Design, traces each problem to its root in the code, fixes small and safe problems, and reports the rest.

It is not pixel comparison and not a test runner, and there is no `nativecn-cli qa` command. nativecn provides only the Skill and Rules; the agent drives devices with the platform's own tools: `adb` for Android and `xcrun simctl` for the iOS Simulator.

#### The design folder

All optional, at the root of your app:

```txt
design/screens/<screen>.png        Reference Design images, such as Figma exports (+ <screen>.dark.png)
design/flows.md                    confirmed User Flows
design/expectations.md             your description of Screens that have no image
```

- A **Reference Design** is what a Screen is meant to look like: an image in `design/screens/` when there is one, otherwise your description in `design/expectations.md`.
- A **User Flow** is a confirmed sequence of Screens and actions, such as sign up → verify code → home. The agent derives flows from your code and docs, asks you to confirm or correct them, and saves them in `design/flows.md`.
- For a Screen with no image, the agent asks what it should look like or do and records your answer.
- If a Figma MCP server is connected, the agent also reads the design's real values from it.

#### How the agent judges

At the design-system level, never pixel by pixel:

- spacing on the Token scale;
- typography: the right Text Variant for each role, and a clear hierarchy;
- layout: alignment, safe areas, clipping and overlap;
- Components: the right Component and Variant, with all states present;
- Colour Roles in light and dark;
- misalignment and broken Components;
- **non-functional actions**: every action does something and leads where the User Flow says.

Every confirmed User Flow is checked end to end against the Screens and the code.

#### Fix or report

**The rule:** the agent fixes a problem itself only if the fix is visual-only, stays inside one Screen, uses what already exists (Tokens, Components, Variants) and is easy to undo. Otherwise it reports the problem and waits for you.

| Auto-fixed                                                                          | Reported for you to decide                                                 |
| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| A hard-coded colour → the matching Colour Role                                      | Navigation and flow: where actions lead, routes, missing Screens           |
| Spacing or size off the scale → the nearest Token, or `t.scaleValue(n)`             | Non-functional actions (the intended behaviour can't be guessed)           |
| The wrong Text Variant for its role                                                 | Logic: data, API, state, validation rules, form behaviour                  |
| Misalignment: alignment, a missing `gap`, uneven padding                            | Auth, storage, permissions and security                                    |
| Safe-area and keyboard problems → wrap the Screen in `Container`                    | Theme or Preset changes in `src/theme/`, which affect the whole app        |
| Clipping or overflow: `numberOfLines`, shrink or wrap                               | Edits to shared Components in `src/components/`, which affect every Screen |
| Broken Component usage: a misspelled prop, a wrong Variant, a missing required prop | Packages, `app.json` and config                                            |
| Missing visual states when the data already exists (such as `loading`)              | Copy and content, images and assets                                        |
| Inconsistent icon sizes or colours                                                  | Layout redesigns: moving sections, changing hierarchy, swapping Components |
| Tap targets under 48 → `hitSlop`                                                    | Deleting code or features                                                  |
| Accessibility gaps: a missing `role` or label                                       | A design that conflicts with the Rules, or an unclear design               |

Limits on auto-fixes:

- Each stays within one Screen file and its private parts.
- A fix needing more than about 30 changed lines becomes a report.
- After fixing, the agent captures the Screen again to confirm. A fix that doesn't hold after three attempts is reverted and reported.
- The agent **never commits**. Auto-fixes stay uncommitted for you to review.

#### The report

Shown in chat and saved as `report.md` in the run's temp folder. Each finding gives where (the Screen and file:line), what's wrong, the root cause in the code, options with trade-offs (one recommended), the severity (broken, wrong or polish) and the status (auto-fixed or awaiting you).

#### Allowed device commands

The agent opens, navigates and screenshots **only the app under development** (its scheme, package and bundle id from `app.json`, or Expo Go's `exp://` URL), using only these commands. Nothing else on the device unless you ask.

| Purpose        | Android (`adb`)                                                                                   | iOS Simulator (`xcrun simctl`)                                                            |
| -------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| list devices   | `adb devices -l`                                                                                  | `xcrun simctl list devices booted -j`                                                     |
| open a Screen  | `adb shell am start -a android.intent.action.VIEW -d <scheme>://<route> -p <package>`             | `xcrun simctl launch booted <bundleId>`, `xcrun simctl openurl booted <scheme>://<route>` |
| navigate       | `adb shell input tap`, `swipe`, `text`, `keyevent BACK`; `adb exec-out uiautomator dump /dev/tty` | deep links only                                                                           |
| screenshot     | save, pull, delete (below)                                                                        | `xcrun simctl io booted screenshot <tmp>/…`                                               |
| light and dark | `adb shell cmd uimode night yes` / `no`                                                           | `xcrun simctl ui booted appearance dark` / `light`                                        |
| status bar     | demo mode, via `adb shell settings` and `am broadcast`                                            | `xcrun simctl status_bar booted override --time 9:41 --batteryLevel 100`                  |

Android screenshots are saved, pulled to your computer, then deleted from the phone, every time:

```sh
adb shell screencap -p /sdcard/nativecn-qa.png
adb pull /sdcard/nativecn-qa.png <tmp>/nativecn-qa/<device>/<timestamp>-<screen>.png
adb shell rm /sdcard/nativecn-qa.png
```

- With exactly one Android device attached, commands leave out `-s`. With several, the agent adds `-s <serial>` and you are asked to approve.
- iOS commands use `booted` instead of a Simulator id. iOS flows use deep links plus reading the code, since there is no tap tool.
- Screenshots go to `<OS temp>/nativecn-qa/<device>/`, and only the last 20 per device are kept. Nothing is left on the phone.
- Installing apps, clearing data, `adb push`, other `adb shell` commands, and automation tools such as Maestro are out of scope.

#### --qa-permissions

By default your agent asks before each device command. To skip those prompts, opt in when you run `init` or `agents`:

```sh
npx nativecn-cli@latest agents --qa-permissions
```

It writes auto-approve rules for exactly the commands above:

| Agent       | Where                                                                 |
| ----------- | --------------------------------------------------------------------- |
| Claude Code | `.claude/settings.json`                                               |
| Codex       | `.codex/rules/*.rules` (loaded only in trusted projects)              |
| Cursor      | `.cursor/permissions.json` and `.cursor/cli.json`                     |
| Antigravity | a snippet is printed for your settings; it has no project-level rules |

- **Allow rules only.** The rules only skip the confirmation prompt for matching commands. Every other command still asks, and nothing is blocked. The Rules and the Skill remain the real guard.
- **No deny rules**, because they would give false assurance: extra commands can be smuggled through `adb shell`.
- **Cursor:** the project files replace your own IDE terminal allowlist in this project, which is why the flag is opt-in.

---

## Alert

Source: https://nativecn.dev/docs/components/alert

> Alert, AlertTitle and AlertDescription: an inline message with Variants (default, destructive, success, warning, info), each with a default icon.

Component · feedback. Registry item `alert`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/alert.json

### Installation

```sh
npx nativecn-cli@latest add alert
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [text](https://nativecn.dev/docs/components/text), [icon](https://nativecn.dev/docs/components/icon), [form-field-context](https://nativecn.dev/docs/primitives/form-field-context), [announce](https://nativecn.dev/docs/primitives/announce).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`.

### Usage

#### Alert demo

Alerts in every Variant, and one with a custom icon.

```tsx
import { Terminal } from "lucide-react-native";
import { View } from "react-native";

import { Alert, AlertDescription, AlertTitle } from "@/components/alert";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({
  stack: { gap: t.spacing[4] },
}));

/** Every Variant with its default icon, and one with a custom icon. */
export default function AlertDemo() {
  const styles = useStyles();
  return (
    <View style={styles.stack}>
      <Alert icon={Terminal}>
        <AlertTitle>Heads up!</AlertTitle>
        <AlertDescription>You can add Components to your app with the CLI.</AlertDescription>
      </Alert>
      <Alert variant="destructive">
        <AlertTitle>Payment failed</AlertTitle>
        <AlertDescription>Check your card details and try again.</AlertDescription>
      </Alert>
      <Alert variant="success">
        <AlertTitle>Profile saved</AlertTitle>
      </Alert>
      <Alert variant="warning">
        <AlertTitle>Storage almost full</AlertTitle>
        <AlertDescription>You have used 90% of your space.</AlertDescription>
      </Alert>
      <Alert variant="info">
        <AlertDescription>A new version is available.</AlertDescription>
      </Alert>
    </View>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `variant` | default \| destructive \| success \| warning \| info (default default) |
| `icon` | Lucide icon component; each Variant has a default (Info, CircleAlert, CircleCheck, TriangleAlert, Info); null hides it |
| `AlertTitle, AlertDescription` | Text props (children); the colour follows the Variant |

### Variants

- `default`, `destructive`, `success`, `warning`, `info`

### Accessibility

- role alert, read as one element: the title and description together.
- A destructive, success or warning Alert is announced once when it appears and again when its text changes ("Error: Wrong password. Check it and try again.", "Success: Saved", "Warning: Your session expires soon"); unrelated re-renders stay silent.
- default and info Alerts are not announced; screen readers read them when the user reaches them.
- aria-label, if given, replaces the announced text; without it the announcement is built from the text written inside the Alert.
- Not announced when it sits inside another Alert (the outer one speaks) or inside a FormField that is announcing its error.
- The Variant's icon is decorative.

### Notes

Never use Alert.alert or any platform dialog: use this inline Alert, or toast() for transient and server feedback. The border, icon and title take the Variant's Colour Role on a card background.

---

## Avatar

Source: https://nativecn.dev/docs/components/avatar

> Round user image (expo-image) with fallback initials, in sizes sm, md and lg.

Component · display. Registry item `avatar`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/avatar.json

### Installation

```sh
npx nativecn-cli@latest add avatar
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [text](https://nativecn.dev/docs/components/text).

Packages: `expo-image`.

### Usage

#### Avatar demo

Avatars in every size, with an image and with initials only.

```tsx
import { View } from "react-native";

import { Avatar } from "@/components/avatar";
import { createStyles } from "@/theme";

export default function AvatarDemo() {
  const styles = useStyles();
  return (
    <View style={styles.row}>
      <Avatar size="sm" src="https://github.com/expo.png" fallback="EX" alt="Expo" />
      <Avatar src="https://github.com/shadcn.png" fallback="CN" alt="shadcn" />
      {/* No image: the initials show. */}
      <Avatar size="lg" fallback="JD" alt="Jane Doe" />
    </View>
  );
}

const useStyles = createStyles((t) => ({
  row: { flexDirection: "row", alignItems: "center", gap: t.spacing[3] },
}));
```

### Props

| Prop | Type and description |
|---|---|
| `src` | string: the image URI |
| `fallback` | string: initials shown while loading, on error or without src (e.g. "JD") |
| `size` | "sm" \| "md" (default) \| "lg": Vega 32 / 40 / 64, Nova 24 / 32 / 48 |
| `alt` | string: who it shows; without it the avatar is decorative (hidden from screen readers) |
| `style` | merged last |

### Accessibility

- With alt it has role img and is read with that name; without alt it is decorative and hidden.
- Pass alt unless the person's name is already next to the avatar.
- The fallback initials never follow the OS font size, so they stay inside the circle.

### Notes

expo-image is SDK-pinned (`npx expo install expo-image`). The fallback sits behind the image, so it shows while the image loads and stays when it fails.

---

## Badge

Source: https://nativecn.dev/docs/components/badge

> Small status label with Variants default, secondary, outline, destructive, success and warning.

Component · display. Registry item `badge`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/badge.json

### Installation

```sh
npx nativecn-cli@latest add badge
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [text](https://nativecn.dev/docs/components/text).

### Usage

#### Badge demo

A Badge in every Variant.

```tsx
import { View } from "react-native";

import { Badge } from "@/components/badge";
import { createStyles } from "@/theme";

export default function BadgeDemo() {
  const styles = useStyles();
  return (
    <View style={styles.row}>
      <Badge label="New" />
      <Badge label="Beta" variant="secondary" />
      <Badge label="Draft" variant="outline" />
      <Badge label="Failed" variant="destructive" />
      <Badge label="Paid" variant="success" />
      <Badge label="Pending" variant="warning" />
    </View>
  );
}

const useStyles = createStyles((t) => ({
  row: { flexDirection: "row", flexWrap: "wrap", gap: t.spacing[2] },
}));
```

### Props

| Prop | Type and description |
|---|---|
| `label` | string (required): the visible text and accessible name |
| `variant` | "default" (default) \| "secondary" \| "outline" \| "destructive" \| "success" \| "warning" |
| `style` | merged last |

### Variants

- `default`, `secondary`, `outline`, `destructive`, `success`, `warning`

### Accessibility

- Not interactive: its label is read as plain text.
- The label uses the caption text Variant, which caps the OS font scale at 1.5× when font scaling is on.

### Notes

Not pressable: for a selectable or removable pill use Chip. A Badge sizes to its label (alignSelf flex-start). Its size comes from the badge.root and badge.label Style Slots.

---

## Button

Source: https://nativecn.dev/docs/components/button

> Button with Variants (primary, secondary, outline, ghost, destructive, link), Sizes, an icon slot, loading and status; icon-only requires aria-label.

Component · core. Registry item `button`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/button.json

### Installation

```sh
npx nativecn-cli@latest add button
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [pressable](https://nativecn.dev/docs/primitives/pressable), [text](https://nativecn.dev/docs/components/text), [icon](https://nativecn.dev/docs/components/icon), [spinner](https://nativecn.dev/docs/components/spinner), [announce](https://nativecn.dev/docs/primitives/announce).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`, `react-native-reanimated`, `react-native-worklets`.

### Usage

#### Button demo

Every Variant and Size, an icon, icon-only, loading, status and disabled.

```tsx
import { ArrowRight, Trash } from "lucide-react-native";
import { useState } from "react";
import { View } from "react-native";

import { Button } from "@/components/button";
import { createStyles } from "@/theme";

/** Variants, Sizes, an icon, icon-only, loading and status. */
export default function ButtonDemo() {
  const styles = useStyles();
  const [saving, setSaving] = useState(false);
  const [saved, setSaved] = useState(false);

  const save = () => {
    setSaving(true);
    setTimeout(() => {
      setSaving(false);
      setSaved(true);
    }, 800);
  };

  return (
    <View style={styles.stack}>
      <View style={styles.row}>
        <Button label="Primary" />
        <Button label="Secondary" variant="secondary" />
        <Button label="Outline" variant="outline" />
      </View>
      <View style={styles.row}>
        <Button label="Ghost" variant="ghost" />
        <Button label="Delete" variant="destructive" />
        <Button label="Learn more" variant="link" />
      </View>
      <View style={styles.row}>
        <Button label="Small" size="sm" />
        <Button label="Large" size="lg" />
        {/* Icon-only: aria-label is required. */}
        <Button icon={Trash} variant="outline" aria-label="Delete draft" />
      </View>
      <Button label="Continue" icon={ArrowRight} iconPosition="end" />
      {/* The screen sets and clears status; the Button never resets it. */}
      <Button
        label={saved ? "Saved" : "Save"}
        loading={saving}
        status={saved ? "success" : undefined}
        onPress={save}
      />
      <Button label="Disabled" disabled />
    </View>
  );
}

const useStyles = createStyles((t) => ({
  stack: { gap: t.spacing[3] },
  row: { flexDirection: "row", flexWrap: "wrap", alignItems: "center", gap: t.spacing[2] },
}));
```

### Props

| Prop | Type and description |
|---|---|
| `...PressableProps` | Pressable Primitive props pass through (onPress, onLongPress, haptic, testID, ...) |
| `label` | string: the visible text and accessible name (required unless icon-only) |
| `icon` | LucideIcon: shown in the icon slot |
| `iconPosition` | "start" (default) \| "end": where the icon slot sits |
| `variant` | "primary" (default) \| "secondary" \| "outline" \| "ghost" \| "destructive" \| "link" |
| `size` | "sm" \| "md" (default) \| "lg" |
| `loading` | boolean: a Spinner takes the icon slot, the label stays, presses are blocked, announced busy |
| `status` | "error" \| "success": a status icon in the icon slot, announced once; the screen clears it |
| `disabled` | boolean: dimmed, presses blocked, announced disabled |
| `aria-label` | string: required for icon-only Buttons (icon and no label) |
| `style` | ViewStyle, layout only (e.g. full width), merged last |

### Variants

- `variant`: `primary`, `secondary`, `outline`, `ghost`, `destructive`, `link`
- `size`: `sm`, `md`, `lg`
- `status`: `error`, `success`

### Accessibility

- role button; the label is the accessible name.
- Icon-only Buttons are typed to require aria-label.
- The tap area is extended to 48 high, and to 48 wide for icon-only Buttons.
- disabled is announced as disabled and loading as busy; no press handler runs in either state.
- A new status is announced once ("Save: error"); the loading Spinner stays silent because the Button is already busy.
- The label uses the button text Variant, which caps the OS font scale at 1.5× when font scaling is on.

### Notes

Built on the Pressable Primitive: the pressed look comes from the button.pressed Style Slot. Precedence: disabled > loading > status. Make a Button full width with style={{ alignSelf: 'stretch' }}; there is no fullWidth prop. Buttons give no haptic tick by default.

---

## Card

Source: https://nativecn.dev/docs/components/card

> Card surface with CardHeader, CardTitle, CardDescription, CardContent and CardFooter; onPress makes the whole card pressable.

Component · display. Registry item `card`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/card.json

### Installation

```sh
npx nativecn-cli@latest add card
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [pressable](https://nativecn.dev/docs/primitives/pressable), [text](https://nativecn.dev/docs/components/text).

### Usage

#### Card demo

A Card with header, content and footer, and a pressable Card.

```tsx
import { View } from "react-native";

import { Badge } from "@/components/badge";
import { Button } from "@/components/button";
import {
  Card,
  CardContent,
  CardDescription,
  CardFooter,
  CardHeader,
  CardTitle,
} from "@/components/card";
import { Text } from "@/components/text";
import { createStyles } from "@/theme";

export default function CardDemo() {
  const styles = useStyles();
  return (
    <View style={styles.stack}>
      <Card>
        <CardHeader>
          <CardTitle>Pro plan</CardTitle>
          <CardDescription>Everything in Free, plus unlimited projects.</CardDescription>
        </CardHeader>
        <CardContent>
          <Badge label="Most popular" variant="secondary" />
          <Text>$12 per month, billed yearly.</Text>
        </CardContent>
        <CardFooter>
          <Button label="Upgrade" style={styles.grow} />
        </CardFooter>
      </Card>

      {/* With onPress the whole card is one pressable target. */}
      <Card onPress={() => {}}>
        <CardHeader>
          <CardTitle>Order #1042</CardTitle>
          <CardDescription>Arrives Thursday</CardDescription>
        </CardHeader>
      </Card>
    </View>
  );
}

const useStyles = createStyles((t) => ({
  stack: { gap: t.spacing[4] },
  grow: { flex: 1 },
}));
```

### Props

#### Card

| Prop | Type and description |
|---|---|
| `children` | CardHeader, CardContent, CardFooter or anything else |
| `onPress` | (event) => void: makes the whole card one pressable target (role button) |
| `onLongPress` | (event) => void |
| `disabled` | boolean (default false): pressable cards only; dims and blocks presses |
| `haptic` | "selection" \| "light": pressable cards only |
| `style` | layout only, merged last onto the root |

#### CardHeader

| Prop | Type and description |
|---|---|
| `children` | CardTitle and CardDescription |

#### CardTitle

| Prop | Type and description |
|---|---|
| `children` | the title text (role heading); Text props except variant |

#### CardDescription

| Prop | Type and description |
|---|---|
| `children` | muted supporting text; Text props except variant |

#### CardContent

| Prop | Type and description |
|---|---|
| `children` | the main content |

#### CardFooter

| Prop | Type and description |
|---|---|
| `children` | actions, laid out in a row |

### Accessibility

- With onPress or onLongPress the whole card is one button, named by its text.
- A pressable card is taller than the 48 touch target, so its tap area is not extended.
- disabled is announced as disabled and blocks presses.
- CardTitle has role heading (the h4 text Variant).

### Notes

Compose shadcn-style from named exports (no dot syntax): <Card><CardHeader><CardTitle>…</CardTitle><CardDescription>…</CardDescription></CardHeader><CardContent>…</CardContent><CardFooter>…</CardFooter></Card>. With onPress the whole card is a single pressable, so don't nest other pressables inside a pressable Card. Padding, gap, radius, border and shadow come from the card.root Style Slot; the pressed look from card.pressed.

---

## Checkbox

Source: https://nativecn.dev/docs/components/checkbox

> Checkbox with an optional label, controlled or uncontrolled, an indeterminate (mixed) state and a haptic tick.

Component · forms. Registry item `checkbox`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/checkbox.json

### Installation

```sh
npx nativecn-cli@latest add checkbox
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [pressable](https://nativecn.dev/docs/primitives/pressable), [form-field-context](https://nativecn.dev/docs/primitives/form-field-context), [text](https://nativecn.dev/docs/components/text), [icon](https://nativecn.dev/docs/components/icon), [use-controllable-state](https://nativecn.dev/docs/primitives/use-controllable-state).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`.

### Usage

#### Checkbox demo

A labelled Checkbox, a 'select all' with an indeterminate state, and a disabled one.

```tsx
import { useState } from "react";
import { View } from "react-native";

import { Checkbox } from "@/components/checkbox";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({
  root: { gap: t.spacing[4] },
  nested: { gap: t.spacing[3], paddingLeft: t.spacing[6] },
}));

const TOPPINGS = ["Cheese", "Olives", "Basil"];

export default function CheckboxDemo() {
  const styles = useStyles();
  const [picked, setPicked] = useState<string[]>(["Cheese"]);
  const all = picked.length === TOPPINGS.length;

  return (
    <View style={styles.root}>
      <Checkbox label="Accept the terms" defaultChecked />
      <Checkbox
        label="All toppings"
        checked={all}
        indeterminate={picked.length > 0 && !all}
        onCheckedChange={(checked) => setPicked(checked ? TOPPINGS : [])}
      />
      <View style={styles.nested}>
        {TOPPINGS.map((topping) => (
          <Checkbox
            key={topping}
            label={topping}
            checked={picked.includes(topping)}
            onCheckedChange={(checked) =>
              setPicked((prev) =>
                checked ? [...prev, topping] : prev.filter((p) => p !== topping),
              )
            }
          />
        ))}
      </View>
      <Checkbox label="Unavailable" disabled />
    </View>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `checked` | boolean: the controlled checked state |
| `defaultChecked` | boolean: the starting state while uncontrolled (default false) |
| `onCheckedChange` | (checked: boolean) => void: called when the user toggles it |
| `label` | string: visible text next to the box, also the accessible name |
| `indeterminate` | boolean: shows a dash and is announced as mixed; pressing it checks the box |
| `disabled` | boolean: dimmed, announced as disabled, no handler runs |
| `style` | layout only, merged last onto the root |

### Accessibility

- role checkbox with aria-checked true, false or mixed.
- The label is the accessible name; without a label, pass aria-label.
- The whole row (box and label) is the tap target, at least 48.
- disabled is announced as disabled and no handler runs.
- Inside a FormField the field's label and error become its name and hint.

### Notes

A light haptic tick on toggle when config.haptics is on. Inside a FormField it takes the field's disabled, and an error outlines the box in destructive. The box uses the checkbox.box Style Slot and the pressed look checkbox.pressed.

---

## Chip

Source: https://nativecn.dev/docs/components/chip

> Chip (plain, toggle or removable, with an optional icon) and ChipGroup (single or multiple choice on the SelectionGroup Primitive), with a haptic tick.

Component · forms. Registry item `chip`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/chip.json

### Installation

```sh
npx nativecn-cli@latest add chip
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [pressable](https://nativecn.dev/docs/primitives/pressable), [selection-group](https://nativecn.dev/docs/primitives/selection-group), [use-controllable-state](https://nativecn.dev/docs/primitives/use-controllable-state), [text](https://nativecn.dev/docs/components/text), [icon](https://nativecn.dev/docs/components/icon).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`.

### Usage

#### Chip demo

Single and multiple ChipGroups, a toggle Chip with an icon and removable Chips.

```tsx
import { Star } from "lucide-react-native";
import { useState } from "react";
import { View } from "react-native";

import { Chip, ChipGroup } from "@/components/chip";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({
  root: { gap: t.spacing[6] },
  row: { flexDirection: "row", flexWrap: "wrap", gap: t.spacing[2] },
}));

export default function ChipDemo() {
  const styles = useStyles();
  const [sort, setSort] = useState("new");
  const [tags, setTags] = useState(["react-native", "expo", "design"]);

  return (
    <View style={styles.root}>
      <ChipGroup value={sort} onValueChange={setSort}>
        <Chip value="new" label="Newest" />
        <Chip value="top" label="Top rated" />
        <Chip value="near" label="Nearby" />
      </ChipGroup>
      <ChipGroup type="multiple" defaultValue={["vegan"]}>
        <Chip value="vegan" label="Vegan" />
        <Chip value="gluten-free" label="Gluten-free" />
        <Chip value="spicy" label="Spicy" disabled />
      </ChipGroup>
      <Chip label="Favourites" icon={Star} defaultSelected />
      <View style={styles.row}>
        {tags.map((tag) => (
          <Chip
            key={tag}
            label={tag}
            onRemove={() => setTags((prev) => prev.filter((t) => t !== tag))}
          />
        ))}
      </View>
    </View>
  );
}
```

### Props

#### Chip

| Prop | Type and description |
|---|---|
| `label` | string (required): the visible text, also the accessible name |
| `icon` | a Lucide component shown before the label |
| `value` | string: the value it stands for inside a ChipGroup (required there) |
| `selected` | boolean: controlled selected state; makes the Chip a toggle |
| `defaultSelected` | boolean: starting state while uncontrolled; makes the Chip a toggle |
| `onSelectedChange` | (selected: boolean) => void; makes the Chip a toggle |
| `onRemove` | () => void: shows a remove (×) button inside the pill, its own control |
| `disabled` | boolean |
| `style` | layout only, merged last onto the root |

#### ChipGroup

| Prop | Type and description |
|---|---|
| `type` | "single" (default) \| "multiple" |
| `value` | string (single) or string[] (multiple): the controlled selection |
| `defaultValue` | string or string[]: the starting selection while uncontrolled |
| `onValueChange` | (value) => void: called with the new selection |
| `disabled` | boolean: disables every Chip |
| `style` | layout only, merged last onto the root |

### Accessibility

- A standalone Chip is a button, or a checkbox with aria-checked when it is a toggle.
- In a single ChipGroup the Chips are radios in a radiogroup; in a multiple ChipGroup they are checkboxes in a group.
- The label is the accessible name.
- With onRemove, the × is a separate button named "Remove <label>", a sibling of the Chip (not nested inside it), with a 48 tap area.
- The tap area is extended to 48 high.

### Notes

Named exports Chip and ChipGroup. Inside a ChipGroup, a Chip's own selection props are ignored. With onRemove, a plain View draws the pill around two sibling controls, the Chip's press and the × button (never nested). A light haptic tick on selection when config.haptics is on. The surface uses the chip.root Style Slot and the pressed look chip.pressed.

---

## Container

Source: https://nativecn.dev/docs/components/container

> Wraps a Screen: safe-area edges, scrolling, keyboard avoidance, Token padding and a max content width.

Component · core. Registry item `container`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/container.json

### Installation

```sh
npx nativecn-cli@latest add container
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [keyboard](https://nativecn.dev/docs/primitives/keyboard).

Packages: `react-native-safe-area-context`.

### Usage

#### Container demo

A Screen wrapped in Container.

```tsx
import { Button } from "@/components/button";
import { Container } from "@/components/container";
import { Text } from "@/components/text";

/**
 * A Screen wrapped in Container: safe-area edges, scrolling, keyboard avoidance, Token padding
 * and a 640 max width, all on by default.
 */
export default function ContainerDemo() {
  return (
    <Container>
      <Text variant="h2">Settings</Text>
      <Text color="mutedForeground">
        Content scrolls, stays clear of the notch and home indicator, and keeps the focused field
        above the keyboard.
      </Text>
      <Button label="Save changes" />
    </Container>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `...ViewProps` | React Native View props pass through onto the root |
| `children` | the Screen's content |
| `scroll` | boolean (default true): scroll the content |
| `keyboard` | boolean (default true): keep the focused field above the keyboard; needs scroll |
| `padded` | boolean (default true): pad the content by the spacing Tokens |
| `edges` | ('top' \| 'bottom' \| 'left' \| 'right')[] (default ['top', 'bottom']): safe-area edges to keep clear of |
| `maxWidth` | number (default 640): caps the content width and centres it |
| `extraKeyboardSpace` | number: extra room below the content while the keyboard is open |
| `contentContainerStyle` | ViewStyle: merged after the content's own padding and gap |
| `ref` | Ref<View> |
| `style` | ViewStyle, merged last onto the root |

### Accessibility

- No role of its own: it only lays out the Screen.
- Keeps content clear of the safe-area edges (top and bottom by default), so nothing sits under the status bar or home indicator.
- With keyboard on (the default), the focused field stays above the keyboard.
- Scrolls by default, so content taller than the screen stays reachable.

### Notes

Wrap every Screen's content in Container. Scrolling uses the keyboard Primitive's KeyboardAwareScroll, so KeyboardProvider must wrap the root Layout. With a KeyboardStickyFooter below the Container, drop 'bottom' from edges (the footer pads the bottom safe area) and pass its height as extraKeyboardSpace.

---

## Drawer

Source: https://nativecn.dev/docs/components/drawer

> Drawer panel content for Expo Router's drawer (expo-router/drawer): DrawerContent, DrawerHeader, DrawerSection, DrawerItem (label, icon, href, badge; active from the current route) and DrawerFooter.

Component · navigation. Registry item `drawer`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/drawer.json

### Installation

```sh
npx nativecn-cli@latest add drawer
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [pressable](https://nativecn.dev/docs/primitives/pressable), [text](https://nativecn.dev/docs/components/text), [icon](https://nativecn.dev/docs/components/icon), [badge](https://nativecn.dev/docs/components/badge).

Packages: `expo-router`, `react-native-safe-area-context`.

### Usage

#### Drawer demo

An app/(drawer)/_layout.tsx: a profile header, titled sections, an accent item, a bottom group and a Log out footer.

```tsx
// app/(drawer)/_layout.tsx: a drawer Layout whose panel is built from the drawer Components.
// The drawer comes only from `expo-router/drawer` (built into Expo Router); never install
// `@react-navigation/drawer` or the unrelated npm package `expo-drawer`.
import { Drawer } from "expo-router/drawer";
import { Bell, Home, Inbox, LifeBuoy, LogOut, Settings, Users } from "lucide-react-native";
import { View } from "react-native";

import { Avatar } from "@/components/avatar";
import { Badge } from "@/components/badge";
import {
  DrawerContent,
  DrawerFooter,
  DrawerHeader,
  DrawerItem,
  DrawerSection,
} from "@/components/drawer";
import { Separator } from "@/components/separator";
import { Text } from "@/components/text";
import { createStyles } from "@/theme";

export default function DrawerLayout() {
  return (
    <Drawer
      drawerContent={(props) => (
        <DrawerContent {...props}>
          <DrawerHeader>
            <ProfileHeader />
          </DrawerHeader>

          <DrawerSection title="Main">
            <DrawerItem label="Home" icon={Home} href="/" />
            <DrawerItem label="Inbox" icon={Inbox} href="/inbox" badge={3} />
            <DrawerItem label="Team" icon={Users} href="/team" />
          </DrawerSection>

          {/* An Accent Colour highlighted item, and an item active in Accent Colour text. */}
          <DrawerSection title="Workspace">
            <DrawerItem
              label="Get started"
              href="/onboarding"
              tone="accent"
              badge={<Badge label="5 Steps" />}
            />
            <DrawerItem label="Notifications" icon={Bell} href="/notifications" variant="text" />
          </DrawerSection>

          {/* Pushed to the bottom of the scrolling area, above the footer. */}
          <DrawerSection style={{ marginTop: "auto" }}>
            <DrawerItem label="Settings" icon={Settings} href="/settings" />
            <DrawerItem label="Help" icon={LifeBuoy} href="/help" />
          </DrawerSection>

          <DrawerFooter>
            <Separator />
            <DrawerItem label="Log out" icon={LogOut} onPress={() => {}} />
          </DrawerFooter>
        </DrawerContent>
      )}
    >
      <Drawer.Screen name="index" options={{ title: "Home" }} />
    </Drawer>
  );
}

function ProfileHeader() {
  const styles = useStyles();
  return (
    <View style={styles.profile}>
      <Avatar fallback="JD" size="lg" />
      <View style={styles.name}>
        <Text variant="h4">Jane Doe</Text>
        <Text variant="small" color="mutedForeground">
          jane@example.com
        </Text>
      </View>
      <Badge label="Pro" variant="secondary" />
    </View>
  );
}

const useStyles = createStyles((t) => ({
  profile: { gap: t.spacing[3] },
  name: { gap: t.spacing[1] },
}));
```

### Props

#### DrawerContent

| Prop | Type and description |
|---|---|
| `...DrawerContentComponentProps` | Expo Router's drawer props (state, navigation, descriptors): spread the drawerContent props in |
| `children` | DrawerHeader (pinned on top), DrawerSections and DrawerItems (scrolling) and DrawerFooter (pinned at the bottom), in any order |
| `contentContainerStyle` | the scrolling area's content, merged last |
| `style` | merged last onto the panel |

#### DrawerHeader

| Prop | Type and description |
|---|---|
| `children` | a profile, a logo and name, or a cover |
| `style` | merged last; the top padding includes the status bar inset |

#### DrawerSection

| Prop | Type and description |
|---|---|
| `title` | string: a small muted heading (role heading) |
| `children` | DrawerItems |
| `style` | merged last; { marginTop: "auto" } pushes the group to the bottom |

#### DrawerItem

| Prop | Type and description |
|---|---|
| `label` | string (required): the visible text and accessible name |
| `icon` | a Lucide icon component; leave it out for text-only items |
| `href` | Href: pressing navigates there and closes the drawer; active while the pathname is this route or below it |
| `badge` | string \| number (a secondary Badge) \| ReactElement (rendered as-is) |
| `active` | boolean: overrides the active state derived from the route |
| `variant` | "default" (default): active on a muted background \| "text": active in the Accent Colour, no background |
| `tone` | "default" (default) \| "accent": an Accent Colour tint with Accent Colour text and icon |
| `onPress` | (event) => void: runs before navigating; without href the item is an action (role button) and the drawer stays open |
| `disabled` | boolean (default false) |
| `style` | layout only, merged last onto the root |

#### DrawerFooter

| Prop | Type and description |
|---|---|
| `children` | Log out, a team switcher, the user |
| `style` | merged last; the bottom padding includes the home indicator inset |

### Variants

- `variant`: `default`, `text`
- `tone`: `default`, `accent`

### Accessibility

- A DrawerItem with href has role link, with aria-selected while its route is active; without href it has role button.
- An item's visible label is its accessible name.
- Items are 48 high in Vega and 40 in Nova, with the tap area extended to 48.
- DrawerSection titles have role heading.
- disabled items are announced as disabled and block presses.
- Item labels use the label text Variant, which caps the OS font scale at 1.5× when font scaling is on.

### Notes

Built only on expo-router/drawer, which ships inside Expo Router (react-native-drawer-layout): never install @react-navigation/drawer or the npm package expo-drawer. In app/(drawer)/_layout.tsx render <Drawer drawerContent={(props) => <DrawerContent {...props}>…</DrawerContent>} />. A DrawerItem with href is active while usePathname() is its route or below it (route groups such as (drawer) and index are ignored); tapping it calls router.navigate(href) and closes the drawer. Items are sized by the drawer.item Style Slot (Vega 48, Nova 40); the label, pressed look and accent tint come from drawer.label, drawer.pressed and drawer.tint. The panel keeps clear of the status bar and home indicator.

---

## Empty State

Source: https://nativecn.dev/docs/components/empty-state

> What a Screen or list shows when there is nothing to show yet: an icon, a title, a description and an action.

Component · feedback. Registry item `empty-state`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/empty-state.json

### Installation

```sh
npx nativecn-cli@latest add empty-state
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [text](https://nativecn.dev/docs/components/text), [icon](https://nativecn.dev/docs/components/icon).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`.

### Usage

#### Empty State demo

An empty inbox with a New message action.

```tsx
import { Inbox, Plus } from "lucide-react-native";

import { Button } from "@/components/button";
import { EmptyState } from "@/components/empty-state";

/** An empty inbox with an action. */
export default function EmptyStateDemo() {
  return (
    <EmptyState
      icon={Inbox}
      title="No messages yet"
      description="When someone writes to you, their message will appear here."
    >
      <Button label="New message" icon={Plus} />
    </EmptyState>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `icon` | Lucide icon component, drawn in a muted circle |
| `title` | string (required), read as a heading |
| `description` | string |
| `children` | the action, usually a Button |

### Accessibility

- The title has role heading (the h4 text Variant).
- The icon is decorative and hidden from screen readers.
- The action (usually a Button) brings its own role and name.

### Notes

Centre it in the free space (style={{ flex: 1 }}, or a list's ListEmptyComponent). Padding, gap and icon size come from the empty-state.root and empty-state.icon Style Slots.

---

## FormField

Source: https://nativecn.dev/docs/components/form-field

> Lays out a control with its Label, description and error, and links them for screen readers ("Email, text field, Enter a valid email").

Component · forms. Registry item `form-field`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/form-field.json

### Installation

```sh
npx nativecn-cli@latest add form-field
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [form-field-context](https://nativecn.dev/docs/primitives/form-field-context), [label](https://nativecn.dev/docs/components/label), [text](https://nativecn.dev/docs/components/text).

### Usage

#### FormField demo

Email and password fields in a FocusChain, with a description and an error.

```tsx
import { useState } from "react";

import { FormField } from "@/components/form-field";
import { Input } from "@/components/input";
import { FocusChain } from "@/components/primitives/focus-chain";

export function FormFieldDemo() {
  const [email, setEmail] = useState("");
  const [error, setError] = useState<string>();

  const submit = () => setError(email.includes("@") ? undefined : "Enter a valid email");

  return (
    <FocusChain onSubmit={submit}>
      <FormField label="Email" description="We never share it." error={error} required>
        <Input
          value={email}
          onChangeText={setEmail}
          placeholder="you@example.com"
          keyboardType="email-address"
          autoCapitalize="none"
          autoComplete="email"
        />
      </FormField>
      <FormField label="Password" required>
        <Input secureTextEntry autoComplete="current-password" />
      </FormField>
    </FocusChain>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `label` | string: the visible label and the control's accessible name |
| `description` | string: helper text under the control, read as its hint |
| `error` | string: replaces the description, sets status error, announced once |
| `required` | boolean: * marker and "required" in the spoken name (default false) |
| `status` | 'error' \| 'success' (defaults to 'error' while error is set) |
| `disabled` | boolean: passed down to the control (default false) |
| `children` | the control: Input, Textarea, InputOTP, Checkbox, Switch, Slider |
| `style` | ViewStyle, layout only, merged last |

### Accessibility

- The label is the control's accessible name, with ", required" added when required.
- The error, or else the description, is the control's hint.
- The visible label, description and error are hidden from screen readers, so nothing is read twice.
- An error is announced once when it appears or its text changes.
- disabled passes down to the control, which is announced as disabled.

### Notes

Wrap each field of a form in FormField, and the fields in FocusChain. FormField is library-neutral: with react-hook-form, render it inside a Controller and pass fieldState.error?.message as error.

---

## Icon

Source: https://nativecn.dev/docs/components/icon

> Every glyph: a Lucide icon at a Token size in a Colour Role, decorative unless labelled.

Component · core. Registry item `icon`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/icon.json

### Installation

```sh
npx nativecn-cli@latest add icon
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`.

### Usage

#### Icon demo

Icons in each size, a Colour Role, a stroke width and a labelled icon.

```tsx
import { Bell, Heart, Settings } from "lucide-react-native";
import { View } from "react-native";

import { Icon } from "@/components/icon";
import { createStyles } from "@/theme";

/** Each size, a Colour Role, a stroke width and a labelled (meaningful) icon. */
export default function IconDemo() {
  const styles = useStyles();
  return (
    <View style={styles.row}>
      <Icon icon={Settings} size="sm" />
      <Icon icon={Settings} />
      <Icon icon={Settings} size="lg" />
      <Icon icon={Heart} color="destructive" strokeWidth={2.5} />
      {/* Decorative unless it carries meaning on its own: then name it. */}
      <Icon icon={Bell} color="primary" aria-label="New notifications" />
    </View>
  );
}

const useStyles = createStyles((t) => ({
  row: { flexDirection: "row", alignItems: "center", gap: t.spacing[4] },
}));
```

### Props

| Prop | Type and description |
|---|---|
| `icon` | LucideIcon (required), e.g. import { Camera } from "lucide-react-native" |
| `size` | "sm" \| "md" (default) \| "lg": 16 · 20 · 24 from the iconSize Tokens, scaled |
| `color` | a Colour Role (default foreground) |
| `strokeWidth` | number (default 2) |
| `aria-label` | string: makes the icon meaningful (role img); without it the icon is decorative and hidden |
| `style` | ViewStyle, merged last |

### Variants

- `size`: `sm`, `md`, `lg`

### Accessibility

- Decorative by default: hidden from screen readers.
- With aria-label it has role img and is read with that name.
- Inside a labelled control (a Button, a ListItem) leave it decorative: the control carries the name.

### Notes

Every glyph goes through Icon, so iOS and Android draw the same Lucide glyphs; never use @expo/vector-icons or SF Symbols directly. lucide-react-native is a recorded dependency exception and react-native-svg is SDK-pinned.

---

## Input

Source: https://nativecn.dev/docs/components/input

> Single-line text field with Sizes, a leading icon, error/success status, a focus ring and an automatic Show/Hide password toggle.

Component · forms. Registry item `input`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/input.json

### Installation

```sh
npx nativecn-cli@latest add input
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [form-field-context](https://nativecn.dev/docs/primitives/form-field-context), [focus-chain](https://nativecn.dev/docs/primitives/focus-chain), [pressable](https://nativecn.dev/docs/primitives/pressable), [icon](https://nativecn.dev/docs/components/icon), [announce](https://nativecn.dev/docs/primitives/announce).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`.

### Usage

#### Input demo

Inputs with an icon, Sizes, a status and a password toggle.

```tsx
import { Mail } from "lucide-react-native";
import { View } from "react-native";

import { Input } from "@/components/input";

export function InputDemo() {
  return (
    <View>
      <Input icon={Mail} placeholder="Email" aria-label="Email" keyboardType="email-address" />
      <Input size="sm" placeholder="Small" aria-label="Small" />
      <Input size="lg" placeholder="Large" aria-label="Large" />
      <Input status="error" defaultValue="not-an-email" aria-label="Email" />
      <Input secureTextEntry placeholder="Password" aria-label="Password" />
      <Input disabled defaultValue="Read only" aria-label="Disabled" />
    </View>
  );
}
```

#### InputOTP demo

A 6-digit verification code, checked when complete, with error and success.

```tsx
import { useState } from "react";
import { View } from "react-native";

import { InputOTP, type InputOTPStatus } from "@/components/input-otp";
import { Text } from "@/components/text";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({ root: { gap: t.spacing[3] } }));

/** A 6-digit verification code: checked when complete; typing again clears the status. */
export function InputOTPDemo() {
  const styles = useStyles();
  const [code, setCode] = useState("");
  const [status, setStatus] = useState<InputOTPStatus>();

  return (
    <View style={styles.root}>
      <Text variant="label">Verification code</Text>
      <InputOTP
        aria-label="Verification code"
        value={code}
        onChangeText={(next) => {
          setCode(next);
          setStatus(undefined);
        }}
        onComplete={(full) => setStatus(full === "123456" ? "success" : "error")}
        status={status}
      />
      <Text variant="caption" color={status === "error" ? "destructive" : "mutedForeground"}>
        {status === "error" ? "That code is not right. Try 123456." : "Enter the code we sent you."}
      </Text>
    </View>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `...TextInputProps` | React Native TextInput props pass through (value, defaultValue, onChangeText, keyboardType, ...) |
| `size` | 'sm' \| 'md' \| 'lg' (default 'md') |
| `icon` | LucideIcon: leading, decorative |
| `status` | 'error' \| 'success': colours and a screen-reader announcement |
| `disabled` | boolean: not editable, dimmed, skipped by FocusChain |
| `secureTextEntry` | boolean: hides the text and adds a Show/Hide password toggle |
| `ref` | Ref<TextInput> |
| `style` | ViewStyle, layout only, merged last onto the frame |

### Variants

- `size`: `sm`, `md`, `lg`
- `status`: `error`, `success`

### Accessibility

- The accessible name is aria-label, else the FormField label; inside a FormField the error, or else the description, is the hint.
- A new status is announced once ("Email: error"), unless a FormField is already announcing its error.
- disabled sets aria-disabled and makes the field read-only.
- The frame extends the tap area to 48 above and below, and a tap there focuses the field; screen readers skip the frame and reach the TextInput directly.
- With secureTextEntry, the toggle is a button named "Show password" or "Hide password", with its tap area extended to 48.

### Notes

Inside FormField, status and disabled come from the field. Inside FocusChain the return key reads Next/Done automatically; a field's own returnKeyType/onSubmitEditing wins. Precedence: disabled > status.

---

## InputOTP

Source: https://nativecn.dev/docs/components/input-otp

> One-time code field: one hidden input drives N cells; numeric keyboard, SMS/Keychain autofill, paste, onComplete, error/success status and secure.

Component · forms. Registry item `input-otp`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/input-otp.json

### Installation

```sh
npx nativecn-cli@latest add input-otp
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [text](https://nativecn.dev/docs/components/text), [form-field-context](https://nativecn.dev/docs/primitives/form-field-context), [focus-chain](https://nativecn.dev/docs/primitives/focus-chain), [use-controllable-state](https://nativecn.dev/docs/primitives/use-controllable-state), [announce](https://nativecn.dev/docs/primitives/announce).

### Usage

#### InputOTP demo

A 6-digit verification code, checked when complete, with error and success.

```tsx
import { useState } from "react";
import { View } from "react-native";

import { InputOTP, type InputOTPStatus } from "@/components/input-otp";
import { Text } from "@/components/text";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({ root: { gap: t.spacing[3] } }));

/** A 6-digit verification code: checked when complete; typing again clears the status. */
export function InputOTPDemo() {
  const styles = useStyles();
  const [code, setCode] = useState("");
  const [status, setStatus] = useState<InputOTPStatus>();

  return (
    <View style={styles.root}>
      <Text variant="label">Verification code</Text>
      <InputOTP
        aria-label="Verification code"
        value={code}
        onChangeText={(next) => {
          setCode(next);
          setStatus(undefined);
        }}
        onComplete={(full) => setStatus(full === "123456" ? "success" : "error")}
        status={status}
      />
      <Text variant="caption" color={status === "error" ? "destructive" : "mutedForeground"}>
        {status === "error" ? "That code is not right. Try 123456." : "Enter the code we sent you."}
      </Text>
    </View>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `length` | number of digits (default 6) |
| `value` | string (controlled) |
| `defaultValue` | string (uncontrolled, default "") |
| `onChangeText` | (code: string) => void: digits only, on every change including a paste |
| `onComplete` | (code: string) => void: once each time the last cell is filled |
| `status` | 'error' \| 'success': colours every cell, announced once; the screen clears it |
| `secure` | boolean: dots instead of digits, hidden from screen readers (default false) |
| `disabled` | boolean: not editable, dimmed, skipped by FocusChain |
| `ref` | Ref<TextInput>: the hidden input (focus, blur, clear) |
| `style` | ViewStyle, layout only, merged last onto the root |
| `...TextInputProps` | other TextInput props pass through to the hidden input (autoFocus, onFocus, aria-label, accessibilityHint, ...) |

### Variants

- `status`: `error`, `success`

### Accessibility

- Screen readers read one field, "Code, 6 digits": the name is aria-label, else the FormField label, else "Code", plus the digit count. The cells are hidden.
- Inside a FormField the error, or else the description, is its hint.
- A new status is announced once ("Code: error"), unless a FormField is already announcing its error.
- With secure, the cells show dots and the hidden input is a secure text entry.
- When the row of cells is under 48, the root extends the tap area to 48 and a tap there focuses the field.
- disabled sets aria-disabled and blocks typing.

### Notes

One hidden TextInput drives the cells, so typing, deleting, one-time-code autofill (iOS Keychain/SMS, Android SMS) and paste behave like one field. Non-digits are dropped, so a pasted "123 456" fills every cell. Inside FormField it takes the label, error and disabled; inside FocusChain it joins as one field. Cell size, radius and gap come from the input-otp.cell and input-otp.root Style Slots. Precedence: disabled > status.

---

## Label

Source: https://nativecn.dev/docs/components/label

> A field's visible label in the label type Variant, with a required marker read as "required".

Component · forms. Registry item `label`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/label.json

### Installation

```sh
npx nativecn-cli@latest add label
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [text](https://nativecn.dev/docs/components/text).

### Usage

#### Label demo

A Label and a required Label.

```tsx
import { View } from "react-native";

import { Label } from "@/components/label";

export function LabelDemo() {
  return (
    <View>
      <Label>Display name</Label>
      <Label required>Email</Label>
    </View>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `children` | ReactNode: the label text |
| `required` | boolean: shows * and adds "required" to the spoken name (default false) |
| `style` | TextStyle, merged last |

### Accessibility

- With required and string children it is read as "<text>, required"; the * marker is hidden from screen readers.
- Inside a FormField the visible label is hidden from screen readers; the control reads it as its name instead.
- It uses the label text Variant, which caps the OS font scale at 1.5× when font scaling is on.

### Notes

Inside a FormField the label is drawn by FormField and read as the control's name; use Label on its own only next to custom controls. Text props pass through.

---

## List

Source: https://nativecn.dev/docs/components/list

> Settings-style rows: ListSection, ListSectionHeader, ListSectionFooter and ListItem (title, description, icon, trailing, chevron, destructive, onPress); FlashList-safe.

Component · display. Registry item `list`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/list.json

### Installation

```sh
npx nativecn-cli@latest add list
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [pressable](https://nativecn.dev/docs/primitives/pressable), [text](https://nativecn.dev/docs/components/text), [icon](https://nativecn.dev/docs/components/icon), [separator](https://nativecn.dev/docs/components/separator).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`.

### Usage

#### List demo

A settings list: header, footer, icons, trailing values, chevrons and a destructive row.

```tsx
import { Bell, LogOut, Moon, User } from "lucide-react-native";
import { View } from "react-native";

import { Badge } from "@/components/badge";
import {
  ListItem,
  ListSection,
  ListSectionFooter,
  ListSectionHeader,
} from "@/components/list";
import { createStyles } from "@/theme";

export default function ListDemo() {
  const styles = useStyles();
  return (
    <View style={styles.stack}>
      <ListSection>
        <ListSectionHeader>Account</ListSectionHeader>
        <ListItem
          icon={User}
          title="Profile"
          description="Name, photo and email"
          chevron
          onPress={() => {}}
        />
        <ListItem
          icon={Bell}
          title="Notifications"
          trailing={<Badge label="3" />}
          chevron
          onPress={() => {}}
        />
        <ListItem icon={Moon} title="Appearance" trailing="System" chevron onPress={() => {}} />
        <ListSectionFooter>Changes sync across your devices.</ListSectionFooter>
      </ListSection>

      <ListSection>
        <ListItem icon={LogOut} title="Sign out" destructive onPress={() => {}} />
      </ListSection>
    </View>
  );
}

// In a FlashList, render ListItem as the row and Separator as ItemSeparatorComponent:
// <FlashList data={rows} renderItem={({ item }) => <ListItem title={item.name} chevron onPress={...} />} />

const useStyles = createStyles((t) => ({
  stack: { gap: t.spacing[6] },
}));
```

### Props

#### ListSection

| Prop | Type and description |
|---|---|
| `children` | ListSectionHeader, rows and ListSectionFooter; header and footer are drawn outside the rounded group |

#### ListSectionHeader

| Prop | Type and description |
|---|---|
| `children` | the section title (role heading) |

#### ListSectionFooter

| Prop | Type and description |
|---|---|
| `children` | a note under the rows |

#### ListItem

| Prop | Type and description |
|---|---|
| `title` | string (required unless children) |
| `description` | string: muted text under the title |
| `icon` | a Lucide icon component, at the start of the row |
| `trailing` | ReactNode at the end of the row (strings render as muted text): a value, Badge, Switch… |
| `chevron` | boolean (default false): a trailing chevron for rows that navigate |
| `destructive` | boolean (default false): title and icon in the destructive colour |
| `onPress` | (event) => void: makes the row pressable (role button) |
| `disabled` | boolean (default false): pressable rows only |
| `children` | escape hatch replacing the title and description column |
| `style` | layout only, merged last onto the root |

### Accessibility

- ListSection has role list and ListSectionHeader role heading.
- A row with onPress or onLongPress has role button, named by its text, with its tap area extended to 48; other rows have role listitem.
- disabled is announced as disabled on a pressable row and blocks presses.
- Row icons, the chevron and the Separators between rows are decorative.

### Notes

Props-based rows are a deliberate exception to 'children over content props'; use children only for custom rows. ListSection draws an inset, rounded group with hairline Separators between rows. For long lists, render ListItem directly as a FlashList/FlatList row (no ListSection) with Separator as ItemSeparatorComponent: ListItem has no state, no layout measuring and no parent context, so recycling is safe.

---

## Progress

Source: https://nativecn.dev/docs/components/progress

> A horizontal progress bar: a value 0–100 that animates, or indeterminate; role progressbar with its value.

Component · feedback. Registry item `progress`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/progress.json

### Installation

```sh
npx nativecn-cli@latest add progress
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [use-motion](https://nativecn.dev/docs/primitives/use-motion).

Packages: `react-native-reanimated`, `react-native-worklets`.

### Usage

#### Progress demo

A determinate bar that fills up, and an indeterminate one.

```tsx
import { useEffect, useState } from "react";
import { View } from "react-native";

import { Progress } from "@/components/progress";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({
  stack: { gap: t.spacing[6] },
}));

/** A determinate bar that fills up, and an indeterminate one. */
export default function ProgressDemo() {
  const styles = useStyles();
  const [value, setValue] = useState(13);

  useEffect(() => {
    const timer = setTimeout(() => setValue(66), 500);
    return () => clearTimeout(timer);
  }, []);

  return (
    <View style={styles.stack}>
      <Progress value={value} accessibilityHint="Upload progress" />
      <Progress indeterminate />
    </View>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `value` | number 0–100, clamped (default 0) |
| `indeterminate` | boolean (default false): a bar sweeps along the track; announced busy |

### Accessibility

- role progressbar with aria-valuemin 0, aria-valuemax 100 and aria-valuenow (left out while indeterminate).
- An indeterminate bar is announced busy.
- Name it with aria-label, e.g. "Step 2 of 4".
- Under Reduce Motion value changes are instant and the indeterminate sweep is still.

### Notes

Value changes animate with the base motion Token. The track height comes from the progress.track Style Slot; set its width with style.

---

## RadioGroup

Source: https://nativecn.dev/docs/components/radio-group

> RadioGroup and RadioGroupItem: a single choice from a list on the SelectionGroup Primitive, vertical or horizontal, with a haptic tick.

Component · forms. Registry item `radio-group`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/radio-group.json

### Installation

```sh
npx nativecn-cli@latest add radio-group
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [pressable](https://nativecn.dev/docs/primitives/pressable), [selection-group](https://nativecn.dev/docs/primitives/selection-group), [text](https://nativecn.dev/docs/components/text).

### Usage

#### RadioGroup demo

A vertical and a horizontal RadioGroup, with a disabled item.

```tsx
import { useState } from "react";
import { View } from "react-native";

import { RadioGroup, RadioGroupItem } from "@/components/radio-group";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({
  root: { gap: t.spacing[6] },
}));

export default function RadioGroupDemo() {
  const styles = useStyles();
  const [plan, setPlan] = useState("monthly");

  return (
    <View style={styles.root}>
      <RadioGroup value={plan} onValueChange={setPlan}>
        <RadioGroupItem value="monthly" label="Monthly" />
        <RadioGroupItem value="yearly" label="Yearly" />
        <RadioGroupItem value="lifetime" label="Lifetime (sold out)" disabled />
      </RadioGroup>
      <RadioGroup defaultValue="m" orientation="horizontal">
        <RadioGroupItem value="s" label="S" />
        <RadioGroupItem value="m" label="M" />
        <RadioGroupItem value="l" label="L" />
      </RadioGroup>
    </View>
  );
}
```

### Props

#### RadioGroup

| Prop | Type and description |
|---|---|
| `value` | string: the controlled selected value |
| `defaultValue` | string: the starting value while uncontrolled |
| `onValueChange` | (value: string) => void: called with the newly selected value |
| `orientation` | "vertical" (default) \| "horizontal" |
| `disabled` | boolean: disables every item |
| `style` | layout only, merged last onto the root |

#### RadioGroupItem

| Prop | Type and description |
|---|---|
| `value` | string (required): the value this item selects |
| `label` | string: visible text next to the dot, also the accessible name |
| `disabled` | boolean: this item only |
| `style` | layout only, merged last onto the root |

### Accessibility

- Announced as a radiogroup of radio items with aria-checked.
- An item's label is its accessible name.
- Each row is the tap target, at least 48.
- disabled, on the group or an item, is announced as disabled and blocks selection.

### Notes

Named exports RadioGroup and RadioGroupItem. A light haptic tick on selection when config.haptics is on. The dot uses the radio.dot Style Slot and the pressed look radio.pressed.

---

## SchemeSwitcher

Source: https://nativecn.dev/docs/components/scheme-switcher

> Theme switcher / dark mode toggle: System, Light and Dark as SegmentedTabs, or one icon button cycling through them. Calls setScheme, which persists the choice.

Component · utility. Registry item `scheme-switcher`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/scheme-switcher.json

### Installation

```sh
npx nativecn-cli@latest add scheme-switcher
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [segmented-tabs](https://nativecn.dev/docs/components/segmented-tabs), [button](https://nativecn.dev/docs/components/button).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`.

### Usage

#### SchemeSwitcher demo

The segmented and icon Variants, sharing the persisted Scheme.

```tsx
import { View } from "react-native";

import { SchemeSwitcher } from "@/components/scheme-switcher";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({
  root: { gap: t.spacing[6] },
  icon: { alignSelf: "flex-start" },
}));

// Both Variants share the persisted Scheme: changing one updates the other.
export default function SchemeSwitcherDemo() {
  const styles = useStyles();
  return (
    <View style={styles.root}>
      <SchemeSwitcher />
      <SchemeSwitcher variant="icon" style={styles.icon} />
    </View>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `variant` | "segmented" (default): System / Light / Dark tabs \| "icon": one icon-only Button cycling System → Light → Dark |
| `disabled` | boolean: blocks changes (default false) |
| `style` | ViewStyle, layout only, merged last |

### Variants

- `segmented`, `icon`

### Accessibility

- segmented: a tablist named "Theme" with System, Light and Dark tabs, aria-selected on the current one.
- icon: an icon-only Button named "Theme: <Scheme>" (e.g. "Theme: Dark"), with a 48 tap area.
- disabled is announced as disabled and blocks changes.

### Notes

Lets the user choose the light/dark Scheme. Both Variants read `schemePreference` and call `setScheme` from useTheme(), which persists the choice (AsyncStorage, `nativecn-theme`) and makes native chrome follow; ThemeProvider must wrap the root Layout. `segmented` is SegmentedTabs with System (smartphone), Light (sun) and Dark (moon). `icon` is an icon-only ghost Button showing the current Scheme's icon; each press moves to the next Scheme. To switch from code instead, call setScheme('system' | 'light' | 'dark') from useTheme().

---

## SearchField

Source: https://nativecn.dev/docs/components/search-field

> Search box with a search icon, an automatic clear (×) button, a loading spinner and onSubmit from the keyboard's Search key.

Component · forms. Registry item `search-field`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/search-field.json

### Installation

```sh
npx nativecn-cli@latest add search-field
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [pressable](https://nativecn.dev/docs/primitives/pressable), [icon](https://nativecn.dev/docs/components/icon), [spinner](https://nativecn.dev/docs/components/spinner), [use-controllable-state](https://nativecn.dev/docs/primitives/use-controllable-state).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`.

### Usage

#### SearchField demo

A controlled SearchField with loading and onSubmit.

```tsx
import { useState } from "react";

import { SearchField } from "@/components/search-field";

export function SearchFieldDemo() {
  const [query, setQuery] = useState("");
  const [loading, setLoading] = useState(false);

  return (
    <SearchField
      value={query}
      onChangeText={setQuery}
      placeholder="Search recipes"
      loading={loading}
      onSubmit={() => {
        setLoading(true);
        setTimeout(() => setLoading(false), 800);
      }}
    />
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `value` | string (controlled) |
| `defaultValue` | string (uncontrolled) |
| `onChangeText` | (text: string) => void |
| `onSubmit` | (value: string) => void: the keyboard's Search key |
| `placeholder` | string (default "Search"); also the accessible name |
| `loading` | boolean: the Spinner replaces the search icon; the field is announced busy |
| `disabled` | boolean |
| `ref` | Ref<TextInput> |
| `style` | ViewStyle, layout only, merged last |

### Accessibility

- The field has role searchbox; its name is aria-label, else the placeholder ("Search" by default).
- While loading, the field is announced busy and the Spinner stays silent.
- The clear button is named "Clear search", with its tap area extended to 48.
- The frame extends the tap area to 48 above and below, and a tap there focuses the field; screen readers skip the frame.
- disabled sets aria-disabled, makes the field read-only and hides the clear button.

### Notes

The clear button appears while there is text; it clears it (calling onChangeText("")) and keeps focus. TextInput props pass through.

---

## SegmentedTabs

Source: https://nativecn.dev/docs/components/segmented-tabs

> In-screen tabs (not navigation): segmented or underline Variants, an animated indicator, and only the selected tab's content rendered.

Component · navigation. Registry item `segmented-tabs`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/segmented-tabs.json

### Installation

```sh
npx nativecn-cli@latest add segmented-tabs
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [selection-group](https://nativecn.dev/docs/primitives/selection-group), [pressable](https://nativecn.dev/docs/primitives/pressable), [text](https://nativecn.dev/docs/components/text), [icon](https://nativecn.dev/docs/components/icon), [use-controllable-state](https://nativecn.dev/docs/primitives/use-controllable-state), [use-motion](https://nativecn.dev/docs/primitives/use-motion).

Packages: `react-native-reanimated`, `react-native-worklets`, `lucide-react-native@^1.51.0`, `react-native-svg`.

### Usage

#### SegmentedTabs demo

Uncontrolled segmented tabs with icons, and controlled underline tabs.

```tsx
import { Bell, User } from "lucide-react-native";
import { useState } from "react";
import { View } from "react-native";

import {
  SegmentedTabs,
  SegmentedTabsContent,
  SegmentedTabsList,
  SegmentedTabsTrigger,
} from "@/components/segmented-tabs";
import { Text } from "@/components/text";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({ root: { gap: t.spacing[8] } }));

export default function SegmentedTabsDemo() {
  const styles = useStyles();
  const [period, setPeriod] = useState("week");
  return (
    <View style={styles.root}>
      {/* Uncontrolled, segmented (the default Variant), with icons. */}
      <SegmentedTabs defaultValue="account">
        <SegmentedTabsList>
          <SegmentedTabsTrigger value="account" label="Account" icon={User} />
          <SegmentedTabsTrigger value="notifications" label="Notifications" icon={Bell} />
        </SegmentedTabsList>
        <SegmentedTabsContent value="account">
          <Text>Your name, email and password.</Text>
        </SegmentedTabsContent>
        <SegmentedTabsContent value="notifications">
          <Text>Choose what we send you.</Text>
        </SegmentedTabsContent>
      </SegmentedTabs>

      {/* Controlled, underline. */}
      <SegmentedTabs value={period} onValueChange={setPeriod} variant="underline">
        <SegmentedTabsList>
          <SegmentedTabsTrigger value="day" label="Day" />
          <SegmentedTabsTrigger value="week" label="Week" />
          <SegmentedTabsTrigger value="month" label="Month" />
        </SegmentedTabsList>
        <SegmentedTabsContent value="day">
          <Text>Activity today.</Text>
        </SegmentedTabsContent>
        <SegmentedTabsContent value="week">
          <Text>Activity this week.</Text>
        </SegmentedTabsContent>
        <SegmentedTabsContent value="month">
          <Text>Activity this month.</Text>
        </SegmentedTabsContent>
      </SegmentedTabs>
    </View>
  );
}
```

### Props

#### SegmentedTabs

| Prop | Type and description |
|---|---|
| `value` | string: the selected tab's value (controlled) |
| `defaultValue` | string: the tab selected first (uncontrolled) |
| `onValueChange` | (value: string) => void: called when the user picks a tab |
| `variant` | "segmented" (default) \| "underline" |
| `disabled` | boolean: disables every tab (default false) |
| `style` | ViewStyle, layout only, merged last |

#### SegmentedTabsList

| Prop | Type and description |
|---|---|
| `children` | SegmentedTabsTrigger elements; announced as a tablist |
| `style` | ViewStyle, layout only, merged last |

#### SegmentedTabsTrigger

| Prop | Type and description |
|---|---|
| `value` | string: identifies the tab (required) |
| `label` | string: the visible text and accessible name (required) |
| `icon` | LucideIcon: shown before the label |
| `disabled` | boolean: disables this tab (default false) |
| `style` | ViewStyle, layout only, merged last |

#### SegmentedTabsContent

| Prop | Type and description |
|---|---|
| `value` | string: the tab this panel belongs to; rendered only while it is selected |
| `style` | ViewStyle, merged last |

### Variants

- `segmented`, `underline`

### Accessibility

- SegmentedTabsList is a tablist; each SegmentedTabsTrigger has role tab with aria-selected.
- SegmentedTabsContent has role tabpanel.
- A trigger's label is its accessible name, and its tap area is at least 48.
- disabled tabs are announced as disabled.
- The sliding indicator is hidden from screen readers and jumps instantly under Reduce Motion.

### Notes

For switching views inside one Screen (Account / Notifications, Day / Week / Month). It is not navigation: never use it in place of Expo Router's Tabs; the bottom tab bar is TabNavigation. Put SegmentedTabsTriggers in a SegmentedTabsList, then one SegmentedTabsContent per tab after it; only the selected Content renders. Works controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`). Tabs give a light haptic tick when chosen. The indicator slides with the `fast` motion Token. Styles come from the segmented-tabs.list, segmented-tabs.trigger and segmented-tabs.pressed Style Slots.

---

## Separator

Source: https://nativecn.dev/docs/components/separator

> A hairline divider, horizontal or vertical, decorative by default.

Component · display. Registry item `separator`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/separator.json

### Installation

```sh
npx nativecn-cli@latest add separator
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme).

### Usage

#### Separator demo

Horizontal and vertical Separators.

```tsx
import { View } from "react-native";

import { Separator } from "@/components/separator";
import { Text } from "@/components/text";
import { createStyles } from "@/theme";

export default function SeparatorDemo() {
  const styles = useStyles();
  return (
    <View style={styles.stack}>
      <Text variant="h4">nativecn</Text>
      <Text variant="small" color="mutedForeground">
        Components for Expo apps.
      </Text>
      <Separator />
      <View style={styles.row}>
        <Text variant="small">Docs</Text>
        <Separator orientation="vertical" />
        <Text variant="small">Blocks</Text>
        <Separator orientation="vertical" />
        <Text variant="small">Themes</Text>
      </View>
    </View>
  );
}

const useStyles = createStyles((t) => ({
  stack: { gap: t.spacing[3] },
  row: { flexDirection: "row", alignItems: "center", gap: t.spacing[3] },
}));
```

### Props

| Prop | Type and description |
|---|---|
| `orientation` | "horizontal" (default) \| "vertical" |
| `decorative` | boolean (default true): hidden from screen readers; false exposes it with role separator |
| `style` | merged last |

### Accessibility

- Decorative by default: hidden from screen readers.
- decorative={false} exposes it with role separator.

### Notes

A vertical Separator stretches to its row's height, so put it in a row with alignItems center. Between virtualized ListItems, pass it as FlashList's ItemSeparatorComponent.

---

## Skeleton

Source: https://nativecn.dev/docs/components/skeleton

> A placeholder shape shown while content loads; pulses unless Reduce Motion is on, hidden from screen readers.

Component · feedback. Registry item `skeleton`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/skeleton.json

### Installation

```sh
npx nativecn-cli@latest add skeleton
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [use-motion](https://nativecn.dev/docs/primitives/use-motion).

Packages: `react-native-reanimated`, `react-native-worklets`.

### Usage

#### Skeleton demo

A list row while it loads: an avatar circle and two lines.

```tsx
import { View } from "react-native";

import { Skeleton } from "@/components/skeleton";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({
  row: { flexDirection: "row", alignItems: "center", gap: t.spacing[4] },
  lines: { flex: 1, gap: t.spacing[2] },
}));

/** A list row while it loads: an avatar circle and two lines of text, announced busy once. */
export default function SkeletonDemo() {
  const styles = useStyles();
  return (
    <View style={styles.row} accessible aria-busy aria-label="Loading profile">
      <Skeleton circle height={48} />
      <View style={styles.lines}>
        <Skeleton width="70%" height={16} />
        <Skeleton width="45%" height={16} />
      </View>
    </View>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `width` | number \| percentage string |
| `height` | number \| percentage string; with circle and no width, also the width |
| `circle` | boolean (default false): fully rounded |

### Accessibility

- Always hidden from screen readers: put aria-busy and an aria-label on the loading container instead.
- Still under Reduce Motion: it does not pulse.

### Notes

Pulses with the slow motion Token. The corner radius comes from the skeleton.root Style Slot.

---

## Slider

Source: https://nativecn.dev/docs/components/slider

> Pick a number in a range by dragging or tapping (Gesture Handler + Reanimated), snapped to steps with a haptic tick; adjustable for screen readers.

Component · forms. Registry item `slider`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/slider.json

### Installation

```sh
npx nativecn-cli@latest add slider
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [form-field-context](https://nativecn.dev/docs/primitives/form-field-context), [use-controllable-state](https://nativecn.dev/docs/primitives/use-controllable-state), [use-motion](https://nativecn.dev/docs/primitives/use-motion).

Packages: `expo-haptics`, `react-native-gesture-handler`, `react-native-reanimated`, `react-native-worklets`.

### Usage

#### Slider demo

A controlled volume Slider with its value shown, and a stepped rating.

```tsx
import { useState } from "react";
import { View } from "react-native";

import { Slider } from "@/components/slider";
import { Text } from "@/components/text";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({ root: { gap: t.spacing[4] } }));

/** A controlled volume Slider with its value shown, and an uncontrolled stepped one. */
export function SliderDemo() {
  const styles = useStyles();
  const [volume, setVolume] = useState(40);

  return (
    <View style={styles.root}>
      <Text variant="label">Volume: {volume}%</Text>
      <Slider
        aria-label="Volume"
        aria-valuetext={`${volume} percent`}
        value={volume}
        onValueChange={setVolume}
      />
      <Text variant="label">Rating</Text>
      <Slider aria-label="Rating" min={1} max={5} defaultValue={3} />
    </View>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `value` | number (controlled) |
| `defaultValue` | number (uncontrolled, default min) |
| `onValueChange` | (value: number) => void: each new stepped value while dragging, and on increment/decrement |
| `onSlidingComplete` | (value: number) => void: when a drag or tap ends, and after increment/decrement |
| `min` | number (default 0) |
| `max` | number (default 100) |
| `step` | number (default 1): values always snap to a step |
| `disabled` | boolean: no dragging or actions, dimmed |
| `aria-label` | string: the accessible name (a FormField label provides it) |
| `aria-valuetext` | string: a spoken value with units, e.g. "40 percent" |
| `style` | ViewStyle, layout only (e.g. width, flex), merged last onto the outermost View |

### Accessibility

- An adjustable control: role slider on Android and web, and accessibilityRole adjustable on iOS (a recorded exception, so VoiceOver users can swipe up and down).
- It exposes aria-valuemin, aria-valuemax and aria-valuenow; the increment and decrement actions move it one step.
- Name it with aria-label (a FormField label provides it); aria-valuetext gives a spoken value with units.
- The row is at least 48 high.
- disabled blocks dragging and the actions, and is announced as disabled.
- The thumb moves instantly under Reduce Motion.

### Notes

Brings its own small GestureHandlerRootView, sized to the Slider, so it works whether or not the app root has one (Expo Router does not add one). The drag runs on the UI thread; horizontal drags only, so a vertical scroll still works. A light haptic tick per step when config.haptics is on. Track and thumb sizes come from the slider.track and slider.thumb Style Slots.

---

## Spinner

Source: https://nativecn.dev/docs/components/spinner

> An indeterminate loading indicator in a Colour Role, announced as busy; still under Reduce Motion.

Component · feedback. Registry item `spinner`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/spinner.json

### Installation

```sh
npx nativecn-cli@latest add spinner
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [icon](https://nativecn.dev/docs/components/icon), [use-motion](https://nativecn.dev/docs/primitives/use-motion).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`, `react-native-reanimated`, `react-native-worklets`.

### Usage

#### Spinner demo

Spinners in each size, a Colour Role and a specific name.

```tsx
import { View } from "react-native";

import { Spinner } from "@/components/spinner";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({
  row: { flexDirection: "row", alignItems: "center", gap: t.spacing[6] },
}));

/** The three sizes, a Colour Role and a specific accessible name. */
export default function SpinnerDemo() {
  const styles = useStyles();
  return (
    <View style={styles.row}>
      <Spinner size="sm" />
      <Spinner />
      <Spinner size="lg" color="primary" aria-label="Loading messages" />
    </View>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `size` | sm \| md \| lg (default md): 16 · 20 · 24 from the iconSize Tokens |
| `color` | Colour Role (default foreground) |
| `aria-label` | string (default "Loading") |
| `aria-hidden` | boolean: silences it inside a parent that is already busy |

### Variants

- `sm`, `md`, `lg`

### Accessibility

- role progressbar with aria-busy, named "Loading" by default; aria-label renames it.
- aria-hidden silences it inside a parent that is already busy; Button does this while loading.
- Still under Reduce Motion: it does not turn.

### Notes

A Lucide LoaderCircle turning once every 800ms (2 × the slow motion Token). Button uses it for `loading`. Use it instead of ActivityIndicator.

---

## Switch

Source: https://nativecn.dev/docs/components/switch

> A themed on/off Switch, identical on iOS and Android, with an optional label, a thumb that slides (instant under Reduce Motion) and a haptic tick.

Component · forms. Registry item `switch`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/switch.json

### Installation

```sh
npx nativecn-cli@latest add switch
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [pressable](https://nativecn.dev/docs/primitives/pressable), [form-field-context](https://nativecn.dev/docs/primitives/form-field-context), [text](https://nativecn.dev/docs/components/text), [use-controllable-state](https://nativecn.dev/docs/primitives/use-controllable-state), [use-motion](https://nativecn.dev/docs/primitives/use-motion).

Packages: `react-native-reanimated`, `react-native-worklets`.

### Usage

#### Switch demo

A controlled Switch with a label, an uncontrolled one and a disabled one.

```tsx
import { useState } from "react";
import { View } from "react-native";

import { Switch } from "@/components/switch";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({
  root: { gap: t.spacing[4] },
}));

export default function SwitchDemo() {
  const styles = useStyles();
  const [notifications, setNotifications] = useState(true);

  return (
    <View style={styles.root}>
      <Switch label="Notifications" checked={notifications} onCheckedChange={setNotifications} />
      <Switch label="Airplane mode" />
      <Switch label="Managed by your organisation" defaultChecked disabled />
    </View>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `checked` | boolean: the controlled on/off state |
| `defaultChecked` | boolean: the starting state while uncontrolled (default false) |
| `onCheckedChange` | (checked: boolean) => void: called when the user toggles it |
| `label` | string: visible text next to the switch, also the accessible name |
| `disabled` | boolean: dimmed, announced as disabled, no handler runs |
| `style` | layout only, merged last onto the root |

### Accessibility

- role switch with aria-checked.
- The label is the accessible name; without a label, pass aria-label.
- The tap area is at least 48.
- disabled is announced as disabled and no handler runs.
- Inside a FormField the field's label and error become its name and hint.
- The thumb jumps instantly under Reduce Motion.

### Notes

Not the OS Switch: drawn by nativecn so both platforms look the same. The thumb slides with the fast motion Token. A light haptic tick on toggle when config.haptics is on. Inside a FormField it takes the field's disabled. The track uses the switch.track Style Slot and the pressed look switch.pressed.

---

## TabNavigation

Source: https://nativecn.dev/docs/components/tab-navigation

> The bottom tab bar: the custom tabBar of an Expo Router JS Tabs Layout, with classic and floating Variants, per-tab icons and badges from Tabs.Screen options.

Component · navigation. Registry item `tab-navigation`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/tab-navigation.json

### Installation

```sh
npx nativecn-cli@latest add tab-navigation
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [pressable](https://nativecn.dev/docs/primitives/pressable), [text](https://nativecn.dev/docs/components/text), [icon](https://nativecn.dev/docs/components/icon), [badge](https://nativecn.dev/docs/components/badge).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`, `react-native-safe-area-context`.

### Usage

#### TabNavigation demo

A tabs Layout using TabNavigation (floating) as the tabBar of Expo Router's JS Tabs, with icons and a badge.

```tsx
import { Tabs } from "expo-router/js-tabs";
import { Bell, House, Search, User } from "lucide-react-native";

import { TabNavigation, tabIcon } from "@/components/tab-navigation";

// A tabs Layout, e.g. app/(tabs)/_layout.tsx: Expo Router's JS Tabs with TabNavigation as its
// tab bar. Each Tabs.Screen gives its title, icon and (optional) badge.
export default function TabsLayout() {
  return (
    <Tabs tabBar={(props) => <TabNavigation {...props} variant="floating" />}>
      <Tabs.Screen name="index" options={{ title: "Home", tabBarIcon: tabIcon(House) }} />
      <Tabs.Screen name="search" options={{ title: "Search", tabBarIcon: tabIcon(Search) }} />
      <Tabs.Screen
        name="inbox"
        options={{ title: "Inbox", tabBarIcon: tabIcon(Bell), tabBarBadge: 3 }}
      />
      <Tabs.Screen name="profile" options={{ title: "Profile", tabBarIcon: tabIcon(User) }} />
    </Tabs>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `...BottomTabBarProps` | state, descriptors, navigation, insets: what Expo Router's JS Tabs pass to tabBar; spread them in |
| `variant` | "classic" (default): full-width bar with a top border \| "floating": inset pill with the Style's radius and a large shadow, above the bottom safe area |
| `options.title / options.tabBarLabel` | Tabs.Screen option: the tab's label and accessible name (a string, or a render function) |
| `options.tabBarIcon` | Tabs.Screen option: ({ focused, color, size }) => ReactNode; use tabIcon(LucideIcon) to draw it with Icon |
| `options.tabBarBadge` | Tabs.Screen option: number \| string shown as a destructive Badge on the icon and spoken ("Inbox, 3 new") |
| `options.tabBarAccessibilityLabel` | Tabs.Screen option: replaces the spoken name |
| `options.tabBarButtonTestID` | Tabs.Screen option: the tab's testID |
| `options.tabBarShowLabel` | Tabs.Screen option: false hides the label (default true) |
| `options.tabBarStyle` | { display: 'none' } on a Screen hides the bar while it is focused |
| `tabIcon(icon)` | turns a Lucide icon into a tabBarIcon option, drawn with Icon |
| `style` | ViewStyle, layout only, merged last onto the root |

### Variants

- `variant`: `classic`, `floating`

### Accessibility

- The bar is a tablist; each tab has role tab, with aria-selected on the active one.
- A tab's name is its label plus its badge ("Inbox, 3 new" for a count); tabBarAccessibilityLabel replaces it.
- Each tab's tap area is at least 48 × 48.
- String labels use the caption text Variant, which caps the OS font scale at 1.5× when font scaling is on.

### Notes

Use it only as the tabBar of Expo Router's JavaScript Tabs (`import { Tabs } from "expo-router/js-tabs"`), never with NativeTabs and never for in-screen tabs (that is SegmentedTabs): `<Tabs tabBar={(props) => <TabNavigation {...props} variant="floating" />}>`. Each Tabs.Screen gives its title, tabBarIcon and optional tabBarBadge; Screens with `href: null` are skipped. A press emits tabPress (call e.preventDefault() in a listener to stop it), then navigates; a long press emits tabLongPress. The active tab is drawn in primary, the others in mutedForeground; the bar uses the card and border Colour Roles. Sizes come from the tab-navigation.bar, .icon, .label, .floating and .pressed Style Slots.

---

## Text

Source: https://nativecn.dev/docs/components/text

> All text: the type ramp as Variants, text Colour Roles, alignment and the font-scaling switch.

Component · core. Registry item `text`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/text.json

### Installation

```sh
npx nativecn-cli@latest add text
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme).

### Usage

#### Text demo

Headings, body, small and caption text in Colour Roles.

```tsx
import { View } from "react-native";

import { Text } from "@/components/text";
import { createStyles } from "@/theme";

/** The type ramp, text Colour Roles and alignment. */
export default function TextDemo() {
  const styles = useStyles();
  return (
    <View style={styles.stack}>
      <Text variant="h1">Welcome back</Text>
      <Text variant="lead" color="mutedForeground">
        Pick up where you left off.
      </Text>
      <Text>Body text is selectable by default, so people can copy it.</Text>
      <Text variant="small" color="mutedForeground">
        Last synced 2 minutes ago
      </Text>
      <Text variant="caption" color="destructive">
        Your trial ends tomorrow
      </Text>
      <Text variant="label" align="center">
        Centred label
      </Text>
    </View>
  );
}

const useStyles = createStyles((t) => ({
  stack: { gap: t.spacing[2] },
}));
```

### Props

| Prop | Type and description |
|---|---|
| `...TextProps` | React Native Text props pass through (numberOfLines, onPress, ...) |
| `variant` | "display" \| "h1" \| "h2" \| "h3" \| "h4" \| "lead" \| "body" (default) \| "label" \| "small" \| "caption" \| "button" |
| `color` | a text Colour Role: "foreground" (default), any "…Foreground" role, "primary", "destructive", "success", "warning", "info" |
| `align` | "auto" \| "left" \| "right" \| "center" \| "justify" |
| `selectable` | boolean (default true for body and small, false otherwise) |
| `allowFontScaling` | boolean (default: config.fontScaling in theme/config.ts) |
| `ref` | Ref<Text> |
| `style` | TextStyle, merged last |

### Variants

- `display`, `h1`, `h2`, `h3`, `h4`, `lead`, `body`, `label`, `small`, `caption`, `button`

### Accessibility

- display and h1–h4 have role heading, so screen readers can jump between headings.
- Font scaling follows the switch in theme/config.ts (off by default); allowFontScaling overrides it for one Text.
- When font scaling is on, the chrome Variants (label, caption, button) cap the OS font scale at 1.5×.

### Notes

The single typographic Component: use it for all text, never React Native's Text or a separate Heading. display and h1–h4 use the Heading Font; the rest use the Body Font.

---

## Textarea

Source: https://nativecn.dev/docs/components/textarea

> Multi-line text field that grows from minRows to maxRows, with a character counter when maxLength is set.

Component · forms. Registry item `textarea`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/textarea.json

### Installation

```sh
npx nativecn-cli@latest add textarea
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [input](https://nativecn.dev/docs/components/input), [text](https://nativecn.dev/docs/components/text), [use-controllable-state](https://nativecn.dev/docs/primitives/use-controllable-state).

### Usage

#### Textarea demo

A Textarea with a character counter inside a FormField.

```tsx
import { FormField } from "@/components/form-field";
import { Textarea } from "@/components/textarea";

export function TextareaDemo() {
  return (
    <FormField label="Bio" description="Tell people a little about yourself.">
      <Textarea placeholder="I like…" maxLength={160} minRows={3} maxRows={6} />
    </FormField>
  );
}
```

### Props

| Prop | Type and description |
|---|---|
| `...InputProps` | Input's props except icon and secureTextEntry |
| `minRows` | number: rows shown when empty (default 3) |
| `maxRows` | number: grows up to this many rows, then scrolls (default 8) |
| `maxLength` | number: limits the text and shows an n/max counter |
| `style` | ViewStyle, layout only, merged last onto the root |

### Variants

- `size`: `sm`, `md`, `lg`
- `status`: `error`, `success`

### Accessibility

- Named and hinted like Input: aria-label or the FormField label is the name, and the error or description the hint.
- A new status is announced once, unless a FormField is already announcing its error.
- disabled sets aria-disabled and makes the field read-only.
- The counter is read as "n of max characters".

### Notes

FocusChain skips Textarea so Enter keeps adding new lines. Works controlled (value + onChangeText) or uncontrolled (defaultValue).

---

## Toast

Source: https://nativecn.dev/docs/components/toast

> Sonner-style Toasts: a <Toaster /> in the root Layout and toast(), toast.success/error/info/warning/dismiss. At most 3 stacked, 4s auto-dismiss, swipe away, announced, above native modals.

Component · feedback. Registry item `toast`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/toast.json

### Installation

```sh
npx nativecn-cli@latest add toast
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [portal](https://nativecn.dev/docs/primitives/portal), [text](https://nativecn.dev/docs/components/text), [icon](https://nativecn.dev/docs/components/icon), [button](https://nativecn.dev/docs/components/button), [use-motion](https://nativecn.dev/docs/primitives/use-motion), [announce](https://nativecn.dev/docs/primitives/announce).

Packages: `zustand@^5.0.15`, `react-native-gesture-handler`, `react-native-reanimated`, `react-native-worklets`, `lucide-react-native@^1.51.0`, `react-native-svg`.

### Usage

#### Toast demo

Each Toast Variant, a description and an action.

```tsx
import { View } from "react-native";

import { Button } from "@/components/button";
import { toast } from "@/components/toast";
import { createStyles } from "@/theme";

const useStyles = createStyles((t) => ({ root: { gap: t.spacing[3] } }));

// Needs <PortalHost /> and <Toaster /> in the root Layout (`init` and `create` add both).
export default function ToastDemo() {
  const styles = useStyles();
  return (
    <View style={styles.root}>
      <Button label="Default" variant="outline" onPress={() => toast("Draft saved")} />
      <Button label="Success" variant="outline" onPress={() => toast.success("Profile updated")} />
      <Button
        label="Error"
        variant="outline"
        onPress={() => toast.error("Wrong password", { description: "Check it and try again." })}
      />
      <Button
        label="With action"
        variant="outline"
        onPress={() =>
          toast("Message archived", {
            action: { label: "Undo", onPress: () => toast.info("Message restored") },
          })
        }
      />
      <Button label="Dismiss all" variant="ghost" onPress={() => toast.dismiss()} />
    </View>
  );
}
```

### Props

#### Toaster

| Prop | Type and description |
|---|---|
| `position` | "top" (default) \| "bottom": the edge Toasts appear at; the newest is nearest it |
| `hostName` | the PortalHost to render into (default: the root host) |

#### toast

| Prop | Type and description |
|---|---|
| `toast(title, options?)` | shows a default Toast and returns its id |
| `toast.success / .error / .info / .warning` | same signature, with the Variant's icon |
| `toast.dismiss(id?)` | dismisses one Toast, or all of them without an id |
| `options.description` | a second, quieter line |
| `options.duration` | ms before it dismisses itself (default 4000; Infinity to keep it) |
| `options.action` | { label, onPress }: one button; pressing it also dismisses |
| `options.id` | reuse an id to update a Toast in place |

### Variants

- `default`, `success`, `error`, `info`, `warning`

### Accessibility

- Each Toast is announced when it appears and again when updated in place; success, error, info and warning Toasts start with "Success:", "Error:", "Info:" or "Warning:".
- The title and description are read as one element with a Dismiss action; VoiceOver's escape gesture also dismisses it.
- Enter, exit and reflow animations are off under Reduce Motion, which is followed live.
- The action is a Button: role button, with a 48 tap area.

### Notes

Render one <Toaster /> in the root Layout next to <PortalHost /> (inside ThemeProvider); `init` and `create` already do. Call toast() from anywhere, including outside React. Server errors and success messages go through toast(), never Alert.alert. At most 3 are visible, stacked, newest nearest the edge; more wait in the queue. Each auto-dismisses after 4s (paused while touched) and can be swiped sideways or towards its edge. Animations follow the motion Tokens. The surface uses the toast.root Style Slot.

---

## Profile header + grouped sections

Source: https://nativecn.dev/docs/blocks/drawer-01

> Drawer panel with a profile header (avatar, name, email, plan Badge), labelled sections (Main, Workspace, Support) and Log out pinned in the footer.

Block · navigation. Registry item `drawer-01`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/drawer-01.json

### Installation

```sh
npx nativecn-cli@latest add drawer-01
```

Also installs: [drawer](https://nativecn.dev/docs/components/drawer), [avatar](https://nativecn.dev/docs/components/avatar), [badge](https://nativecn.dev/docs/components/badge), [separator](https://nativecn.dev/docs/components/separator), [text](https://nativecn.dev/docs/components/text), [theme](https://nativecn.dev/docs/theme/theme).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`.

### What makes it different

The familiar Gmail/Slack drawer: who is signed in on top, items grouped under small headings, Log out at the bottom; the active item sits on a muted background.

### Block Variants

- **drawer-01** (this page) – Profile header + grouped sections: The familiar Gmail/Slack drawer: who is signed in on top, items grouped under small headings, Log out at the bottom; the active item sits on a muted background.
- [drawer-02](https://nativecn.dev/docs/blocks/drawer-02) – SaaS workspace: A product workspace: an Accent-tinted onboarding Checklist on top, a second group pushed to the bottom, and a team switcher and account button in the footer instead of a profile header.
- [drawer-03](https://nativecn.dev/docs/blocks/drawer-03) – Cover header: A consumer or commerce app drawer: a dark profile cover that stays dark in both Schemes (with a light status bar over it while the drawer is open), and items that show the current route by Accent Colour text and icon, with no background.

### Accessibility

- Each item is a DrawerItem: role link with aria-selected while its route is active, or role button for an action without href.
- An item's visible label is its accessible name.
- Items are 48 high in Vega and 40 in Nova, with the tap area extended to 48.
- The section titles (Main, Workspace, Support) have role heading.
- The name in the header is a heading (h4); the initials Avatar is decorative.
- Log out is an action item: role button.

### Notes

In app/(drawer)/_layout.tsx, with Expo Router's drawer from expo-router/drawer (never @react-navigation/drawer or the npm package expo-drawer): <Drawer drawerContent={(props) => <Drawer01 {...props} />} />. Spread every drawerContent prop in, so items can close the drawer. Tapping an item navigates and closes the drawer; the backdrop and the system back gesture also close it. Names, avatars, counts, items and routes are placeholders: rename them and point each href at a route in your drawer Layout. Item heights follow the drawer.item Style Slot (Vega 48, Nova 40), and the panel keeps clear of the status bar and home indicator.

---

## SaaS workspace

Source: https://nativecn.dev/docs/blocks/drawer-02

> Drawer panel for a SaaS workspace: logo and name with a close button, an Accent Colour onboarding item with a 5 Steps Badge, main items, a bottom group (Notifications with a count, Settings, Docs, Help) and a footer with a team switcher and the user's avatar.

Block · navigation. Registry item `drawer-02`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/drawer-02.json

### Installation

```sh
npx nativecn-cli@latest add drawer-02
```

Also installs: [drawer](https://nativecn.dev/docs/components/drawer), [avatar](https://nativecn.dev/docs/components/avatar), [badge](https://nativecn.dev/docs/components/badge), [button](https://nativecn.dev/docs/components/button), [icon](https://nativecn.dev/docs/components/icon), [pressable](https://nativecn.dev/docs/primitives/pressable), [text](https://nativecn.dev/docs/components/text), [theme](https://nativecn.dev/docs/theme/theme).

Packages: `lucide-react-native@^1.51.0`, `react-native-svg`.

### What makes it different

A product workspace: an Accent-tinted onboarding Checklist on top, a second group pushed to the bottom, and a team switcher and account button in the footer instead of a profile header.

### Block Variants

- [drawer-01](https://nativecn.dev/docs/blocks/drawer-01) – Profile header + grouped sections: The familiar Gmail/Slack drawer: who is signed in on top, items grouped under small headings, Log out at the bottom; the active item sits on a muted background.
- **drawer-02** (this page) – SaaS workspace: A product workspace: an Accent-tinted onboarding Checklist on top, a second group pushed to the bottom, and a team switcher and account button in the footer instead of a profile header.
- [drawer-03](https://nativecn.dev/docs/blocks/drawer-03) – Cover header: A consumer or commerce app drawer: a dark profile cover that stays dark in both Schemes (with a light status bar over it while the drawer is open), and items that show the current route by Accent Colour text and icon, with no background.

### Accessibility

- Each item is a DrawerItem: role link with aria-selected while its route is active, or role button for an action without href.
- An item's visible label is its accessible name.
- Items are 48 high in Vega and 40 in Nova, with the tap area extended to 48.
- The close button is an icon-only Button named "Close menu"; the logo icon is decorative.
- The footer buttons are named "Switch team, current team Acme Inc" and "Account menu", with their tap areas extended to 48.

### Notes

In app/(drawer)/_layout.tsx, with Expo Router's drawer from expo-router/drawer (never @react-navigation/drawer or the npm package expo-drawer): <Drawer drawerContent={(props) => <Drawer02 {...props} />} />. Spread every drawerContent prop in, so items can close the drawer. Tapping an item navigates and closes the drawer; the backdrop and the system back gesture also close it. Names, avatars, counts, items and routes are placeholders: rename them and point each href at a route in your drawer Layout. Item heights follow the drawer.item Style Slot (Vega 48, Nova 40), and the panel keeps clear of the status bar and home indicator.

---

## Cover header

Source: https://nativecn.dev/docs/blocks/drawer-03

> Drawer panel with a dark cover (large avatar, name, View profile, a bell with a count, an overflow button and a round + action), icon items active in Accent Colour text, a divider and text-only secondary items.

Block · navigation. Registry item `drawer-03`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/drawer-03.json

### Installation

```sh
npx nativecn-cli@latest add drawer-03
```

Also installs: [drawer](https://nativecn.dev/docs/components/drawer), [avatar](https://nativecn.dev/docs/components/avatar), [badge](https://nativecn.dev/docs/components/badge), [button](https://nativecn.dev/docs/components/button), [pressable](https://nativecn.dev/docs/primitives/pressable), [separator](https://nativecn.dev/docs/components/separator), [text](https://nativecn.dev/docs/components/text), [theme](https://nativecn.dev/docs/theme/theme).

Packages: `expo-router`, `lucide-react-native@^1.51.0`, `react-native-svg`.

### What makes it different

A consumer or commerce app drawer: a dark profile cover that stays dark in both Schemes (with a light status bar over it while the drawer is open), and items that show the current route by Accent Colour text and icon, with no background.

### Block Variants

- [drawer-01](https://nativecn.dev/docs/blocks/drawer-01) – Profile header + grouped sections: The familiar Gmail/Slack drawer: who is signed in on top, items grouped under small headings, Log out at the bottom; the active item sits on a muted background.
- [drawer-02](https://nativecn.dev/docs/blocks/drawer-02) – SaaS workspace: A product workspace: an Accent-tinted onboarding Checklist on top, a second group pushed to the bottom, and a team switcher and account button in the footer instead of a profile header.
- **drawer-03** (this page) – Cover header: A consumer or commerce app drawer: a dark profile cover that stays dark in both Schemes (with a light status bar over it while the drawer is open), and items that show the current route by Accent Colour text and icon, with no background.

### Accessibility

- Each item is a DrawerItem: role link with aria-selected while its route is active, or role button for an action without href.
- An item's visible label is its accessible name.
- Items are 48 high in Vega and 40 in Nova, with the tap area extended to 48.
- The bell is an icon-only Button named "Notifications, <count> unread"; its count Badge is hidden from screen readers.
- The overflow and + buttons are icon-only Buttons named "More" and "Create".
- View profile has role link; the initials Avatar is decorative.

### Notes

In app/(drawer)/_layout.tsx, with Expo Router's drawer from expo-router/drawer (never @react-navigation/drawer or the npm package expo-drawer): <Drawer drawerContent={(props) => <Drawer03 {...props} />} />. Spread every drawerContent prop in, so items can close the drawer. Tapping an item navigates and closes the drawer; the backdrop and the system back gesture also close it. Names, avatars, counts, items and routes are placeholders: rename them and point each href at a route in your drawer Layout. Item heights follow the drawer.item Style Slot (Vega 48, Nova 40), and the panel keeps clear of the status bar and home indicator.

---

## Classic centred

Source: https://nativecn.dev/docs/blocks/sign-in-01

> A centred sign-in Screen: logo, email and password, Forgot password, an "or" divider, then Apple and Google, and a Sign up link.

Block · auth. Registry item `sign-in-01`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/sign-in-01.json

### Installation

```sh
npx nativecn-cli@latest add sign-in-01 --route "(auth)/sign-in"
```

- `--route "(auth)/sign-in"` is the Block's suggested route: change it to put the Screen somewhere else in your app folder.
- In a project with the feature Structure, also pass `--feature <name>` (for example `--feature auth`).
- `add` never overwrites an existing route file.

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [container](https://nativecn.dev/docs/components/container), [text](https://nativecn.dev/docs/components/text), [button](https://nativecn.dev/docs/components/button), [form-field](https://nativecn.dev/docs/components/form-field), [input](https://nativecn.dev/docs/components/input), [focus-chain](https://nativecn.dev/docs/primitives/focus-chain), [icon](https://nativecn.dev/docs/components/icon), [separator](https://nativecn.dev/docs/components/separator), [toast](https://nativecn.dev/docs/components/toast).

Packages: `react-hook-form@^7.89.0`, `zod@^4.6.5`, `@hookform/resolvers@^5.9.1`, `lucide-react-native@^1.51.0`, `react-native-svg`.

### What makes it different

Logo, email and password, "or", then social; everything on one screen.

### Block Variants

- **sign-in-01** (this page) – Classic centred: Logo, email and password, "or", then social; everything on one screen.
- [sign-in-02](https://nativecn.dev/docs/blocks/sign-in-02) – Social-first hero: Dark brand hero, centred; Apple/Google are the primary path; "Continue with email" reveals the fields.
- [sign-in-03](https://nativecn.dev/docs/blocks/sign-in-03) – Email-first, two steps: Email → password, one question per step, with "Email me a code instead" (InputOTP).

### Props

| Prop | Type and description |
|---|---|
| `onSubmit` | (values: { email, password }) => void \| Promise<void>: sign in; throw to show the error as a toast, resolve for a "Signed in" toast |
| `onSocialSignIn` | (provider: "apple" \| "google") => void \| Promise<void>: run that provider's sign-in; a thrown error becomes a toast |
| `onForgotPassword` | () => void: the Forgot password? link |
| `onSignUp` | () => void: the Sign up link |

### Accessibility

- "Welcome back" has role heading; the logo icon and the lines around "or" are decorative.
- Each field is in a FormField: its label is the field's accessible name, and a validation error becomes its hint and is announced once.
- Errors from your callbacks and the success message are toast()s, which screen readers announce.
- The submit Button is announced busy while your callback runs.
- Apple and Google are labelled Buttons ("Continue with Apple", "Continue with Google"); their logos are decorative.

### Notes

Render it from a route: `export default function Screen() { return <SignIn01 onSubmit={signIn} />; }`. The email and password are validated with zod through react-hook-form (the email is trimmed), and the fields are in a FocusChain (Next, then Done submits). Validation errors appear under each field. Errors thrown by your callbacks, and the success message, appear only as toast()s: render <Toaster /> in the root Layout (init and create already do). The Apple and Google logos are bundled SVGs in components/social-buttons.tsx; the buttons only call onSocialSignIn. The Block never talks to a server: wire your auth backend in the route file through the props, and keep any session or token in expo-secure-store, never AsyncStorage.

---

## Social-first hero

Source: https://nativecn.dev/docs/blocks/sign-in-02

> A social-first sign-in Screen: a dark brand hero (logo, headline, subtitle, centred) above a panel where Apple and Google lead and "Continue with email" reveals the email form.

Block · auth. Registry item `sign-in-02`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/sign-in-02.json

### Installation

```sh
npx nativecn-cli@latest add sign-in-02 --route "(auth)/sign-in"
```

- `--route "(auth)/sign-in"` is the Block's suggested route: change it to put the Screen somewhere else in your app folder.
- In a project with the feature Structure, also pass `--feature <name>` (for example `--feature auth`).
- `add` never overwrites an existing route file.

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [container](https://nativecn.dev/docs/components/container), [text](https://nativecn.dev/docs/components/text), [button](https://nativecn.dev/docs/components/button), [form-field](https://nativecn.dev/docs/components/form-field), [input](https://nativecn.dev/docs/components/input), [focus-chain](https://nativecn.dev/docs/primitives/focus-chain), [icon](https://nativecn.dev/docs/components/icon), [separator](https://nativecn.dev/docs/components/separator), [toast](https://nativecn.dev/docs/components/toast).

Packages: `react-hook-form@^7.89.0`, `zod@^4.6.5`, `@hookform/resolvers@^5.9.1`, `lucide-react-native@^1.51.0`, `react-native-svg`, `react-native-safe-area-context`.

### What makes it different

Dark brand hero, centred; Apple/Google are the primary path; "Continue with email" reveals the fields.

### Block Variants

- [sign-in-01](https://nativecn.dev/docs/blocks/sign-in-01) – Classic centred: Logo, email and password, "or", then social; everything on one screen.
- **sign-in-02** (this page) – Social-first hero: Dark brand hero, centred; Apple/Google are the primary path; "Continue with email" reveals the fields.
- [sign-in-03](https://nativecn.dev/docs/blocks/sign-in-03) – Email-first, two steps: Email → password, one question per step, with "Email me a code instead" (InputOTP).

### Props

| Prop | Type and description |
|---|---|
| `onSubmit` | (values: { email, password }) => void \| Promise<void>: sign in; throw to show the error as a toast, resolve for a "Signed in" toast |
| `onSocialSignIn` | (provider: "apple" \| "google") => void \| Promise<void>: run that provider's sign-in; a thrown error becomes a toast |

### Accessibility

- The headline has role heading; the logo icon and the lines around "or" are decorative.
- Each field is in a FormField: its label is the field's accessible name, and a validation error becomes its hint and is announced once.
- Errors from your callbacks and the success message are toast()s, which screen readers announce.
- The submit Button is announced busy while your callback runs.
- Apple and Google are labelled Buttons ("Continue with Apple", "Continue with Google"); their logos are decorative.

### Notes

Render it from a route: `export default function Screen() { return <SignIn02 onSocialSignIn={signInWith} onSubmit={signIn} />; }`. The hero is drawn with the dark Scheme's Colour Roles in both Schemes (a nested ThemeProvider scheme="dark") and runs under a light status bar. The email form appears only after "Continue with email"; it is validated with zod through react-hook-form, in a FocusChain. Validation errors appear under each field. Errors thrown by your callbacks, and the success message, appear only as toast()s: render <Toaster /> in the root Layout (init and create already do). The Block never talks to a server: wire your auth backend in the route file through the props, and keep any session or token in expo-secure-store, never AsyncStorage.

---

## Email-first, two steps

Source: https://nativecn.dev/docs/blocks/sign-in-03

> An email-first sign-in Screen in two steps: the email, then the password, with "Email me a code instead" switching to a 6-digit code (InputOTP). Lucide chevron-left Back buttons.

Block · auth. Registry item `sign-in-03`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/sign-in-03.json

### Installation

```sh
npx nativecn-cli@latest add sign-in-03 --route "(auth)/sign-in"
```

- `--route "(auth)/sign-in"` is the Block's suggested route: change it to put the Screen somewhere else in your app folder.
- In a project with the feature Structure, also pass `--feature <name>` (for example `--feature auth`).
- `add` never overwrites an existing route file.

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [container](https://nativecn.dev/docs/components/container), [text](https://nativecn.dev/docs/components/text), [button](https://nativecn.dev/docs/components/button), [form-field](https://nativecn.dev/docs/components/form-field), [input](https://nativecn.dev/docs/components/input), [focus-chain](https://nativecn.dev/docs/primitives/focus-chain), [input-otp](https://nativecn.dev/docs/components/input-otp), [keyboard](https://nativecn.dev/docs/primitives/keyboard), [toast](https://nativecn.dev/docs/components/toast).

Packages: `react-hook-form@^7.89.0`, `zod@^4.6.5`, `@hookform/resolvers@^5.9.1`, `lucide-react-native@^1.51.0`, `react-native-svg`.

### What makes it different

Email → password, one question per step, with "Email me a code instead" (InputOTP).

### Block Variants

- [sign-in-01](https://nativecn.dev/docs/blocks/sign-in-01) – Classic centred: Logo, email and password, "or", then social; everything on one screen.
- [sign-in-02](https://nativecn.dev/docs/blocks/sign-in-02) – Social-first hero: Dark brand hero, centred; Apple/Google are the primary path; "Continue with email" reveals the fields.
- **sign-in-03** (this page) – Email-first, two steps: Email → password, one question per step, with "Email me a code instead" (InputOTP).

### Props

| Prop | Type and description |
|---|---|
| `onSubmit` | (values: { method: "password", email, password } \| { method: "code", email, code }) => void \| Promise<void>: sign in; throw to show the error as a toast, resolve for a "Signed in" toast |
| `onSendCode` | (email: string) => void \| Promise<void>: email a 6-digit code (Email me a code instead, Resend); a thrown error becomes a toast and the step stays |

### Accessibility

- Each step's title has role heading.
- Every step change (Continue, Email me a code instead, Back, Android's back button) moves screen-reader focus to the new step's title.
- While a screen reader runs, the new step's field doesn't take the keyboard, so focus stays on the heading; without one, the field takes the keyboard as before.
- Each field is in a FormField: its label is the field's accessible name, and a validation error becomes its hint and is announced once.
- Errors from your callbacks and the success message are toast()s, which screen readers announce.
- The submit Button is announced busy while your callback runs.
- Back is an icon-only Button named "Back"; Android's back button steps back too.
- The code is one InputOTP field, read as "Verification code, 6 digits".

### Notes

Render it from a route: `export default function Screen() { return <SignIn03 onSubmit={signIn} onSendCode={sendCode} />; }`. The step (email, password, code) lives inside the Block; Back (an icon-only Button with a Lucide chevron-left) and Android's back button step back, keeping what was typed. Each step validates only its own field with zod through react-hook-form; the main button sits in a KeyboardStickyFooter above the keyboard. hooks/use-step-focus.ts moves screen-reader focus to the new step's heading on every step change; it is this Block's own copy. Validation errors appear under each field. Errors thrown by your callbacks, and the success message, appear only as toast()s: render <Toaster /> in the root Layout (init and create already do). The Block never talks to a server: wire your auth backend in the route file through the props, and keep any session or token in expo-secure-store, never AsyncStorage.

---

## Classic single form

Source: https://nativecn.dev/docs/blocks/sign-up-01

> A classic sign-up Screen on one scroll: Apple and Google on top, "or", then name, email and password, a terms Checkbox with Terms and Privacy Policy links, Create account, and a Sign in link.

Block · auth. Registry item `sign-up-01`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/sign-up-01.json

### Installation

```sh
npx nativecn-cli@latest add sign-up-01 --route "(auth)/sign-up"
```

- `--route "(auth)/sign-up"` is the Block's suggested route: change it to put the Screen somewhere else in your app folder.
- In a project with the feature Structure, also pass `--feature <name>` (for example `--feature auth`).
- `add` never overwrites an existing route file.

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [container](https://nativecn.dev/docs/components/container), [text](https://nativecn.dev/docs/components/text), [button](https://nativecn.dev/docs/components/button), [form-field](https://nativecn.dev/docs/components/form-field), [input](https://nativecn.dev/docs/components/input), [focus-chain](https://nativecn.dev/docs/primitives/focus-chain), [checkbox](https://nativecn.dev/docs/components/checkbox), [icon](https://nativecn.dev/docs/components/icon), [separator](https://nativecn.dev/docs/components/separator), [toast](https://nativecn.dev/docs/components/toast).

Packages: `react-hook-form@^7.89.0`, `zod@^4.6.5`, `@hookform/resolvers@^5.9.1`, `lucide-react-native@^1.51.0`, `react-native-svg`.

### What makes it different

Social on top, then name, email, password and a terms Checkbox; one form.

### Block Variants

- **sign-up-01** (this page) – Classic single form: Social on top, then name, email, password and a terms Checkbox; one form.
- [sign-up-02](https://nativecn.dev/docs/blocks/sign-up-02) – Step-by-step wizard: Progress bar plus one question per screen: email → name → password → verify code.
- [sign-up-03](https://nativecn.dev/docs/blocks/sign-up-03) – Social-first + verify: Brand-led and passwordless; Apple/Google lead, and the email path sends an InputOTP code.

### Props

| Prop | Type and description |
|---|---|
| `onSubmit` | (values: { name, email, password }) => void \| Promise<void>: create the account; throw to show the error as a toast, resolve for an "Account created" toast |
| `onSocialSignIn` | (provider: "apple" \| "google") => void \| Promise<void>: run that provider's sign-up; a thrown error becomes a toast |
| `onTermsPress` | () => void: the Terms link under the checkbox |
| `onPrivacyPress` | () => void: the Privacy Policy link under the checkbox |
| `onSignIn` | () => void: the Sign in link |

### Accessibility

- "Create an account" has role heading; the lines around "or" are decorative.
- Each field is in a FormField: its label is the field's accessible name, and a validation error becomes its hint and is announced once.
- Errors from your callbacks and the success message are toast()s, which screen readers announce.
- The submit Button is announced busy while your callback runs.
- The password field's hint is "At least 8 characters." until it has an error.
- The terms Checkbox is named "I agree to the Terms and Privacy Policy"; its error is its hint and is announced. The dot between the Terms and Privacy Policy links is hidden.
- Apple and Google are labelled Buttons ("Continue with Apple", "Continue with Google"); their logos are decorative.

### Notes

Render it from a route: `export default function Screen() { return <SignUp01 onSubmit={signUp} />; }`. The name, email and password (at least 8 characters) are validated with zod through react-hook-form (name and email trimmed), and the terms Checkbox must be ticked; its error appears under it. The three fields are in a FocusChain (Next, Next, then Done submits). Validation errors appear under each field. Errors thrown by your callbacks, and the success message, appear only as toast()s: render <Toaster /> in the root Layout (init and create already do). The Apple and Google logos are bundled SVGs in components/social-buttons.tsx; the buttons only call onSocialSignIn. The Block never talks to a server: wire your auth backend in the route file through the props, and keep any session or token in expo-secure-store, never AsyncStorage.

---

## Step-by-step wizard

Source: https://nativecn.dev/docs/blocks/sign-up-02

> A sign-up wizard, one question per step under a Progress bar: email, name, password, then a 6-digit code (InputOTP). Lucide chevron-left Back buttons; the Continue button rides above the keyboard.

Block · auth. Registry item `sign-up-02`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/sign-up-02.json

### Installation

```sh
npx nativecn-cli@latest add sign-up-02 --route "(auth)/sign-up"
```

- `--route "(auth)/sign-up"` is the Block's suggested route: change it to put the Screen somewhere else in your app folder.
- In a project with the feature Structure, also pass `--feature <name>` (for example `--feature auth`).
- `add` never overwrites an existing route file.

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [container](https://nativecn.dev/docs/components/container), [text](https://nativecn.dev/docs/components/text), [button](https://nativecn.dev/docs/components/button), [form-field](https://nativecn.dev/docs/components/form-field), [input](https://nativecn.dev/docs/components/input), [focus-chain](https://nativecn.dev/docs/primitives/focus-chain), [progress](https://nativecn.dev/docs/components/progress), [input-otp](https://nativecn.dev/docs/components/input-otp), [keyboard](https://nativecn.dev/docs/primitives/keyboard), [toast](https://nativecn.dev/docs/components/toast).

Packages: `react-hook-form@^7.89.0`, `zod@^4.6.5`, `@hookform/resolvers@^5.9.1`, `lucide-react-native@^1.51.0`, `react-native-svg`.

### What makes it different

Progress bar plus one question per screen: email → name → password → verify code.

### Block Variants

- [sign-up-01](https://nativecn.dev/docs/blocks/sign-up-01) – Classic single form: Social on top, then name, email, password and a terms Checkbox; one form.
- **sign-up-02** (this page) – Step-by-step wizard: Progress bar plus one question per screen: email → name → password → verify code.
- [sign-up-03](https://nativecn.dev/docs/blocks/sign-up-03) – Social-first + verify: Brand-led and passwordless; Apple/Google lead, and the email path sends an InputOTP code.

### Props

| Prop | Type and description |
|---|---|
| `onSendCode` | (details: { email, name, password }) => void \| Promise<void>: register the details and email a 6-digit code (after the password step, and on Resend, so make it safe to repeat); a thrown error becomes a toast and the step stays |
| `onSubmit` | (values: { email, name, password, code }) => void \| Promise<void>: check the code and finish the account; throw to show the error as a toast, resolve for an "Account created" toast |

### Accessibility

- Each step's title has role heading.
- Every step change (Continue, Back, Android's back button) moves screen-reader focus to the new step's title.
- While a screen reader runs, the new step's field doesn't take the keyboard, so focus stays on the heading; without one, the field takes the keyboard as before.
- The Progress bar is named "Step 2 of 4" and carries its value; the visible "2/4" is hidden from screen readers.
- Each field is in a FormField: its label is the field's accessible name, and a validation error becomes its hint and is announced once.
- Errors from your callbacks and the success message are toast()s, which screen readers announce.
- The submit Button is announced busy while your callback runs.
- Back is an icon-only Button named "Back"; Android's back button steps back too.
- The code is one InputOTP field, read as "Verification code, 6 digits".

### Notes

Render it from a route: `export default function Screen() { return <SignUp02 onSendCode={register} onSubmit={verify} />; }`. The step (email, name, password, code) lives inside the Block, and the Progress bar shows how far along it is. Back (an icon-only Button with a Lucide chevron-left) and Android's back button step back, keeping every answer. Each step validates its own field with zod through react-hook-form; the password needs at least 8 characters. The main button sits in a KeyboardStickyFooter above the keyboard. hooks/use-step-focus.ts moves screen-reader focus to the new step's heading on every step change; it is this Block's own copy. Validation errors appear under each field. Errors thrown by your callbacks, and the success message, appear only as toast()s: render <Toaster /> in the root Layout (init and create already do). The Block never talks to a server: wire your auth backend in the route file through the props, and keep any session or token in expo-secure-store, never AsyncStorage.

---

## Social-first + verify

Source: https://nativecn.dev/docs/blocks/sign-up-03

> A brand-led, passwordless sign-up Screen: the logo and headline centred above Apple and Google; "Sign up with email" reveals the email field, and Send code moves on to a 6-digit code (InputOTP).

Block · auth. Registry item `sign-up-03`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/sign-up-03.json

### Installation

```sh
npx nativecn-cli@latest add sign-up-03 --route "(auth)/sign-up"
```

- `--route "(auth)/sign-up"` is the Block's suggested route: change it to put the Screen somewhere else in your app folder.
- In a project with the feature Structure, also pass `--feature <name>` (for example `--feature auth`).
- `add` never overwrites an existing route file.

Also installs: [theme](https://nativecn.dev/docs/theme/theme), [container](https://nativecn.dev/docs/components/container), [text](https://nativecn.dev/docs/components/text), [button](https://nativecn.dev/docs/components/button), [form-field](https://nativecn.dev/docs/components/form-field), [input](https://nativecn.dev/docs/components/input), [focus-chain](https://nativecn.dev/docs/primitives/focus-chain), [icon](https://nativecn.dev/docs/components/icon), [input-otp](https://nativecn.dev/docs/components/input-otp), [keyboard](https://nativecn.dev/docs/primitives/keyboard), [toast](https://nativecn.dev/docs/components/toast).

Packages: `react-hook-form@^7.89.0`, `zod@^4.6.5`, `@hookform/resolvers@^5.9.1`, `lucide-react-native@^1.51.0`, `react-native-svg`.

### What makes it different

Brand-led and passwordless; Apple/Google lead, and the email path sends an InputOTP code.

### Block Variants

- [sign-up-01](https://nativecn.dev/docs/blocks/sign-up-01) – Classic single form: Social on top, then name, email, password and a terms Checkbox; one form.
- [sign-up-02](https://nativecn.dev/docs/blocks/sign-up-02) – Step-by-step wizard: Progress bar plus one question per screen: email → name → password → verify code.
- **sign-up-03** (this page) – Social-first + verify: Brand-led and passwordless; Apple/Google lead, and the email path sends an InputOTP code.

### Props

| Prop | Type and description |
|---|---|
| `onSocialSignIn` | (provider: "apple" \| "google") => void \| Promise<void>: run that provider's sign-up; a thrown error becomes a toast |
| `onSendCode` | (email: string) => void \| Promise<void>: email a 6-digit code (Send code, Resend); a thrown error becomes a toast and the email field stays |
| `onSubmit` | (values: { email, code }) => void \| Promise<void>: check the code and create the account; throw to show the error as a toast, resolve for an "Account created" toast |

### Accessibility

- The headline and "Check your inbox" have role heading; the logo icon is decorative.
- Moving to the code step puts screen-reader focus on "Check your inbox"; Back and Android's back button put it on the headline.
- While a screen reader runs, the new step's field doesn't take the keyboard, so focus stays on the heading; without one, the field takes the keyboard as before.
- Each field is in a FormField: its label is the field's accessible name, and a validation error becomes its hint and is announced once.
- Errors from your callbacks and the success message are toast()s, which screen readers announce.
- The submit Button is announced busy while your callback runs.
- Apple and Google are labelled Buttons ("Continue with Apple", "Continue with Google"); their logos are decorative.
- Back is an icon-only Button named "Back"; Android's back button steps back too.
- The code is one InputOTP field, read as "Verification code, 6 digits".

### Notes

Render it from a route: `export default function Screen() { return <SignUp03 onSocialSignIn={signUpWith} onSendCode={sendCode} onSubmit={verify} />; }`. There is no password: the email path checks the address with zod through react-hook-form, calls onSendCode, then asks for the 6-digit code. The step lives inside the Block; Back (an icon-only Button with a Lucide chevron-left) and Android's back button return to the email field, keeping it. The Create account button sits in a KeyboardStickyFooter above the keyboard. hooks/use-step-focus.ts moves screen-reader focus to the new step's heading on every step change; it is this Block's own copy. Validation errors appear under each field. Errors thrown by your callbacks, and the success message, appear only as toast()s: render <Toaster /> in the root Layout (init and create already do). The Apple and Google logos are bundled SVGs in components/social-buttons.tsx; the buttons only call onSocialSignIn. The Block never talks to a server: wire your auth backend in the route file through the props, and keep any session or token in expo-secure-store, never AsyncStorage.

---

## announce

Source: https://nativecn.dev/docs/primitives/announce

> Reliable screen-reader announcements on iOS and Android (Button and Input status, Toast, error, success and warning Alerts).

Helper · accessibility. Registry item `announce`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/announce.json

### Installation

```sh
npx nativecn-cli@latest add announce
```

### Props

| Prop | Type and description |
|---|---|
| `announce(message, options?)` | void: speaks message with VoiceOver or TalkBack; a no-op for empty text or without a screen reader |
| `options.queue` | boolean (default true): wait for the current speech instead of cutting it off (VoiceOver only; TalkBack always queues) |

### Accessibility

- On iOS it waits briefly so VoiceOver does not drop announcements made during a press or layout change.
- Components already announce their own status; call it only for custom feedback.

### Notes

Use it for changes that appear without moving focus: a form error, a Button's status, a Toast.

---

## FocusChain

Source: https://nativecn.dev/docs/primitives/focus-chain

> Automatic Next/Done between fields in on-screen order; Done submits the form.

Primitive · forms. Registry item `focus-chain`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/focus-chain.json

### Installation

```sh
npx nativecn-cli@latest add focus-chain
```

### Props

#### FocusChain

| Prop | Type and description |
|---|---|
| `children` | the form's fields |
| `onSubmit` | () => void: called when "Done" is pressed on the last field |

#### useFocusChainField

| Prop | Type and description |
|---|---|
| `useFocusChainField(ref, options?)` | registers a field and returns { returnKeyType, onSubmitEditing, submitBehavior } to spread onto its TextInput |
| `options.disabled / options.hidden` | boolean: the chain skips the field |
| `options.multiline` | boolean: skipped so Enter keeps adding new lines (Textarea) |
| `options.returnKeyType / options.onSubmitEditing / options.submitBehavior` | the field's own values win over the chain's |

### Notes

Wrap a form's fields in FocusChain: each field's return key reads Next and moves focus to the next field in on-screen order; the last reads Done and calls onSubmit. Input joins automatically; Textarea is skipped. Custom fields join with useFocusChainField.

---

## FormField context

Source: https://nativecn.dev/docs/primitives/form-field-context

> Links a field to its label, description and error for screen readers; passes status, disabled and required down.

Primitive · forms. Registry item `form-field-context`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/form-field-context.json

### Installation

```sh
npx nativecn-cli@latest add form-field-context
```

### Props

#### FormFieldProvider

| Prop | Type and description |
|---|---|
| `label` | string: the visible label and the control's accessible name |
| `description` | string: helper text, read as the control's hint while there is no error |
| `error` | string: read as the hint instead, and announced once when it appears |
| `status` | 'error' \| 'success' (defaults to 'error' while error is set) |
| `disabled` | boolean (default false) |
| `required` | boolean: adds "required" to the spoken name (default false) |
| `children` | the field's control |

#### useFormField

| Prop | Type and description |
|---|---|
| `useFormField()` | FormFieldState \| null: label, description, error, status, disabled, required and accessibilityProps to spread onto the control; null outside a field |

#### FormFieldContext

| Prop | Type and description |
|---|---|
| `value` | FormFieldState \| null: the raw context |

### Accessibility

- FormField renders FormFieldProvider; a custom control calls useFormField() and spreads accessibilityProps onto its focusable element, so it reads as one element (name, then hint or error).

### Notes

Controls take status and disabled from the field unless set on the control itself.

---

## Keyboard

Source: https://nativecn.dev/docs/primitives/keyboard

> KeyboardProvider setup, a scroll view that keeps the focused field above the keyboard, and a footer that keeps a form's main button above it.

Primitive · layout. Registry item `keyboard`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/keyboard.json

### Installation

```sh
npx nativecn-cli@latest add keyboard
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme).

Packages: `react-native-keyboard-controller`, `react-native-reanimated`, `react-native-worklets`, `react-native-safe-area-context`.

### Props

#### KeyboardProvider

| Prop | Type and description |
|---|---|
| `children` | the whole app, once, in the root Layout (re-exported from react-native-keyboard-controller) |

#### KeyboardAwareScroll

| Prop | Type and description |
|---|---|
| `...KeyboardAwareScrollViewProps` | react-native-keyboard-controller's KeyboardAwareScrollView props (enabled, extraKeyboardSpace, ...) |
| `ref` | Ref<KeyboardAwareScrollViewRef> |

#### KeyboardStickyFooter

| Prop | Type and description |
|---|---|
| `...ViewProps` | View props pass through |
| `gap` | number: space above and below the content (default the spacing[3] Token) |
| `safeArea` | boolean (default true): keep clear of the home indicator while the keyboard is closed; off when a parent already pads it |
| `enabled` | boolean (default true): follow the keyboard |

### Notes

react-native-keyboard-controller is SDK-pinned (`npx expo install`). init and create wrap the root Layout in KeyboardProvider, inside ThemeProvider. Container already scrolls with KeyboardAwareScroll; put a form's main Button in KeyboardStickyFooter below the Container so it stays above the keyboard.

---

## Portal

Source: https://nativecn.dev/docs/primitives/portal

> Renders content above every Screen (above native modals on iOS), layered and safe-area aware.

Primitive · overlay. Registry item `portal`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/portal.json

### Installation

```sh
npx nativecn-cli@latest add portal
```

Packages: `react-native-safe-area-context`, `react-native-screens`.

### Props

#### Portal

| Prop | Type and description |
|---|---|
| `children` | ReactNode: drawn in the host, above every Screen |
| `hostName` | string: the PortalHost to render into (default "root") |
| `layer` | number (default 0): stacking within the host; higher draws on top |

#### PortalHost

| Prop | Type and description |
|---|---|
| `name` | string (default "root"): which Portals this host renders; one default host goes in the root Layout |

#### usePortalInsets

| Prop | Type and description |
|---|---|
| `usePortalInsets()` | EdgeInsets: the safe-area insets of the window the host covers |

### Notes

init and create add <PortalHost /> to the root Layout. On iOS the host draws inside FullWindowOverlay, so Portals (Toasts, sheets, menus) sit above native modals too. A host never blocks touches outside its content.

---

## Pressable

Source: https://nativecn.dev/docs/primitives/pressable

> Pressed look from a Style Slot, tap area extended to 48, no handlers while disabled or loading, optional haptics, role and aria-* states.

Primitive · interaction. Registry item `pressable`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/pressable.json

### Installation

```sh
npx nativecn-cli@latest add pressable
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme).

Packages: `expo-haptics`.

### Props

#### Pressable

| Prop | Type and description |
|---|---|
| `...PressableProps` | React Native Pressable props pass through (onPress, role, aria-*, ...) |
| `pressedStyle` | ViewStyle: the pressed look, usually a Style Slot such as button.pressed |
| `disabled` | boolean: blocks every press handler, announced disabled |
| `loading` | boolean: blocks every press handler, announced busy |
| `haptic` | "selection" \| "light": fires only when config.haptics is on |
| `size` | { width?, height? }: the visual size used to extend the tap area to 48; missing sides are measured |
| `hitSlop` | Insets \| number: an explicit tap-area extension; overrides the computed one |
| `style` | ViewStyle or (state) => ViewStyle, merged last |
| `ref` | Ref<View> |

#### touchTargetHitSlop

| Prop | Type and description |
|---|---|
| `touchTargetHitSlop(width, height, min)` | Insets \| undefined: the extra area on each side so the element reaches min on both axes |

### Accessibility

- The tap area reaches theme.minTouchTarget (48) through hitSlop.
- Use the role / aria-* props, not accessibility*.

### Notes

The press foundation of every pressable Component. Press feedback is a Style Slot applied instantly on press, identical on iOS and Android (no ripple).

---

## SelectionGroup

Source: https://nativecn.dev/docs/primitives/selection-group

> Single or multiple choice within a group, with radio, tab or checkbox roles and selected states.

Primitive · forms. Registry item `selection-group`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/selection-group.json

### Installation

```sh
npx nativecn-cli@latest add selection-group
```

Also installs: [use-controllable-state](https://nativecn.dev/docs/primitives/use-controllable-state).

### Props

#### SelectionGroup

| Prop | Type and description |
|---|---|
| `type` | "single" (default) \| "multiple" |
| `value` | string (single) \| string[] (multiple): controlled |
| `defaultValue` | string \| string[]: uncontrolled |
| `onValueChange` | (value) => void |
| `itemRole` | "radio" \| "tab" \| "checkbox" (default radio for single, checkbox for multiple) |
| `disabled` | boolean: disables every item |
| `ref` | Ref<View> |

#### useSelectionItem

| Prop | Type and description |
|---|---|
| `useSelectionItem({ value, disabled? })` | { selected, disabled, select, itemProps }: spread itemProps onto the item's Pressable (role, aria-checked/selected, tabIndex, onPress) |

#### useSelectionGroup

| Prop | Type and description |
|---|---|
| `useSelectionGroup()` | the group's context: selected values, items, select, move (single only: arrow keys, swipes) and the roving tab stop |

### Accessibility

- The behaviour under RadioGroup, SegmentedTabs and ChipGroup: one implementation of single and multiple choice, roles and selected states, controlled or uncontrolled.

### Notes

Build a custom group by rendering SelectionGroup and calling useSelectionItem in each item.

---

## useControllableState

Source: https://nativecn.dev/docs/primitives/use-controllable-state

> One implementation of controlled and uncontrolled values for form controls.

Primitive · state. Registry item `use-controllable-state`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/use-controllable-state.json

### Installation

```sh
npx nativecn-cli@latest add use-controllable-state
```

### Props

| Prop | Type and description |
|---|---|
| `useControllableState({ value, defaultValue, onChange })` | [value, setValue]: the current value and a stable setter that accepts a value or an updater |
| `value` | T \| undefined: anything but undefined makes the state controlled |
| `defaultValue` | T: the starting value while uncontrolled |
| `onChange` | (value: T) => void: called whenever the setter changes the value, in both modes |

### Notes

Controlled: the returned value is always `value` and the setter only calls onChange. Uncontrolled: the hook holds the value from defaultValue and still calls onChange. Setting the same value (Object.is) does nothing. Warns in development when a component switches between controlled and uncontrolled. Every nativecn form control uses it, so each works with value + change handler or defaultValue.

---

## useMotion

Source: https://nativecn.dev/docs/primitives/use-motion

> Enter/exit animations and timing/spring configs from the motion Tokens; instant when Reduce Motion is on.

Primitive · motion. Registry item `use-motion`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/use-motion.json

### Installation

```sh
npx nativecn-cli@latest add use-motion
```

Also installs: [theme](https://nativecn.dev/docs/theme/theme).

Packages: `react-native-reanimated`, `react-native-worklets`.

### Props

| Prop | Type and description |
|---|---|
| `useMotion()` | Motion: the helpers below, all instant under Reduce Motion |
| `reduced` | boolean: Reduce Motion is on |
| `duration(name)` | number: a duration Token in ms (0 under Reduce Motion) |
| `timing(duration?, easing?)` | withTiming config from Tokens (defaults base, standard) |
| `spring(name?)` | withSpring config from a spring Token (default snappy) |
| `entering(kind?) / exiting(kind?)` | "fade" \| "from-top" \| "from-bottom": a Reanimated layout animation, or undefined under Reduce Motion |

### Accessibility

- Every animation in nativecn goes through useMotion so Reduce Motion is honoured in one place.

### Notes

Pass entering/exiting to an Animated.View's entering/exiting props; pass timing()/spring() to withTiming/withSpring. Reanimated and Worklets are SDK-pinned.

---

## Theme

Source: https://nativecn.dev/docs/theme/theme

> Tokens, Scale, Colour Roles, ThemeProvider, createStyles and the navigation theme.

Theme · theme. Registry item `theme`, shown in the vega Style. JSON: https://nativecn.dev/r/styles/vega/theme.json

### Installation

```sh
npx nativecn-cli@latest add theme
```

Packages: `zustand@^5.0.15`, `@react-native-async-storage/async-storage`, `expo-font`, `expo-splash-screen`, `expo-system-ui`.

### Props

#### ThemeProvider

| Prop | Type and description |
|---|---|
| `children` | the app; wraps the root Layout once |
| `scheme` | "system" \| "light" \| "dark": forces a Scheme for this subtree (e.g. previews) |
| `fonts` | Record<string, FontSource>: extra font faces to load |

#### useTheme

| Prop | Type and description |
|---|---|
| `useTheme()` | Theme: the scaled Tokens (spacing, radius, type, iconSize, controlHeight, ...), colors for the current Scheme, scheme, schemePreference, setScheme, scale, scaleValue(n), elevation, borderWidth, motion, opacity, minTouchTarget and config |
| `setScheme(scheme)` | "system" \| "light" \| "dark": switches the Scheme and persists it |
| `scaleValue(n)` | number: scales a one-off literal like the Tokens (t.scale is the factor itself) |

#### createStyles

| Prop | Type and description |
|---|---|
| `createStyles((t) => styles)` | returns a useStyles() hook; StyleSheet.create runs once per Scale and Scheme and is cached |

#### ThemeContext

| Prop | Type and description |
|---|---|
| `ThemeContext` | the React context useTheme() reads; ThemeProvider provides it. Only for previews that layer a Theme over the app's (the Showcase App's live Preset); apps never need it |

#### useNavigationTheme

| Prop | Type and description |
|---|---|
| `useNavigationTheme()` | an Expo Router / React Navigation theme from the Theme, for headers, tab bars and drawers |

#### config

| Prop | Type and description |
|---|---|
| `fontScaling` | boolean (default false): respect the OS font size |
| `defaultScheme` | "system" (default) \| "light" \| "dark": before the user picks one |
| `scale` | { baseline: 390, min: 0.85, max: 1.25 }: how Tokens adapt to the device |
| `haptics` | boolean (default true): light tick on selection controls |

#### colors, tokens

| Prop | Type and description |
|---|---|
| `colors` | the Colour Roles, with identical light and dark keys |
| `tokens` | the unscaled Token values |

### Notes

The single source of truth for every Token. create/init install it and write colors.ts and the radius and font parts of tokens.ts from the Preset; edit Tokens there by hand when asked, keeping light and dark keys identical, but never re-run setup to change the Preset. ThemeProvider must wrap the root Layout; it also sets the window background (behind the status and navigation bars) to the Scheme's background with expo-system-ui. Components read Tokens through createStyles and never hard-code literals. The Scheme preference is kept in AsyncStorage (a non-sensitive preference).

---

## Registry items

Install any item with `npx nativecn-cli@latest add <name>`. Full source: https://nativecn.dev/r/styles/vega/<name>.json.

### Components

- [text](https://nativecn.dev/docs/components/text.md): All text: the type ramp as Variants, text Colour Roles, alignment and the font-scaling switch.
- [icon](https://nativecn.dev/docs/components/icon.md): Every glyph: a Lucide icon at a Token size in a Colour Role, decorative unless labelled.
- [button](https://nativecn.dev/docs/components/button.md): Button with Variants (primary, secondary, outline, ghost, destructive, link), Sizes, an icon slot, loading and status; icon-only requires aria-label.
- [container](https://nativecn.dev/docs/components/container.md): Wraps a Screen: safe-area edges, scrolling, keyboard avoidance, Token padding and a max content width.
- [toast](https://nativecn.dev/docs/components/toast.md): Sonner-style Toasts: a <Toaster /> in the root Layout and toast(), toast.success/error/info/warning/dismiss. At most 3 stacked, 4s auto-dismiss, swipe away, announced, above native modals.
- [label](https://nativecn.dev/docs/components/label.md): A field's visible label in the label type Variant, with a required marker read as "required".
- [form-field](https://nativecn.dev/docs/components/form-field.md): Lays out a control with its Label, description and error, and links them for screen readers ("Email, text field, Enter a valid email").
- [input](https://nativecn.dev/docs/components/input.md): Single-line text field with Sizes, a leading icon, error/success status, a focus ring and an automatic Show/Hide password toggle.
- [textarea](https://nativecn.dev/docs/components/textarea.md): Multi-line text field that grows from minRows to maxRows, with a character counter when maxLength is set.
- [search-field](https://nativecn.dev/docs/components/search-field.md): Search box with a search icon, an automatic clear (×) button, a loading spinner and onSubmit from the keyboard's Search key.
- [tab-navigation](https://nativecn.dev/docs/components/tab-navigation.md): The bottom tab bar: the custom tabBar of an Expo Router JS Tabs Layout, with classic and floating Variants, per-tab icons and badges from Tabs.Screen options.
- [input-otp](https://nativecn.dev/docs/components/input-otp.md): One-time code field: one hidden input drives N cells; numeric keyboard, SMS/Keychain autofill, paste, onComplete, error/success status and secure.
- [slider](https://nativecn.dev/docs/components/slider.md): Pick a number in a range by dragging or tapping (Gesture Handler + Reanimated), snapped to steps with a haptic tick; adjustable for screen readers.
- [skeleton](https://nativecn.dev/docs/components/skeleton.md): A placeholder shape shown while content loads; pulses unless Reduce Motion is on, hidden from screen readers.
- [spinner](https://nativecn.dev/docs/components/spinner.md): An indeterminate loading indicator in a Colour Role, announced as busy; still under Reduce Motion.
- [progress](https://nativecn.dev/docs/components/progress.md): A horizontal progress bar: a value 0–100 that animates, or indeterminate; role progressbar with its value.
- [alert](https://nativecn.dev/docs/components/alert.md): Alert, AlertTitle and AlertDescription: an inline message with Variants (default, destructive, success, warning, info), each with a default icon.
- [empty-state](https://nativecn.dev/docs/components/empty-state.md): What a Screen or list shows when there is nothing to show yet: an icon, a title, a description and an action.
- [card](https://nativecn.dev/docs/components/card.md): Card surface with CardHeader, CardTitle, CardDescription, CardContent and CardFooter; onPress makes the whole card pressable.
- [separator](https://nativecn.dev/docs/components/separator.md): A hairline divider, horizontal or vertical, decorative by default.
- [badge](https://nativecn.dev/docs/components/badge.md): Small status label with Variants default, secondary, outline, destructive, success and warning.
- [avatar](https://nativecn.dev/docs/components/avatar.md): Round user image (expo-image) with fallback initials, in sizes sm, md and lg.
- [list](https://nativecn.dev/docs/components/list.md): Settings-style rows: ListSection, ListSectionHeader, ListSectionFooter and ListItem (title, description, icon, trailing, chevron, destructive, onPress); FlashList-safe.
- [checkbox](https://nativecn.dev/docs/components/checkbox.md): Checkbox with an optional label, controlled or uncontrolled, an indeterminate (mixed) state and a haptic tick.
- [radio-group](https://nativecn.dev/docs/components/radio-group.md): RadioGroup and RadioGroupItem: a single choice from a list on the SelectionGroup Primitive, vertical or horizontal, with a haptic tick.
- [switch](https://nativecn.dev/docs/components/switch.md): A themed on/off Switch, identical on iOS and Android, with an optional label, a thumb that slides (instant under Reduce Motion) and a haptic tick.
- [chip](https://nativecn.dev/docs/components/chip.md): Chip (plain, toggle or removable, with an optional icon) and ChipGroup (single or multiple choice on the SelectionGroup Primitive), with a haptic tick.
- [segmented-tabs](https://nativecn.dev/docs/components/segmented-tabs.md): In-screen tabs (not navigation): segmented or underline Variants, an animated indicator, and only the selected tab's content rendered.
- [scheme-switcher](https://nativecn.dev/docs/components/scheme-switcher.md): Theme switcher / dark mode toggle: System, Light and Dark as SegmentedTabs, or one icon button cycling through them. Calls setScheme, which persists the choice.
- [drawer](https://nativecn.dev/docs/components/drawer.md): Drawer panel content for Expo Router's drawer (expo-router/drawer): DrawerContent, DrawerHeader, DrawerSection, DrawerItem (label, icon, href, badge; active from the current route) and DrawerFooter.

### Blocks

- [drawer-01](https://nativecn.dev/docs/blocks/drawer-01.md): Drawer panel with a profile header (avatar, name, email, plan Badge), labelled sections (Main, Workspace, Support) and Log out pinned in the footer.
- [drawer-02](https://nativecn.dev/docs/blocks/drawer-02.md): Drawer panel for a SaaS workspace: logo and name with a close button, an Accent Colour onboarding item with a 5 Steps Badge, main items, a bottom group (Notifications with a count, Settings, Docs, Help) and a footer with a team switcher and the user's avatar.
- [drawer-03](https://nativecn.dev/docs/blocks/drawer-03.md): Drawer panel with a dark cover (large avatar, name, View profile, a bell with a count, an overflow button and a round + action), icon items active in Accent Colour text, a divider and text-only secondary items.
- [sign-in-01](https://nativecn.dev/docs/blocks/sign-in-01.md): A centred sign-in Screen: logo, email and password, Forgot password, an "or" divider, then Apple and Google, and a Sign up link.
- [sign-in-02](https://nativecn.dev/docs/blocks/sign-in-02.md): A social-first sign-in Screen: a dark brand hero (logo, headline, subtitle, centred) above a panel where Apple and Google lead and "Continue with email" reveals the email form.
- [sign-in-03](https://nativecn.dev/docs/blocks/sign-in-03.md): An email-first sign-in Screen in two steps: the email, then the password, with "Email me a code instead" switching to a 6-digit code (InputOTP). Lucide chevron-left Back buttons.
- [sign-up-01](https://nativecn.dev/docs/blocks/sign-up-01.md): A classic sign-up Screen on one scroll: Apple and Google on top, "or", then name, email and password, a terms Checkbox with Terms and Privacy Policy links, Create account, and a Sign in link.
- [sign-up-02](https://nativecn.dev/docs/blocks/sign-up-02.md): A sign-up wizard, one question per step under a Progress bar: email, name, password, then a 6-digit code (InputOTP). Lucide chevron-left Back buttons; the Continue button rides above the keyboard.
- [sign-up-03](https://nativecn.dev/docs/blocks/sign-up-03.md): A brand-led, passwordless sign-up Screen: the logo and headline centred above Apple and Google; "Sign up with email" reveals the email field, and Send code moves on to a 6-digit code (InputOTP).

### Primitives

- [form-field-context](https://nativecn.dev/docs/primitives/form-field-context.md): Links a field to its label, description and error for screen readers; passes status, disabled and required down.
- [focus-chain](https://nativecn.dev/docs/primitives/focus-chain.md): Automatic Next/Done between fields in on-screen order; Done submits the form.
- [keyboard](https://nativecn.dev/docs/primitives/keyboard.md): KeyboardProvider setup, a scroll view that keeps the focused field above the keyboard, and a footer that keeps a form's main button above it.
- [portal](https://nativecn.dev/docs/primitives/portal.md): Renders content above every Screen (above native modals on iOS), layered and safe-area aware.
- [selection-group](https://nativecn.dev/docs/primitives/selection-group.md): Single or multiple choice within a group, with radio, tab or checkbox roles and selected states.
- [pressable](https://nativecn.dev/docs/primitives/pressable.md): Pressed look from a Style Slot, tap area extended to 48, no handlers while disabled or loading, optional haptics, role and aria-* states.
- [use-controllable-state](https://nativecn.dev/docs/primitives/use-controllable-state.md): One implementation of controlled and uncontrolled values for form controls.
- [use-motion](https://nativecn.dev/docs/primitives/use-motion.md): Enter/exit animations and timing/spring configs from the motion Tokens; instant when Reduce Motion is on.

### Helpers

- [announce](https://nativecn.dev/docs/primitives/announce.md): Reliable screen-reader announcements on iOS and Android (Button and Input status, Toast, error, success and warning Alerts).

### Themes

- [theme](https://nativecn.dev/docs/theme/theme.md): Tokens, Scale, Colour Roles, ThemeProvider, createStyles and the navigation theme.