Native UI with Expo Router

Patterns and conventions for building native mobile applications with Expo Router and React Native.

References

Consult these as needed:

• ./references/route-structure.md

  — Route conventions, dynamic routes, groups, folder organization

• ./references/tabs.md

  — Native tab bar with NativeTabs, iOS 26 features

• ./references/icons.md

  — SF Symbols with expo-symbols, icon names, animations, weights

• ./references/controls.md

  — Native iOS controls: Switch, Slider, SegmentedControl, DateTimePicker

• ./references/visual-effects.md

  — Blur effects (expo-blur) and liquid glass (expo-glass-effect)

• ./references/animations.md

  — Reanimated: entering, exiting, layout, scroll-driven, gestures

• ./references/search.md

  — Search bar with headers, useSearch hook, filtering patterns

• ./references/gradients.md

  — CSS gradients via experimental_backgroundImage (New Architecture only)

• ./references/media.md

  — Camera, audio, video, file saving

• ./references/storage.md

  — SQLite, AsyncStorage, SecureStore

• ./references/webgpu-three.md

  — 3D graphics and GPU visualizations with WebGPU/Three.js

• ./references/toolbar-and-headers.md

  — Stack headers and toolbar with buttons, menus, search bars (iOS)

• ./references/form-sheet.md

  — Form sheet presentation patterns

Running the App

Always try Expo Go first before creating custom builds.

1. Start with

   npx expo start

   and scan the QR code
2. Test features in Expo Go
3. Only create custom builds when required

When Custom Builds Are Required

Use

npx expo run:ios/android

eas build

• Local Expo modules (custom native code in

  modules/

  )
• Apple targets (widgets, app clips via

  @bacons/apple-targets

  )
• Third-party native modules not in Expo Go
• Custom native configuration beyond

  app.json

Expo Go supports all

expo-*

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install native-ui

Code Style

• Escape nested backticks and quotes correctly
• Always use import statements at the top of the file
• Use kebab-case for file names:

  comment-card.tsx

• Remove old route files when restructuring navigation
• No special characters in file names
• Configure

  tsconfig.json

  path aliases; prefer aliases over relative imports

Routes

See

./references/route-structure.md

• Routes belong in the

  app

  directory
• Never co-locate components, types, or utilities in

  app/

  — this is an anti-pattern
• Always have a route matching

  /

  , possibly inside a group route

Library Preferences

expo-audio

expo-av

expo-video

expo-av

expo-symbols

@expo/vector-icons

react-native-safe-area-context

process.env.EXPO_OS

Platform.OS

React.use

React.useContext

expo-image

img

expo-glass-effect

Never use deprecated modules: Picker, WebView, SafeAreaView, AsyncStorage (from RN core), or legacy

expo-permissions

Responsiveness

• Wrap root components in a scroll view
• Use

  <ScrollView contentInsetAdjustmentBehavior="automatic" />

  instead of

  <SafeAreaView>

• Apply

  contentInsetAdjustmentBehavior="automatic"

  to FlatList and SectionList too
• Use flexbox instead of Dimensions API
• Prefer

  useWindowDimensions

  over

  Dimensions.get()

  for screen measurement

Behavior

• Use

  expo-haptics

  conditionally on iOS for delightful interactions
• Use views with built-in haptics (

  <Switch />

  ,

  @react-native-community/datetimepicker

  )
• First child of a Stack route should almost always be a ScrollView with

  contentInsetAdjustmentBehavior="automatic"

• Prefer

  headerSearchBarOptions

  in Stack.Screen options for search bars
• Use

  <Text selectable />

  on data that users may want to copy
• Format large numbers: 1.4M, 38k
• Never use intrinsic elements (

  img

  ,

  div

  ) outside webviews or Expo DOM components

Styling

Follow Apple Human Interface Guidelines.

General Rules

• Prefer flex gap over margin and padding
• Prefer padding over margin
• Always account for safe area via stack headers, tabs, or

  contentInsetAdjustmentBehavior="automatic"

• Ensure both top and bottom safe area insets are handled
• Inline styles preferred over

  StyleSheet.create

  unless reusing styles
