Native rendering

Four components can render the platform's real control instead of PanelUI's: Button, Switch, Select and BottomSheet. Pass native and rendering goes to SwiftUI on iOS and Jetpack Compose on Android.

<Switch native value={enabled} onValueChange={setEnabled} label="Notifications" />

Why only these four

These are the controls where a faithful re-implementation is not good enough. A switch, a picker, a sheet and a button are muscle memory — users notice when the animation curve, the spring, the haptic or the dismiss gesture is a near-miss, even when they cannot say why. Everything else in the library is better served by tokens and Reanimated, where matching the platform is not the goal.

Installation

@expo/ui is an optional peer dependency. Nothing needs it until you write native.

npx expo install @expo/ui

Without the package installed, native is a silent no-op — the styled component renders as usual. Nothing throws, nothing warns. The same applies on web, which has neither SwiftUI nor Compose.

Check at runtime if you need to branch on it:

import { hasNativeUI } from 'panelui-native';

if (hasNativeUI()) {
  // the platform control is available
}

Theme tokens do not apply

This is the part that surprises people, so it is worth stating plainly: in native mode the platform draws the control. It uses its own colours, metrics, typography and press behaviour. Your theme does not reach it, className is ignored, and most of the component's own props go with it.

That is the trade, not a bug. If you want the control to match your design system, do not pass native.

What survives per component

Button

<Button native variant="outline" onPress={save}>
  Save changes
</Button>

Prop	In native mode
`children` (string)	Becomes the button label
`onPress`	Passed through
`disabled`	Passed through
`variant`	Mapped: `primary`/`secondary`/`destructive` → filled, `outline`/`social` → outlined, `ghost` → text
`size`, `fullWidth`, `className`	Ignored
`loading`, `startContent`, `endContent`	Ignored

loading is the one to watch — a native button has no spinner state, so a loading button looks identical to an idle one. Disable it yourself, or do not use native on buttons that load.

Switch

<Switch native value={enabled} onValueChange={setEnabled} label="Wi-Fi" />

Prop	In native mode
`value`, `onValueChange`, `disabled`	Passed through
`label`	Text drawn beside the control — native only, the styled switch has no label
`size`, `className`	Ignored

Select

<Select native value={fruit} onValueChange={setFruit}>
  <Select.Item value="apple" label="Apple" />
  <Select.Item value="banana" label="Banana" />
</Select>

Prop	In native mode
`value`, `onValueChange`, `disabled`	Passed through
`Select.Item` children	Declare the options, same as always
`nativeAppearance`	`menu` (default) is a dropdown; `wheel` is an inline rotor, iOS only
`placeholder`, `title`, `className`	Ignored

placeholder has nowhere to go: a native picker always has a selection, so an unset value shows the first option rather than placeholder text. Set an initial value, or add an explicit "None" item.

BottomSheet

<BottomSheet native snapPoints={['half', 'full']} open={open} onOpenChange={setOpen}>
  <BottomSheet.Content>
    <Text>Anything you like in here.</Text>
  </BottomSheet.Content>
</BottomSheet>

Prop	In native mode
`open` / `onOpenChange` / `defaultOpen`	Passed through
`snapPoints`	Detents the sheet rests at — native only
`dismissible`	Passed through
`BottomSheet.Content` `className`	Ignored — the platform draws the container

The content inside the sheet is still yours and still themed. Only the chrome — the container, the corner radius, the grabber, the backdrop, the dismiss gesture — belongs to the platform.

snapPoints takes 'half', 'full', { fraction } or { height }. The last two are iOS-only; Android snaps them to the nearest of half and full.

Notes

The native sheet stays mounted and toggles its presentation, where the styled sheet unmounts on close. If you rely on the content unmounting to reset state, key it or reset it yourself.

@expo/ui is versioned with the Expo SDK and needs SDK 56 or newer for these components. On SDK 56+ it runs in Expo Go; on older SDKs you need a development build.

Native rendering

On this page