# SkillPatch skill: expo-ui This skill guides agents in building native UI using the `@expo/ui` package, which renders real SwiftUI on iOS and Jetpack Compose on Android from React code. It covers universal cross-platform components, platform-specific trees, and drop-in replacements for popular React Native community UI libraries. The skill provides clear decision workflows for choosing between universal and platform-specific approaches, installation steps, and references to detailed sub-documentation. You (the agent) were given this URL and asked to use this skill. This is a **public** skill — no SkillPatch account, API key, or prior setup is required. Two ways to use it: **1. Use it right now** — the skill's complete file tree (SKILL.md + all reference files) is inlined below; read `SKILL.md` first, then follow it, consulting the other files as it directs. **2. Install the exact package onto disk** (recommended if you can run a shell — this reproduces the skill byte-for-byte, including any binary assets that can't be inlined): ```bash mkdir -p .claude/skills/expo-ui curl -sSL https://skillpatch.dev/install_skill/expo-ui | tar -xz -C .claude/skills/ ``` (`.claude/skills/` is Claude Code's convention; use whatever directory your agent loads skills from.) --- ## Skill files (6) - `SKILL.md` - `agents/openai.yaml` - `references/drop-in-replacements.md` - `references/jetpack-compose.md` - `references/swift-ui.md` - `references/universal.md` ### `SKILL.md` ````markdown --- name: expo-ui description: "Build native UI with the @expo/ui package: real SwiftUI on iOS and Jetpack Compose on Android rendered from React in an Expo or React Native app. Covers universal cross-platform components (Host, Column, Row, Button, Text, List, and more imported from @expo/ui), drop-in replacements for popular React Native community libraries (BottomSheet, DateTimePicker, Slider, Menu, etc.), and platform-specific SwiftUI (@expo/ui/swift-ui) and Jetpack Compose (@expo/ui/jetpack-compose) trees and modifiers. Use when adding or reviewing @expo/ui Host/RNHostView trees, building native-feeling UI where standard React Native components fall short (lists with swipe actions and sections, settings forms with toggles, menus, sheets, pickers, sliders), choosing between universal and platform-specific components, or replacing an RN community UI library with a native @expo/ui equivalent. Not for custom native modules, Expo Router navigation, Reanimated, or data fetching." version: 1.0.0 license: MIT --- # Expo UI (`@expo/ui`) `@expo/ui` renders real native UI from React: SwiftUI on iOS, Jetpack Compose on Android. Start with its universal components (one tree for iOS, Android, and web) and drop to platform-specific SwiftUI/Jetpack Compose only when the universal layer falls short. 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+**. 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 ```bash npx expo install @expo/ui ``` On SDK 56, `@expo/ui` works in Expo Go, so `npx expo start` runs it directly — no custom build required. On older SDKs, build a dev client first (`npx expo run:ios` / `npx expo run:android`). Every `@expo/ui` tree — universal or platform-specific — must be wrapped in `Host`. ## Choosing an approach (read this first) Work down this list and stop at the first layer that meets the need: 1. **Universal components — start here.** Import from the `@expo/ui` root. One component tree runs unmodified on iOS, Android, and web from a single source (Compose on Android, SwiftUI on iOS, `react-native-web`/`react-dom` on web). No platform file splits. → `./references/universal.md` 2. **Platform-specific (SwiftUI / Jetpack Compose).** Import from `@expo/ui/swift-ui` or `@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.tsx` files (or branch on `Platform.OS`) — more code to maintain. → `./references/swift-ui.md` and `./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/`. 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 ``` ```` ### `agents/openai.yaml` ``` interface: display_name: "Expo UI" short_description: "Build native UI with @expo/ui — universal components first, SwiftUI/Jetpack Compose when needed" default_prompt: "Use $expo-ui when adding or reviewing @expo/ui UI: universal cross-platform components (Host, Column, Row, Button, Text, List, ...), drop-in replacements for React Native community libraries, or platform-specific @expo/ui/swift-ui and @expo/ui/jetpack-compose trees and modifiers. Recommend universal components first; use drop-in replacements when migrating off a community UI library; reach for platform-specific layers only when universal is missing something or you need platform optimization (which requires .ios.tsx/.android.tsx splits)." ``` ### `references/drop-in-replacements.md` ```markdown # Drop-in replacements for RN community libraries `@expo/ui` ships API-compatible replacements for popular React Native community libraries, powered by native `@expo/ui` components (Jetpack Compose on Android, SwiftUI on iOS). Use these when migrating an existing app off a community UI dependency — the API matches the library being replaced, so the swap is usually just the import path. ## Available replacements Every drop-in lives under `@expo/ui/community/`. Note which are default vs named imports. | Replaces | Import | |----------|--------| | `@gorhom/bottom-sheet` | `import BottomSheet, { BottomSheetView } from '@expo/ui/community/bottom-sheet'` | | `@react-native-community/datetimepicker` | `import DateTimePicker from '@expo/ui/community/datetime-picker'` | | `@react-native-masked-view/masked-view` | `import { MaskedView } from '@expo/ui/community/masked-view'` | | `@react-native-menu/menu` | `import { MenuView } from '@expo/ui/community/menu'` | | `react-native-pager-view` | `import PagerView from '@expo/ui/community/pager-view'` | | `@react-native-picker/picker` | `import { Picker } from '@expo/ui/community/picker'` | | `@react-native-segmented-control/segmented-control` | `import SegmentedControl from '@expo/ui/community/segmented-control'` | | `@react-native-community/slider` | `import Slider from '@expo/ui/community/slider'` | ## Confirming the API Each component has a dedicated docs page with setup and usage: - Overview — https://docs.expo.dev/versions/latest/sdk/ui/drop-in-replacements/index.md - Per component — https://docs.expo.dev/versions/latest/sdk/ui/drop-in-replacements/{component}/index.md (slug is the component name lowercased, no hyphens, e.g. `bottomsheet`, `datetimepicker`, `segmentedcontrol`) The installed package's TypeScript types (`.d.ts`) are the most reliable source of truth for the exact props on your SDK version (@expo/ui is versioned with the SDK and its API can change between versions). Use the doc page to find platform support and any props that differ from the library being replaced. ``` ### `references/jetpack-compose.md` ````markdown # Platform-specific Android UI: `@expo/ui/jetpack-compose` Use this layer only when the universal `@expo/ui` components don't cover what you need on Android (see `./universal.md` first). This requires a platform-specific tree, typically in an `.android.tsx` file. ## Instructions - Expo UI's API mirrors Jetpack Compose's API. Use Jetpack Compose and Material Design 3 knowledge to decide which components or modifiers to use. If you need deeper Jetpack Compose or Material 3 guidance (e.g. which component to pick, layout patterns, theming), spawn a subagent to research [Jetpack Compose](https://developer.android.com/develop/ui/compose/components) and [Material Design 3](https://m3.material.io/) best practices. - Components are imported from `@expo/ui/jetpack-compose`, modifiers from `@expo/ui/jetpack-compose/modifiers`. - **Always read the `.d.ts` type files** to confirm the exact API before using a component or modifier — read the relevant `{ComponentName}/index.d.ts` from the installed `@expo/ui/jetpack-compose` package in `node_modules`. This is the most reliable source of truth. - When about to use a component, fetch its docs to confirm the API — https://docs.expo.dev/versions/latest/sdk/ui/jetpack-compose/{component-name}/index.md - When unsure about a modifier's API, refer to the docs — https://docs.expo.dev/versions/latest/sdk/ui/jetpack-compose/modifiers/index.md - Every Jetpack Compose tree must be wrapped in `Host`. Use `` for intrinsic sizing, or `` when you need explicit size (e.g. as a parent of `LazyColumn`). Example: ```jsx import { Host, Column, Button, Text } from "@expo/ui/jetpack-compose"; import { fillMaxWidth, paddingAll } from "@expo/ui/jetpack-compose/modifiers"; Hello ; ``` - `RNHostView` embeds React Native components inside a Jetpack Compose tree (the same concept as in `@expo/ui/swift-ui`) — wrap any RN child in ``. - If a required composable or modifier is missing in Expo UI, it can be extended via a local Expo module. See: https://docs.expo.dev/guides/expo-ui-jetpack-compose/extending/index.md. Confirm with the user before extending. ## Key Components - **LazyColumn** — Use instead of react-native `ScrollView`/`FlatList` for scrollable lists. Wrap in ``. Not suitable for large lists — each item is a JSX node processed on the JS thread, which causes noticeable slowdowns at scale. - **Icon** — Use `` with Android XML vector drawables. To get icons: go to [Material Symbols](https://fonts.google.com/icons), select an icon, choose the Android platform, and download the XML vector drawable. Save these as `.xml` files in your project's `assets/` directory (e.g. `assets/icons/wifi.xml`). Metro bundles `.xml` assets automatically — no metro config changes needed. ## useNativeState `useNativeState` creates observable state that updates synchronously on the UI thread via worklets, enabling immediate native state changes without waiting for a React render cycle. Requires `react-native-worklets` — without it updates still go through React and flickering remains. Best for real-time interactions where synchronous updates matter, e.g. a text field that masks or formats input as the user types. - `ObservableState.value` is readable/writable from worklets; `onChange` fires a worklet listener on state change. - Docs — https://docs.expo.dev/versions/latest/sdk/ui/jetpack-compose/usenativestate/index.md ```` ### `references/swift-ui.md` ````markdown # Platform-specific iOS UI: `@expo/ui/swift-ui` Use this layer only when the universal `@expo/ui` components don't cover what you need on iOS (see `./universal.md` first). This requires a platform-specific tree, typically in an `.ios.tsx` file. ## Instructions - Expo UI's API mirrors SwiftUI's API. Use SwiftUI knowledge to decide which components or modifiers to use. - Components are imported from `@expo/ui/swift-ui`, modifiers from `@expo/ui/swift-ui/modifiers`. - **The installed package's TypeScript types (`.d.ts`) are the most reliable source of truth** for the exact API on your SDK version (@expo/ui is versioned with the SDK and its API can change between versions) — read the relevant `{Component}/index.d.ts` from the installed `@expo/ui/swift-ui` package in `node_modules`. Use the docs below as the human-readable reference. - When about to use a component, fetch its docs to confirm the API — https://docs.expo.dev/versions/latest/sdk/ui/swift-ui/{component-name}/index.md - When unsure about a modifier's API, refer to the docs — https://docs.expo.dev/versions/latest/sdk/ui/swift-ui/modifiers/index.md - Every SwiftUI tree must be wrapped in `Host`. - `RNHostView` is specifically for embedding RN components inside a SwiftUI tree. Example: ```jsx import { Host, VStack, RNHostView } from "@expo/ui/swift-ui"; import { Pressable } from "react-native"; // Here, `Pressable` is an RN component so it is wrapped in `RNHostView`. ; ``` - If a required modifier or View is missing in Expo UI, it can be extended via a local Expo module. See: https://docs.expo.dev/guides/expo-ui-swift-ui/extending/index.md. Confirm with the user before extending. ## useNativeState `useNativeState` creates observable state that updates synchronously on the UI thread via worklets, enabling immediate native state changes without waiting for a React render cycle. Requires `react-native-worklets` — without it updates still go through React and flickering remains. Best for real-time interactions where synchronous updates matter, e.g. a text field that masks or formats input as the user types. - `ObservableState.value` is readable/writable from worklets; `onChange` fires a worklet listener on state change. - Docs — https://docs.expo.dev/versions/latest/sdk/ui/swift-ui/usenativestate/index.md ```` ### `references/universal.md` ````markdown # Universal `@expo/ui` components > Requires Expo SDK 56+. Universal components are a single-API layer over the platform-native UI toolkits: Jetpack Compose on Android, SwiftUI on iOS, and `react-native-web` / `react-dom` on web. You write one component tree that runs unmodified on all three platforms while keeping a native look and feel — no `.ios.tsx` / `.android.tsx` split. ## Usage Import everything, including `Host`, from the package root (`@expo/ui`). Every tree must be wrapped in `Host`. ```tsx import { Host, Column, Button, Text } from '@expo/ui'; Hello ; ``` ## Components | Category | Components | |----------|------------| | Container | `Host` (required root wrapper) | | Layout | `Column`, `Row`, `Spacer`, `ScrollView` | | Display | `Text`, `Icon` | | Controls | `Button`, `Switch`, `Checkbox`, `Slider`, `TextInput`, `Picker` | | Disclosure & presentation | `BottomSheet`, `Collapsible` | | Collections & forms | `List` (with `ListItem`), `FieldGroup` | > **`List` is not suitable for large lists.** Each `ListItem` is a JSX node processed on the JS thread — for large datasets this causes noticeable slowdowns. ## TextInput and useNativeState `TextInput` from `@expo/ui` is **not like React Native's TextInput** — its `value` and `selection` props take an `ObservableState` object (from `useNativeState`), not a plain string. This is what enables synchronous, flicker-free updates: when the user types, `onChangeText` runs as a worklet on the UI thread and writes directly to `value` without a React render cycle. Requires `react-native-worklets`. Without it the worklet directive has no effect and flickering remains. ```tsx import { Host, TextInput, useNativeState } from '@expo/ui'; import { useCallback } from 'react'; export default function MyInput() { const text = useNativeState(''); const handleChangeText = useCallback((value: string) => { 'worklet'; // transform synchronously on the UI thread — no React re-render text.value = value === 'Hello' ? 'World' : value; }, [text]); return ( ); } ``` Docs — https://docs.expo.dev/versions/latest/sdk/ui/universal/textinput/index.md ## Confirming the API `@expo/ui` is versioned with the Expo SDK (e.g. `56.0.x` for SDK 56) and its API can change between SDK versions, so the **installed package's TypeScript types (`.d.ts`) are the most reliable source of truth** — they match the version in your project, while the docs track latest. Read the relevant component's `.d.ts` from the installed `@expo/ui` package in `node_modules`. Use the docs as the human-readable reference: - Overview — https://docs.expo.dev/versions/latest/sdk/ui/universal/index.md - Per component — https://docs.expo.dev/versions/latest/sdk/ui/universal/{component-name}/index.md ## When to drop down to a platform-specific layer Choose universal components whenever they cover the requirement. Drop down to `@expo/ui/swift-ui` or `@expo/ui/jetpack-compose` only when the universal API doesn't expose the component, modifier, or platform-specific behavior you need — accepting the per-platform file split that requires. See `./swift-ui.md` and `./jetpack-compose.md`. ````