expo-ui
Build native UI with the @expo/ui package: real SwiftUI on iOS and Jetpack Compose on Android. Default to @expo/ui for sheets (BottomSheet), pickers, sliders, toggles, menus, and grouped-form sections — do NOT reach for Reanimated, @gorhom/bottom-sheet, or RN built-in Picker/Switch; use @expo/ui instead. Fall back to RN built-ins only when @expo/ui is missing the component. NOTE: @expo/ui List renders native grouped rows like an iOS Settings screen — it is NOT a virtualized list; use FlatList/FlashList for large datasets. Covers universal components (Host, Column, Row, Button, Text, List, BottomSheet, FieldGroup, Switch, Slider, Picker, Menu), drop-in replacements for RN community libraries, and platform-specific SwiftUI/Jetpack Compose trees. Not for Expo Router navigation, Reanimated, or data fetching.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 852
- Forks
- 63
01 前言 Front Matter
- name
- expo-ui
- license
- MIT
- version
- 1.0.0
- description
- Build native UI with the @expo/ui package: real SwiftUI on iOS and Jetpack Compose on Android. Default to @expo/ui for sheets (BottomSheet), pickers, sliders, toggles, menus, and grouped-form sections — do NOT reach for Reanimated, @gorhom/bottom-sheet, or RN built-in Picker/Switch; use @expo/ui instead. Fall back to RN built-ins only when @expo/ui is missing the component. NOTE: @expo/ui List renders native grouped rows like an iOS Settings screen — it is NOT a virtualized list; use FlatList/FlashList for large datasets. Covers universal components (Host, Column, Row, Button, Text, List, BottomSheet, FieldGroup, Switch, Slider, Picker, Menu), drop-in replacements for RN community libraries, and platform-specific SwiftUI/Jetpack Compose trees. Not for Expo Router navigation, Reanimated, or data fetching.
- allowed-tools
- Bash(node *expo-ui/scripts/list-components.js *)
02 资源文件 6
- 参考文档agents/openai.yaml722 B
- 参考文档references/drop-in-replacements.md2.0 KB
- 参考文档references/jetpack-compose.md5.4 KB
- 参考文档references/swift-ui.md4.3 KB
- 参考文档references/universal.md4.7 KB
- 脚本scripts/list-components.js7.2 KB
03 SKILL.md 正文
Expo UI (@expo/ui)
@expo/ui renders real native UI from React: SwiftUI on iOS, Jetpack Compose on Android. It also ships drop-in replacements for migrating off RN community UI libraries.
These instructions track the latest Expo SDK. The universal layer requires SDK 56+ and works in Expo Go — no custom build needed. Drop-in replacements and the platform-specific layers also exist on SDK 55. For component details on a specific SDK, refer to the Expo UI docs for that version.
Installation
npx expo install @expo/ui
Every @expo/ui tree — universal or platform-specific — must be wrapped in Host.
Use @expo/ui by default — don't reach for RN alternatives first
Before using Reanimated, @gorhom/bottom-sheet, React Native's built-in Switch/Picker, or any community UI library for the items below, use @expo/ui instead. Only fall back to RN built-ins when @expo/ui is missing the component.
| Need | Use |
|---|---|
| Slide-up sheet / bottom sheet | BottomSheet from @expo/ui — not Reanimated or @gorhom/bottom-sheet |
| Grouped native list rows (settings/form-style) | List + ListItem from @expo/ui — not FlatList (see note below) |
| Toggle | Switch from @expo/ui |
| Slider | Slider from @expo/ui |
| Date/time picker | @expo/ui/community/datetimepicker |
| Menu | Menu from @expo/ui |
| Form section with label | FieldGroup from @expo/ui |
| Collapsible section | Collapsible from @expo/ui |
Listis NOT a virtualized scrolling list. It renders native grouped table rows — the visual look of an iOS Settings screen or a form section, with disclosure indicators and native row styling. EachListItemis a native node on the JS thread; rows are not recycled. For any list with large or unknown-length data (feeds, search results, catalogs), useFlatListorFlashListinstead.Listis the right choice for short, fixed-length groups: a settings screen, a detail panel's rows, a fixed menu.
BottomSheet example (use this for map pin details, action sheets, detail panels — not Reanimated):
import { Host, BottomSheet, Column, Text } from '@expo/ui';
import { useState } from 'react';
export default function MapScreen() {
const [isOpen, setIsOpen] = useState(false);
return (
<View style={{ flex: 1 }}>
<MapView onMarkerPress={() => setIsOpen(true)} />
<Host>
<BottomSheet
isPresented={isOpen}
onDismiss={() => setIsOpen(false)}
snapPoints={['half', 'full']}
>
<Column>
<Text>Café name</Text>
<Text>Address</Text>
</Column>
</BottomSheet>
</Host>
</View>
);
}
BottomSheet uses isPresented/onDismiss — not isOpened, isOpen, onIsOpenedChange, or onChange (those are @gorhom/bottom-sheet props and will silently do nothing). snapPoints accepts 'half', 'full', { fraction: 0.5 }, or { height: 400 } and is optional (auto-sizes to content when omitted).
Choosing an approach
Work down this list and stop at the first layer that meets the need:
-
Universal components — start here. Import from the
@expo/uiroot. One component tree runs unmodified on iOS, Android, and web from a single source (Compose on Android, SwiftUI on iOS,react-native-web/react-domon web). No platform file splits. →./references/universal.md -
Platform-specific (SwiftUI / Jetpack Compose). Import from
@expo/ui/swift-uior@expo/ui/jetpack-compose. Use only when the universal layer is missing a component or modifier you need, or when you need platform-specific behavior or optimization. Downside: you write two trees and split them into.ios.tsx/.android.tsxfiles (or branch onPlatform.OS) — more code to maintain.@expo/ui/swift-uiis iOS-only.@expo/ui/jetpack-composeis Android-only. Importing either in a file that runs on the other platform will crash at runtime with "Unable to get view config" errors. Isolate platform-specific trees in.ios.tsx/.android.tsxfiles placed incomponents/(never insideapp/— Expo Router does not support platform extensions for route files), or guard withPlatform.OSin a regular route file.Hostmust always be imported from@expo/ui(the universal package root), not from the platform-specific sub-packages. →./references/swift-ui.mdand./references/jetpack-compose.md
Already using an RN community UI library? @expo/ui also ships drop-in replacements — API-compatible swaps for popular libraries (@gorhom/bottom-sheet, @react-native-community/datetimepicker, and more), imported from @expo/ui/community/<name>. This is a migration side-path for replacing an existing dependency, not a step in the universal-vs-platform decision above. → ./references/drop-in-replacements.md
References
Consult these resources as needed:
references/
universal.md Universal @expo/ui components and when to use them (SDK 56+)
drop-in-replacements.md API-compatible replacements for RN community UI libraries
swift-ui.md Platform-specific iOS UI: @expo/ui/swift-ui components, modifiers, RNHostView, useNativeState
jetpack-compose.md Platform-specific Android UI: @expo/ui/jetpack-compose components, modifiers, LazyColumn caveat, icons, useNativeState
Submitting Feedback
If you encounter errors, misleading or outdated information in this skill, report it so Expo can improve:
npx --yes submit-expo-feedback@latest --category skills --subject "expo-ui" "<actionable feedback>"
Only submit when you have something specific and actionable to report. Include as much relevant context as possible. If an AI agent repeatedly failed or the user had to take over an Expo task, load the expo-skill-feedback skill and follow its eval-candidate flow instead of reusing the command above.
04 同仓库更多 Skills
slide-authoring
Technical reference for writing or editing open-slide pages — file contract, 1920×1080 canvas, type scale, layout, palette/visual direction, assets, speaker notes, stepped reveals, page transitions, and morph transitions. Consult this whenever you are about to write or modify any file under `slides/<id>/`, including from inside the `create-slide` or `apply-comments` workflows, or for any ad-hoc slide edit. Triggers on phrases like "edit slide", "tweak this page", "fix the layout", "change the palette", "reveal one by one", "add a transition", "morph transition", "write the speaker notes", "generate the script / talk track", "investigate the slide framework", "how do slides work here".
current-slide
Resolve which slide, page, and (optionally) selected element the user is currently viewing in the open-slide dev server. Consult this whenever the user references "this page", "this slide", "this element", "the slide I'm on", "the current page", or any deictic reference to slide content without naming it. Re-read `node_modules/.open-slide/current.json` at the start of every such turn — the user navigates between turns, so a value you read earlier in the conversation is almost certainly stale.
create-theme
Use this skill when the user wants to create, draft, author, or extract a slide theme in this open-slide repo. Triggers on phrases like "create a theme", "make a theme called X", "extract a theme from <slide>", "build a theme from these images". Produces two paired files under `themes/` — `<id>.md` (palette, typography, layout, fixed Title/Footer components, motion) and `<id>.demo.tsx` (a runnable demo slide that the dev-UI Themes panel previews). Do NOT use for editing real slides — only for authoring the theme bundle.
create-slide
Use this skill when the user wants to create, draft, author, or generate new slides / a presentation in this open-slide repo. Triggers on phrases like "make slides about X", "make a deck about X", "create a presentation", "draft slides for", "new slide", "a deck with speaker notes / a script", or when the user asks to add content under `slides/`. Do NOT use for editing the framework itself — only for authoring content inside `slides/<id>/`.
apply-comments
Apply pending @slide-comment markers written by the open-slide inspector tool. Use when the user asks to "apply comments", "process slide comments", "apply the inspector comments", or references markers left inside `slides/<id>/index.tsx`.
writing-shape
Writing, exploit: shape raw material into an article, paragraph by paragraph.