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.

Portal

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

View as Markdown
Primitiveoverlay
Style

Installation

$npx nativecn-cli@latest add portal

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

Props

Portal

PropType and description
childrenReactNode: drawn in the host, above every Screen
hostNamestring: the PortalHost to render into (default "root")
layernumber (default 0): stacking within the host; higher draws on top

PortalHost

PropType and description
namestring (default "root"): which Portals this host renders; one default host goes in the root Layout

usePortalInsets

PropType 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.

Source

The Vega Style's code, exactly as add copies it into your app.

{components}/primitives/portal.tsx

import {
  createContext,
  use,
  useId,
  useLayoutEffect,
  useSyncExternalStore,
  type ReactNode,
} from "react";
import { Platform, StyleSheet, View } from "react-native";
import {
  SafeAreaInsetsContext,
  initialWindowMetrics,
  type EdgeInsets,
} from "react-native-safe-area-context";
import { FullWindowOverlay } from "react-native-screens";

/** The host a Portal renders into when it names none. */
export const DEFAULT_PORTAL_HOST = "root";

type PortalEntry = { key: string; layer: number; order: number; children: ReactNode };

// A tiny module-level store, so a Portal anywhere in the app (including inside a native
// modal Screen) reaches the PortalHost in the root Layout without a shared provider.
const hosts = new Map<string, PortalEntry[]>();
const listeners = new Set<() => void>();
const EMPTY: PortalEntry[] = [];
let nextOrder = 0;

function emit() {
  for (const listener of listeners) listener();
}

function subscribe(listener: () => void) {
  listeners.add(listener);
  return () => {
    listeners.delete(listener);
  };
}

function sortEntries(entries: PortalEntry[]) {
  // Higher layers draw on top; within a layer, the later registration draws on top.
  return entries.sort((a, b) => a.layer - b.layer || a.order - b.order);
}

function upsert(hostName: string, key: string, layer: number, children: ReactNode) {
  const entries = hosts.get(hostName) ?? [];
  const existing = entries.find((e) => e.key === key);
  const order = existing?.order ?? nextOrder++;
  const next = entries.filter((e) => e.key !== key);
  next.push({ key, layer, order, children });
  hosts.set(hostName, sortEntries(next));
  emit();
}

function remove(hostName: string, key: string) {
  const entries = hosts.get(hostName);
  if (!entries?.some((e) => e.key === key)) return;
  const next = entries.filter((e) => e.key !== key);
  if (next.length) hosts.set(hostName, next);
  else hosts.delete(hostName);
  emit();
}

const ZERO_INSETS: EdgeInsets = { top: 0, right: 0, bottom: 0, left: 0 };
const PortalInsetsContext = createContext<EdgeInsets>(ZERO_INSETS);

/**
 * The safe-area insets of the window a PortalHost covers. Portal content is drawn over the
 * whole window, so it uses these to keep clear of the notch, status bar and home indicator.
 */
export function usePortalInsets(): EdgeInsets {
  return use(PortalInsetsContext);
}

type PortalHostProps = {
  /** Which Portals this host renders. Place one default host in the root Layout. */
  name?: string;
};

/**
 * Renders every Portal that targets it, above every Screen. On iOS it draws inside
 * `FullWindowOverlay`, so it also sits above native modals (e.g. an Expo Router formSheet).
 * It has no visuals of its own and never blocks touches outside Portal content.
 */
export function PortalHost({ name = DEFAULT_PORTAL_HOST }: PortalHostProps) {
  const entries = useSyncExternalStore(
    subscribe,
    () => hosts.get(name) ?? EMPTY,
    () => EMPTY,
  );
  const insets = use(SafeAreaInsetsContext) ?? initialWindowMetrics?.insets ?? ZERO_INSETS;

  if (entries.length === 0) return null;

  const content = (
    <PortalInsetsContext value={insets}>
      <View style={StyleSheet.absoluteFill} pointerEvents="box-none" testID={`portal-host-${name}`}>
        {entries.map((entry) => (
          <View key={entry.key} style={StyleSheet.absoluteFill} pointerEvents="box-none">
            {entry.children}
          </View>
        ))}
      </View>
    </PortalInsetsContext>
  );

  if (Platform.OS === "ios") {
    return (
      <FullWindowOverlay unstable_accessibilityContainerViewIsModal={false}>
        {content}
      </FullWindowOverlay>
    );
  }
  return content;
}

type PortalProps = {
  children: ReactNode;
  /** The PortalHost to render into. Defaults to the root host. */
  hostName?: string;
  /** Stacking layer within the host: higher draws on top. Ties go to the later Portal. */
  layer?: number;
};

/**
 * Renders its children in a PortalHost instead of in place, so overlays (Toast, Dialog,
 * Sheet, menus) escape their Screen's layout and clipping. Renders nothing where it is used.
 */
export function Portal({ children, hostName = DEFAULT_PORTAL_HOST, layer = 0 }: PortalProps) {
  const key = useId();

  useLayoutEffect(() => {
    upsert(hostName, key, layer, children);
  }, [hostName, key, layer, children]);

  useLayoutEffect(() => () => remove(hostName, key), [hostName, key]);

  return null;
}