Skip to content
  • Introduction
    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.
  • Installation
    Create a new Expo app with nativecn, or add nativecn to an existing one.
  • components.json
    The project file that records your Preset, Structure, aliases and agents.
  • CLI
    Every nativecn-cli command and flag: init, create, add, agents and mcp.
  • Changelog
    What changed in each nativecn release.
  • Theming
    Tokens, Colour Roles, Scale, Scheme, createStyles and fonts.
  • Presets & Styles
    Style, Base Colour, Accent Colour, Radius and fonts: chosen once, baked into your code.
  • Folder structure
    Flat and feature Structures, Destinations and the placement rule.
  • AI agents
    Rules, Skills, the nativecn MCP server, the Plugin and the Visual QA Loop.
  • Alert
    Alert, AlertTitle and AlertDescription: an inline message with Variants (default, destructive, success, warning, info), each with a default icon.
  • Avatar
    Round user image (expo-image) with fallback initials, in sizes sm, md and lg.
  • Badge
    Small status label with Variants default, secondary, outline, destructive, success and warning.
  • Button
    Button with Variants (primary, secondary, outline, ghost, destructive, link), Sizes, an icon slot, loading and status; icon-only requires aria-label.
  • Card
    Card surface with CardHeader, CardTitle, CardDescription, CardContent and CardFooter; onPress makes the whole card pressable.
  • Checkbox
    Checkbox with an optional label, controlled or uncontrolled, an indeterminate (mixed) state and a haptic tick.
  • Chip
    Chip (plain, toggle or removable, with an optional icon) and ChipGroup (single or multiple choice on the SelectionGroup Primitive), with a haptic tick.
  • Container
    Wraps a Screen: safe-area edges, scrolling, keyboard avoidance, Token padding and a max content width.
  • 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.
  • Empty State
    What a Screen or list shows when there is nothing to show yet: an icon, a title, a description and an action.
  • FormField
    Lays out a control with its Label, description and error, and links them for screen readers ("Email, text field, Enter a valid email").
  • Icon
    Every glyph: a Lucide icon at a Token size in a Colour Role, decorative unless labelled.
  • Input
    Single-line text field with Sizes, a leading icon, error/success status, a focus ring and an automatic Show/Hide password toggle.
  • InputOTP
    One-time code field: one hidden input drives N cells; numeric keyboard, SMS/Keychain autofill, paste, onComplete, error/success status and secure.
  • Label
    A field's visible label in the label type Variant, with a required marker read as "required".
  • List
    Settings-style rows: ListSection, ListSectionHeader, ListSectionFooter and ListItem (title, description, icon, trailing, chevron, destructive, onPress); FlashList-safe.
  • Progress
    A horizontal progress bar: a value 0–100 that animates, or indeterminate; role progressbar with its value.
  • RadioGroup
    RadioGroup and RadioGroupItem: a single choice from a list on the SelectionGroup Primitive, vertical or horizontal, with a haptic tick.
  • SchemeSwitcher
    Theme switcher / dark mode toggle: System, Light and Dark as SegmentedTabs, or one icon button cycling through them. Calls setScheme, which persists the choice.
  • SearchField
    Search box with a search icon, an automatic clear (×) button, a loading spinner and onSubmit from the keyboard's Search key.
  • SegmentedTabs
    In-screen tabs (not navigation): segmented or underline Variants, an animated indicator, and only the selected tab's content rendered.
  • Separator
    A hairline divider, horizontal or vertical, decorative by default.
  • Skeleton
    A placeholder shape shown while content loads; pulses unless Reduce Motion is on, hidden from screen readers.
  • 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.
  • Spinner
    An indeterminate loading indicator in a Colour Role, announced as busy; still under Reduce Motion.
  • 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.
  • TabNavigation
    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.
  • Text
    All text: the type ramp as Variants, text Colour Roles, alignment and the font-scaling switch.
  • Textarea
    Multi-line text field that grows from minRows to maxRows, with a character counter when maxLength is set.
  • 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.
  • Profile header + grouped sections
    Drawer panel with a profile header (avatar, name, email, plan Badge), labelled sections (Main, Workspace, Support) and Log out pinned in the footer.
  • SaaS workspace
    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.
  • Cover header
    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.
  • Classic centred
    A centred sign-in Screen: logo, email and password, Forgot password, an "or" divider, then Apple and Google, and a Sign up link.
  • Social-first hero
    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.
  • Email-first, two steps
    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.
  • Classic single form
    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.
  • Step-by-step wizard
    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.
  • Social-first + verify
    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).
  • announce
    Reliable screen-reader announcements on iOS and Android (Button and Input status, Toast, error, success and warning Alerts).
  • FocusChain
    Automatic Next/Done between fields in on-screen order; Done submits the form.
  • FormField context
    Links a field to its label, description and error for screen readers; passes status, disabled and required down.
  • 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.
  • Portal
    Renders content above every Screen (above native modals on iOS), layered and safe-area aware.
  • Pressable
    Pressed look from a Style Slot, tap area extended to 48, no handlers while disabled or loading, optional haptics, role and aria-* states.
  • SelectionGroup
    Single or multiple choice within a group, with radio, tab or checkbox roles and selected states.
  • useControllableState
    One implementation of controlled and uncontrolled values for form controls.
  • useMotion
    Enter/exit animations and timing/spring configs from the motion Tokens; instant when Reduce Motion is on.
  • Theme
    Tokens, Scale, Colour Roles, ThemeProvider, createStyles and the navigation theme.

