{"name":"expo-native-ui","url":"https://github.com/expo/skills/tree/main/plugins/expo/skills/expo-native-ui","install":"npx skills add expo/skills --skill expo-native-ui","sdk":"expo","key":"expo/expo-native-ui","description":"Framework (OSS). Build beautiful, native-feeling Expo screens. Covers Apple HIG styling, semantic colors, native controls, SF Symbols, media, animations, visual effects, gradients, storage, and responsive layout. For routing and navigation, use the expo-router skill.","hasContent":true,"content":"---\nname: expo-native-ui\ndescription: Framework (OSS). Build beautiful, native-feeling Expo screens. Covers Apple HIG styling, semantic colors, native controls, SF Symbols, media, animations, visual effects, gradients, storage, and responsive layout. For routing and navigation, use the expo-router skill.\nversion: 1.1.1\nlicense: MIT\n---\n\n# Expo Native UI Guidelines\n\nFor routes, links, stacks, tabs, modals, sheets, and headers, use the `expo-router` skill.\n\n## References\n\nConsult these resources as needed:\n\n```\nreferences/\n  animations.md          Reanimated: entering, exiting, layout, scroll-driven, gestures\n  controls.md            Native iOS: Switch, Slider, SegmentedControl, DateTimePicker, Picker\n  gradients.md           CSS gradients via experimental_backgroundImage (New Arch only)\n  icons.md               SF Symbols via expo-image (sf: source), names, animations, weights\n  media.md               Camera, audio, video, and file saving\n  storage.md             SQLite, AsyncStorage, SecureStore\n  visual-effects.md      Blur (expo-blur) and liquid glass (expo-glass-effect)\n  webgpu-three.md        3D graphics, games, GPU visualizations with WebGPU and Three.js\n```\n\n## Running the App\n\n**CRITICAL: Always try Expo Go first before creating custom builds.**\n\nMost Expo apps work in Expo Go without any custom native code. Before running `npx expo run:ios` or `npx expo run:android`:\n\n1. **Start with Expo Go**: Run `npx expo start` and scan the QR code with Expo Go\n2. **Check if features work**: Test your app thoroughly in Expo Go\n3. **Only create custom builds when required** - see below\n\n### When Custom Builds Are Required\n\nYou need `npx expo run:ios/android` or `eas build` ONLY when using:\n\n- **Local Expo modules** (custom native code in `modules/`)\n- **Apple targets** (widgets, app clips, extensions via `@bacons/apple-targets`)\n- **Third-party native modules** not included in Expo Go\n- **Custom native configuration** that can't be expressed in `app.json`\n\n### When Expo Go Works\n\nExpo Go supports a huge range of features out of the box:\n\n- All `expo-*` packages (camera, location, notifications, etc.)\n- Expo Router navigation\n- Most UI libraries (reanimated, gesture handler, etc.)\n- Push notifications, deep links, and more\n\n**If you're unsure, try Expo Go first.** Creating custom builds adds complexity, slower iteration, and requires Xcode/Android Studio setup.\n\n## Code Style\n\n- Be cautious of unterminated strings. Ensure nested backticks are escaped; never forget to escape quotes correctly.\n- Always use import statements at the top of the file.\n- Always use kebab-case for file names, e.g. `comment-card.tsx`\n- Never use special characters in file names\n- Configure tsconfig.json with path aliases, and prefer aliases over relative imports for refactors.\n\n## Library Preferences\n\n- Never use modules removed from React Native such as Picker, WebView, SafeAreaView, or AsyncStorage\n- Never use legacy expo-permissions\n- `expo-audio` not `expo-av`\n- `expo-video` not `expo-av`\n- `expo-image` with `source=\"sf:name\"` for SF Symbols, not `expo-symbols` or `@expo/vector-icons`\n- `react-native-safe-area-context` not react-native SafeAreaView\n- `process.env.EXPO_OS` not `Platform.OS`\n- `React.use` not `React.useContext`\n- `expo-image` Image component instead of intrinsic element `img`\n- `expo-glass-effect` for liquid glass backdrops\n- `Color` from `expo-router` for native semantic colors, not raw `PlatformColor` (type-safe, auto-adapts to light/dark)\n- In SDK 56+, never import from `@react-navigation/*` directly — use `expo-router/react-navigation` instead (covers `@react-navigation/native`, `/core`, `/elements`, `/routers`)\n\n## Responsiveness\n\n- Always wrap root component in a scroll view for responsiveness\n- Use `<ScrollView contentInsetAdjustmentBehavior=\"automatic\" />` instead of `<SafeAreaView>` for smarter safe area insets\n- `contentInsetAdjustmentBehavior=\"automatic\"` should be applied to FlatList and SectionList as well\n- Use flexbox instead of Dimensions API\n- ALWAYS prefer `useWindowDimensions` over `Dimensions.get()` to measure screen size\n\n## Behavior\n\n- Use expo-haptics conditionally on iOS to make more delightful experiences\n- Use views with built-in haptics like `<Switch />` from React Native and `@react-native-community/datetimepicker`\n- When a route belongs to a Stack, its first child should almost always be a ScrollView with `contentInsetAdjustmentBehavior=\"automatic\"` set\n- When adding a `ScrollView` to the page it should almost always be the first component inside the route component\n- Use the `<Text selectable />` prop on text containing data that could be copied\n- Consider formatting large numbers like 1.4M or 38k\n- Never use intrinsic elements like 'img' or 'div' unless in a webview or Expo DOM component\n\n# Styling\n\nFollow Apple Human Interface Guidelines.\n\n## General Styling Rules\n\n- Prefer flex gap over margin and padding styles\n- Prefer padding over margin where possible\n- Always account for safe area, either with stack headers, tabs, or ScrollView/FlatList `contentInsetAdjustmentBehavior=\"automatic\"`\n- Ensure both top and bottom safe area insets are accounted for\n- Inline styles not StyleSheet.create unless reusing styles is faster\n- Add entering and exiting animations for state changes\n- Use `{ borderCurve: 'continuous' }` for rounded corners unless creating a capsule shape\n- ALWAYS use a navigation stack title instead of a custom text element on the page\n- When padding a ScrollView, use `contentContainerStyle` padding and gap instead of padding on the ScrollView itself (reduces clipping)\n- CSS and Tailwind are not supported - use inline styles\n\n## Colors\n\nUse the `Color` API from `expo-router` for native semantic colors. It is a type-safe wrapper over `PlatformColor` that exposes iOS UIKit colors through `Color.ios.*` and Android Material 3 colors through `Color.android.material.*` (static) or `Color.android.dynamic.*` (adapts to the user's wallpaper on Android 12+). These resolve on-device and automatically adapt to light/dark mode and accessibility settings, so you no longer maintain separate light/dark hex tables or a `colors.web.ts` file.\n\n`Color` is platform-specific, so wrap each value in `Platform.select` with a `default` hex fallback for web. Centralize the palette in `theme/colors.ts` and import `colors` everywhere:\n\n```tsx\n// theme/colors.ts\nimport { Platform } from \"react-native\";\nimport { Color } from \"expo-router\";\n\nexport const colors = {\n  label: Platform.select({\n    ios: Color.ios.label,\n    android: Color.android.dynamic.onSurface,\n    default: \"#000000\",\n  })!,\n  secondaryLabel: Platform.select({\n    ios: Color.ios.secondaryLabel,\n    android: Color.android.dynamic.onSurfaceVariant,\n    default: \"#3c3c43\",\n  })!,\n  separator: Platform.select({\n    ios: Color.ios.separator,\n    android: Color.android.dynamic.outlineVariant,\n    default: \"#c6c6c8\",\n  })!,\n  systemBackground: Platform.select({\n    ios: Color.ios.systemBackground,\n    android: Color.android.dynamic.surface,\n    default: \"#ffffff\",\n  })!,\n  systemBlue: Platform.select({\n    ios: Color.ios.systemBlue,\n    android: Color.android.dynamic.primary,\n    default: \"#007aff\",\n  })!,\n};\n```\n\n```tsx\nimport { colors } from \"@/theme/colors\";\n\n<View style={{ backgroundColor: colors.systemBackground }}>\n  <Text style={{ color: colors.label }}>Title</Text>\n</View>;\n```\n\n- iOS re-resolves these colors automatically when the system theme changes. On Android, call `useColorScheme()` inside any component that renders them so it re-renders when the theme flips (required when React Compiler memoizes the component).\n- Don't pass `Color` / `PlatformColor` values into Reanimated styles — use static colors there (see `references/animations.md`).\n- `Platform.select({...})!` returns `string | OpaqueColorValue`. Most React Native style props accept `ColorValue` (`string | OpaqueColorValue`) so this works fine. But some third-party props only accept `string` (e.g. `tintColor` on `expo-image`). Cast when needed: `colors.label as string`.\n\n## Text Styling\n\n- Add the `selectable` prop to every `<Text/>` element displaying important data or error messages\n- Counters should use `{ fontVariant: 'tabular-nums' }` for alignment\n\n## Shadows\n\nUse CSS `boxShadow` style prop. NEVER use legacy React Native shadow or elevation styles.\n\n```tsx\n<View style={{ boxShadow: \"0 1px 2px rgba(0, 0, 0, 0.05)\" }} />\n```\n\n'inset' shadows are supported.\n\n## Submitting Feedback\nIf you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:\n```bash\nnpx --yes submit-expo-feedback@latest --category skills --subject \"expo-native-ui\" \"<actionable feedback>\"\n```\nOnly submit when you have something specific and actionable to report. Include as much relevant context as possible.\n","contentSource":"https://raw.githubusercontent.com/expo/skills/main/plugins/expo/skills/expo-native-ui/SKILL.md","contentFetchedAt":"2026-07-28T23:15:38.856Z"}