Expo Native UI

Expo Native UI Guidelines

For routes, links, stacks, tabs, modals, sheets, and headers, use the expo-router skill. For any motion — entering/exiting, gestures, springs, keyboard-driven UI — use the expo-animation skill.

Before picking any UI component, check expo-ui first. @expo/ui provides native equivalents — BottomSheet, Button, Picker, Slider, Menu, Section, Switch, SegmentedControl, and more — rendered as real SwiftUI on iOS and Jetpack Compose on Android, available in Expo Go on SDK 56+ with no custom build. Load the expo-ui skill to find the right component before falling back to React Native built-ins or community libraries. This skill (expo-native-ui) covers the surrounding structure: Expo Router navigation, layout, styling, and visual effects.

References

Consult these resources as needed:

references/
  controls.md            Native iOS: Switch, Slider, SegmentedControl, DateTimePicker, Picker
  gradients.md           CSS gradients via experimental_backgroundImage (New Arch only)
  icons.md               SF Symbols via expo-symbols SymbolView: names, weights, animations; Material icons on Android
  media.md               Camera, audio, video, and file saving
  storage.md             SQLite, AsyncStorage, SecureStore
  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

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 wide range of features out of the box:

• Most expo-* packages (camera, location, sensors, sqlite, etc.) — but not all: remote push notifications don't work in Expo Go on Android since SDK 53, and some packages need native capabilities Expo Go doesn't bundle (e.g. WebGPU — see references/webgpu-three.md)
• Expo Router navigation and deep links
• Most UI libraries (reanimated, gesture handler, etc.)

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
• Never use special characters in file names
• Configure tsconfig.json with path aliases, and prefer aliases over relative imports for refactors.

Library Preferences

• For any sheet, picker, slider, toggle, menu, or grouped-form section: use @expo/ui (see expo-ui skill) before reaching for a React Native built-in or community library — it renders native SwiftUI/Compose and works in Expo Go on SDK 56+. For grouped/settings-style rows (short, fixed-length), use @expo/ui's List + ListItem. For large or unknown-length scrolling lists (feeds, search results, catalogs), use FlatList or FlashList — @expo/ui's List is not virtualized.
• 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-symbols (SymbolView) for SF Symbols on iOS, not @expo/vector-icons — see references/icons.md. SF Symbols are Apple-only: on Android every icon needs a Material source (md prop on NativeTabs triggers; in-screen options under "Android: Material Icons" in icons.md), never SF-only iconography
• 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
• Color from expo-router for native semantic colors, not raw PlatformColor (type-safe, auto-adapts to light/dark)
• In SDK 56+, never import from @react-navigation/* directly — use expo-router/react-navigation instead (covers @react-navigation/native, /core, /elements, /routers)

Responsiveness

• Wrap screens with scrollable content in a ScrollView. Screens whose root is a FlatList/FlashList must not add an outer ScrollView (the list is the scroll container), and full-bleed screens (camera, map, canvas) need neither
• 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 Stack route has scrollable content, make the ScrollView (or FlatList) the first component inside the route, with contentInsetAdjustmentBehavior="automatic" set
• 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
• Every screen that loads data has four states (loading, error, empty, content) - never show the empty state while the first load is still resolving; the rules live in the expo-data-fetching skill
• On scrollable forms and search results, use keyboardShouldPersistTaps="handled" so controls receive the first tap and unhandled taps can dismiss the keyboard. Use "always" only when unhandled taps should also keep it open
• A form's primary action must never sit under the keyboard. For UI that tracks the keyboard's real frame, load the expo-animation skill's keyboard recipe (react-native-keyboard-controller) - never Keyboard.addListener plus a timing animation
• Every enabled control must perform its advertised action: search filters results, Save commits edits, and settings affect behavior. Empty handlers and success alerts are not implementations; local state is enough when the user requested a prototype
• For async saves, preserve drafts and handle pending/failure states per expo-data-fetching; do not dismiss a form before its save succeeds

Before calling a screen complete, walk through its primary task, including one failure and recovery when it loads or saves data. Check keyboard access and back/dismiss behavior. Try long titles, missing images, no search results, and large system text; required actions must remain reachable. Report what you exercised and what you could not run.