/building-native-ui

name: building-native-ui
description: Complete guide for building beautiful apps with Expo Router. Covers fundamentals, styling, components, navigation, animations, patterns, and native tabs.
version: 1.0.1
license: MIT

Expo UI Guidelines

References

Consult these resources as needed:

references/
  animations.md          Reanimated: entering, exiting, layout, scroll-driven, gestures
  controls.md            Native iOS: Switch, Slider, SegmentedControl, DateTimePicker, Picker
  form-sheet.md          Form sheets with footers via Stack and react-native-screens
  gradients.md           CSS gradients via experimental_backgroundImage (New Arch only)
  icons.md               SF Symbols via expo-image (sf: source), names, animations, weights
  media.md               Camera, audio, video, and file saving
  route-structure.md     Route conventions, dynamic routes, groups, folder organization
  search.md              Search bar with headers, useSearch hook, filtering patterns
  storage.md             SQLite, AsyncStorage, SecureStore
  tabs.md                NativeTabs, migration from JS tabs, iOS 26 features
  toolbar-and-headers.md Stack headers and toolbar buttons, menus, search (iOS only)
  visual-effects.md      Blur (expo-blur) and liquid glass (expo-glass-effect)
  webgpu-three.md        3D graphics, games, GPU visualizations with WebGPU and Three.js
  zoom-transitions.md    Apple Zoom: fluid zoom transitions with Link.AppleZoom (iOS 18+)

Running the App

**CRITICAL: Always try Expo Go first before creating custom builds.**

Most Expo apps work in Expo Go without any custom native code. Before running `npx expo run:ios` or `npx expo run:android`:

1. **Start with Expo Go**: Run `npx expo start` and scan the QR code with Expo Go 2. **Check if features work**: Test your app thoroughly in Expo Go 3. **Only create custom builds when required** - see below

When Custom Builds Are Required

You need `npx expo run:ios/android` or `eas build` ONLY when using:

• **Local Expo modules** (custom native code in `modules/`)
• **Apple targets** (widgets, app clips, extensions via `@bacons/apple-targets`)
• **Third-party native modules** not included in Expo Go
• **Custom native configuration** that can't be expressed in `app.json`

When Expo Go Works

Expo Go supports a huge range of features out of the box:

• All `expo-*` packages (camera, location, notifications, etc.)
• Expo Router navigation
• Most UI libraries (reanimated, gesture handler, etc.)
• Push notifications, deep links, and more

**If you're unsure, try Expo Go first.** Creating custom builds adds complexity, slower iteration, and requires Xcode/Android Studio setup.

Code Style

• Be cautious of unterminated strings. Ensure nested backticks are escaped; never forget to escape quotes correctly.
• Always use import statements at the top of the file.
• Always use kebab-case for file names, e.g. `comment-card.tsx`
• Always remove old route files when moving or restructuring navigation
• Never use special characters in file names
• Configure tsconfig.json with path aliases, and prefer aliases over relative imports for refactors.

Routes

See `./references/route-structure.md` for detailed route conventions.

• Routes belong in the `app` directory.
• Never co-locate components, types, or utilities in the app directory. This is an anti-pattern.
• Ensure the app always has a route that matches "/", it may be inside a group route.

Library Preferences

• Never use modules removed from React Native such as Picker, WebView, SafeAreaView, or AsyncStorage
• Never use legacy expo-permissions
• `expo-audio` not `expo-av`
• `expo-video` not `expo-av`
• `expo-image` with `source="sf:name"` for SF Symbols, not `expo-symbols` or `@expo/vector-icons`
• `react-native-safe-area-context` not react-native SafeAreaView
• `process.env.EXPO_OS` not `Platform.OS`
• `React.use` not `React.useContext`
• `expo-image` Image component instead of intrinsic element `img`
• `expo-glass-effect` for liquid glass backdrops

Responsiveness

• Always wrap root component in a scroll view for responsiveness
• Use `<ScrollView contentInsetAdjustmentBehavior="automatic" />` instead of `<SafeAreaView>` for smarter safe area insets
• `contentInsetAdjustmentBehavior="automatic"` should be applied to FlatList and SectionList as well
• Use flexbox instead of Dimensions API
• ALWAYS prefer `useWindowDimensions` over `Dimensions.get()` to measure screen size

Behavior

• Use expo-haptics conditionally on iOS to make more delightful experiences
• Use views with built-in haptics like `<Switch />` from React Native and `@react-native-community/datetimepicker`
• When a route belongs to a Stack, its first child should almost always be a ScrollView with `contentInsetAdjustmentBehavior="automatic"` set
• Prefer `headerSearchBarOptions` in Stack.Screen options to add a search bar
• Use the `<Text selectable />` prop on text containing data that could be copied
• Consider formatting large numbers like 1.4M or 38k
• Never use intrinsic elements like 'img' or 'div' unless in a webview or Expo DOM component

Styling

Follow Apple Human Interface Guidelines.

General Styling Rules

• Prefer flex gap over margin and padding styles
• Prefer padding over margin where possible
• Always account for safe area, either with stack headers, tabs, or ScrollView/FlatList `contentInsetAdjustmentBehavior="automatic"`
• Ensure both top and bottom safe area insets are accounted for
• Inline styles not StyleSheet.create unless reusing styles is faster
• Add entering and exiting animations for state changes
• Use `{ borderCurve: 'continuous' }` for rounded corners unless creating a capsule shape
• ALWAYS use a navigation stack title instead of a custom text element on the page
• When padding a ScrollView, use `contentContainerStyle` padding and gap instead of padding on the ScrollView itself (reduces clipping)
• CSS and Tailwind are not supported - use inline styles