FAQ

Yes. Add react-native-worklets/plugin last in the Babel plugin list and clear the Metro cache. Without it the animated callbacks never reach the UI runtime and Reanimated aborts. Recent Expo SDKs set it up for you.

react, react-native, react-native-reanimated 4 and react-native-worklets. The rest are optional and only pulled in by what you use:

• react-native-gesture-handler — Slider, calendars, BottomSheet, TimePicker
• react-native-svg — icons, progress, charts
• react-native-safe-area-context — chrome and full-screen surfaces
• libphonenumber-js — PhoneNumberField

Both. Expo installs the compatible native versions for you; on the Community CLI you add the peers yourself and run pod install. Either way, run the New Architecture — see the installation guide.

The current package publishes on the beta dist-tag, so pnpm add @xaui/native@beta is what gets you the 75 components documented here. Plain latest still points at the previous line, and the alpha tag is frozen on the last pre-beta publish.

variant picks a semantic appearance out of the theme — a Button takes primary, secondary, default, tertiary, ghost, danger and danger-soft. color takes one raw hue and the component derives its own pressed, soft and contrasting values from it. Each component's values are in the generated props table on its page.

Put style on the slot that draws it, or one of its style props for the common case. A component resolves its own styles first, then your style props, then your style — so style is where transforms, shadows and computed values go.

<Button variant="primary" paddingHorizontal={20}>
  <Button.Icon as={SaveIcon} />
  <Button.Label style={{ letterSpacing: 0.4 }}>Save</Button.Label>
</Button>

When you need your own element in that position instead, pass asChild and the slot merges its behaviour into your child.

Import from the component's own subpath — @xaui/native/button, @xaui/native/select. Each component is an entry point, so a screen only pulls in what it renders.

Every preview on this site is the real component under react-native-web, so the answer is yes for the render path documented here. @xaui/hybrid is the separate renderer for mobile webviews.

Give XAUIProvider a colorMode of light, dark or system. createTheme resolves both palettes once, in OKLab, so you declare the source colours and get the derived ones. XAUI does not persist the user's choice — that stays your storage.

Yes. Style props are the React Native names and values with no implicit scale, and style takes precedence over them, so an external stylesheet composes with a component rather than fighting it.

No. They are generated from the TypeScript types at build time, which is what keeps them from drifting: a prop that lands in the source shows up in the table with no edit here.

They keep working. @xaui/native-legacy is frozen and reads the same provider and tokens, so both trees live in one app while you move screen by screen — the migration guide has the prop mapping.