Expo SDK 57+ · iOS & Android · Open source

shadcn for Expo, built for AI agents

Components and Screens you copy into your Expo app and own, the same on iOS and Android. Every project ships with Rules, Skills and an MCP server, so your agent can build a whole mobile app and check it on a real device.

$npx nativecn-cli@latest create my-app
Read the docsGitHub

Copy, paste, own it

Not a library

Like shadcn, nativecn is a way to build your own components. You run the CLI and the source lands in your project, ready to change.

Your code, not a dependency

nativecn-cli copies each Component's source into your app. Edit any line; there is no runtime package to upgrade around.

Plain React Native

StyleSheet plus a TypeScript Theme. No Tailwind, NativeWind or className, and no build-time CSS step.

One Theme, both platforms

Every Component reads Tokens from your Theme and never hard-codes a colour or size, so iOS and Android match.

Whole Screens as Blocks

Pre-designed Screens such as sign-in, in several Block Variants, installed at the route you choose.

Its own Primitives

Dialogs, sheets, pickers and menus are written by nativecn, so they follow your Theme and you can edit them.

Your folder structure

Flat or feature folders, recorded in components.json. add writes every file where it belongs.

Presets

Your look, chosen once

A Preset is a Style, a Base Colour, an Accent Colour, a Radius and fonts. You pick it at create, it is baked into your code, and it stays fixed for the life of the project.

Vega

Clean and balanced. The default.

Nova

Compact, for denser screens.

Colours

7 Base Colours × 24 Accent Colours, every pairing checked for WCAG AA contrast in light and dark.

  • neutral
  • stone
  • zinc
  • mauve
  • olive
  • mist
  • taupe
  • amber
  • blue
  • cyan
  • emerald
  • fuchsia
  • green
  • indigo
  • lime
  • orange
  • pink
  • purple
  • red
  • rose
  • sky
  • teal
  • violet
  • yellow

Base Colours: neutral, stone, zinc, mauve, olive, mist, taupe.

Fonts

A Body Font and an optional Heading Font. Only the fonts you choose are added to your app.

Sans
Inter, Geist, DM Sans, Figtree
Serif
Lora, Source Serif 4
Mono
Geist Mono, JetBrains Mono

One short code

Share a Preset as a code, or spell it out as flags. Settings you leave out take their defaults.

# Vega · neutral · neutral · Inter (the default)
npx nativecn-cli@latest create my-app --preset a0

# Nova · violet accent · Lora headings
npx nativecn-cli@latest create my-app --preset a1Q17B

# the same Preset, as long flags
npx nativecn-cli@latest create my-app \
  --style nova --accent violet --heading-font lora
Presets & Styles in the docs

AI-native

The Agent Kit

create and init write the Agent Kit for Claude Code, Codex, Cursor and Antigravity, so your agent knows what exists, how to add it and how to check the result.

# AGENTS.md

1. Tokens only, via createStyles

3. Never Alert.alert, use toast()

8. The Preset is fixed

…

Rules

Twelve Rules in AGENTS.md: Tokens only, no platform alerts, Expo Router navigation, safe storage, the placement rule and accessibility.
  • nativecn-setup
  • nativecn-build-screen
  • nativecn-theme
  • nativecn-component-authoring
  • nativecn-visual-qa

Five Skills

Task-sized instructions for setting up a project, building a Screen, theming, authoring Components and running Visual QA.
  • list_items
  • search_items
  • view_items
  • get_item_examples
  • get_add_command
  • get_project_config
  • get_audit_checklist
  • list_block_variants
  • list_preset_options
  • build_preset_code

The nativecn MCP server

Read-only tools that list and search Components, Blocks and Block Variants, give the exact add command, build Preset codes and return a post-change audit checklist. Local over stdio, or remote at nativecn.dev/mcp.
  1. navigate
  2. screenshot
  3. judge
  4. fix or report

Visual QA Loop

Your agent opens each Screen on a device, screenshots it, judges it against your design, fixes small visual problems and reports the rest.

Read AI agents for the full Rules, Skills and tools.

Expo-first

Made for Expo apps

nativecn follows shadcn wherever it can and Expo's conventions wherever it must. Bare React Native apps are not supported.

  • Expo SDK 57+

    SDK 57 is the support floor, with Expo Router for navigation.

  • iOS & Android

    One Theme and one set of Components, the same on both.

  • Expo's own layout

    src/components, src/hooks and your app/ routes.

  • Few dependencies

    The Expo SDK's pinned modules, plus a short recorded list.

Showcase App

See it on a phone

The Showcase App is a complete app built with nativecn, demonstrating every Component. These screens use Preset a1Q17B.

Start a new app

Or set nativecn up in an existing Expo app with init.

$npx nativecn-cli@latest create my-app
InstallationStar on GitHub