native-ui

# 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` or `eas build` only for:

- 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-*` packages, Expo Router, Reanimated, Gesture Handler, push notifications, and deep links out of the box.


## Installation

### OpenClaw / Moltbot / Clawbot

```bash
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` for detailed conventions.

- 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

| Use | Instead of |
|-----|------------|
| `expo-audio` | `expo-av` |
| `expo-video` | `expo-av` |
| `expo-symbols` | `@expo/vector-icons` |
| `react-native-safe-area-context` | RN SafeAreaView |
| `process.env.EXPO_OS` | `Platform.OS` |
| `React.use` | `React.useContext` |
| `expo-image` | Intrinsic `img` element |
| `expo-glass-effect` | Custom glass backdrops |

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` style prop. Never use legacy RN shadow or elevation styles.

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

Inset shadows are supported.

---

## Navigation

### Link

Use `<Link href="/path" />` from `expo-router` for navigation.

```tsx
import { Link } from 'expo-router';

<Link href="/path" />

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

Include `<Link.Preview>` whenever possible to follow iOS conventions. Add context menus and previews frequently.

### 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:

```tsx
<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

```tsx
<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:

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

Prefer this over custom modal components.

### Sheet

Present as a dynamic form sheet:

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

`contentStyle: { backgroundColor: "transparent" }` enables liquid glass on iOS 26+.

---

## 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:**

```tsx
// 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:**

```tsx
// 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>
  );
}
```