• Add entering/exiting animations for state changes
• Use

  { borderCurve: 'continuous' }

  for rounded corners (not capsule shapes)
• Use navigation stack title instead of custom text headers
• On ScrollView, use

  contentContainerStyle

  for padding/gap (avoids clipping)
• CSS and Tailwind are not supported — use inline styles

Text Styling

• Add

  selectable

  prop to

  <Text/>

  elements showing important data or errors
• Use

  { fontVariant: 'tabular-nums' }

  on counters for alignment

Shadows

Use CSS

boxShadow

<View style={{ boxShadow: "0 1px 2px rgba(0, 0, 0, 0.05)" }} />

Inset shadows are supported.

Navigation

Link

Use

<Link href="/path" />

expo-router

import { Link } from 'expo-router';

<Link href="/path" />

<Link href="/path" asChild>
  <Pressable>...</Pressable>
</Link>

Include

<Link.Preview>

Stack

• Always use

  _layout.tsx

  files to define stacks
• Use

  Stack

  from

  expo-router/stack

  for native navigation stacks
• Set page titles in Stack.Screen options:

  options={{ title: "Home" }}

Context Menus

Add long-press context menus to Link components:

<Link href="/settings" asChild>
  <Link.Trigger>
    <Pressable><Card /></Pressable>
  </Link.Trigger>
  <Link.Menu>
    <Link.MenuAction title="Share" icon="square.and.arrow.up" onPress={handleShare} />
    <Link.MenuAction title="Block" icon="nosign" destructive onPress={handleBlock} />
    <Link.Menu title="More" icon="ellipsis">
      <Link.MenuAction title="Copy" icon="doc.on.doc" onPress={() => {}} />
      <Link.MenuAction title="Delete" icon="trash" destructive onPress={() => {}} />
    </Link.Menu>
  </Link.Menu>
</Link>

Link Previews

<Link href="/settings">
  <Link.Trigger>
    <Pressable><Card /></Pressable>
  </Link.Trigger>
  <Link.Preview />
</Link>

Can be combined with context menus.

Modal

Present a screen as a modal:

<Stack.Screen name="modal" options={{ presentation: "modal" }} />

Prefer this over custom modal components.

Sheet

Present as a dynamic form sheet:

<Stack.Screen
  name="sheet"
  options={{
    presentation: "formSheet",
    sheetGrabberVisible: true,
    sheetAllowedDetents: [0.5, 1.0],
    contentStyle: { backgroundColor: "transparent" },
  }}
/>

contentStyle: { backgroundColor: "transparent" }

Common Route Structure

Standard app layout with tabs and stacks:

app/
  _layout.tsx        — <NativeTabs />
  (index,search)/
    _layout.tsx      — <Stack />
    index.tsx        — Main list
    search.tsx       — Search view

Root layout:

// app/_layout.tsx
import { NativeTabs, Icon, Label } from "expo-router/unstable-native-tabs";
import { Theme } from "../components/theme";

export default function Layout() {
  return (
    <Theme>
      <NativeTabs>
        <NativeTabs.Trigger name="(index)">
          <Icon sf="list.dash" />
          <Label>Items</Label>
        </NativeTabs.Trigger>
        <NativeTabs.Trigger name="(search)" role="search" />
      </NativeTabs>
    </Theme>
  );
}

Shared group layout:

// app/(index,search)/_layout.tsx
import { Stack } from "expo-router/stack";
import { PlatformColor } from "react-native";

export default function Layout({ segment }) {
  const screen = segment.match(/\((.*)\)/)?.[1]!;
  const titles: Record<string, string> = { index: "Items", search: "Search" };

  return (
    <Stack
      screenOptions={{
        headerTransparent: true,
        headerShadowVisible: false,
        headerLargeTitleShadowVisible: false,
        headerLargeStyle: { backgroundColor: "transparent" },
        headerTitleStyle: { color: PlatformColor("label") },
        headerLargeTitle: true,
        headerBlurEffect: "none",
        headerBackButtonDisplayMode: "minimal",
      }}
    >
      <Stack.Screen name={screen} options={{ title: titles[screen] }} />
      <Stack.Screen name="i/[id]" options={{ headerLargeTitle: false }} />
    </Stack>
  );
}