@limonify/zest-ui

Base UI for React Native — headless, unstyled, accessible primitive components.

@limonify/zest-ui is a React Native port of MUI Base UI. Same compound parts (Dialog.Popup, Dialog.Backdrop), same controlled/uncontrolled patterns — adapted for touch and React Native accessibility APIs.

Zero style. Zero theme. Zero animation library. You own the look; zest owns behaviour, state, and accessibility. Style with StyleSheet, Uniwind, NativeWind, Tamagui, or anything else.

Docs: zestui.limonify.com

Why zest

• Base UI API — familiar compound components and part names, not a Radix rename
• Headless — every part renders a plain RN primitive (View, Pressable, Text, TextInput)
• State as style — style and className accept a function of state (the RN counterpart of data-*)
• Accessible — roles and states map to accessibilityRole / accessibilityState (and keep aria-* for RN-web)

Install

bun add @limonify/zest-ui
# or: npm install @limonify/zest-ui

Peers: React 19+, React Native 0.79+.

react-native-gesture-handler is a required peer — install it alongside zest. On Expo, use npx expo install react-native-gesture-handler so you get the version your SDK's Expo Go ships; a mismatch crashes at gesture attach rather than at build:

bun add react-native-gesture-handler

It is required rather than optional because the package root re-exports every component, and Metro does not tree-shake: importing anything from @limonify/zest-ui pulls in Slider, Drawer, Toast and NumberField, which import it statically. Reach for the per-component subpaths (@limonify/zest-ui/dialog) if you want a bundle without it.

Wrapping the app is separate, and only needed if you actually render one of the gesture-driven parts — Slider, Drawer, Toast, or NumberField.ScrubArea:

import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
  return <GestureHandlerRootView style={{ flex: 1 }}>{/* ... */}</GestureHandlerRootView>;
}

Anchored popups (Popover, Tooltip, Menu, Select, Combobox, …) use @floating-ui/react-native, which ships as a regular dependency — nothing extra to install.

Full install guide: zestui.limonify.com/docs/installation

Quick start

Style from state — no themes, no CSS variables:

import { StyleSheet } from 'react-native';
import { Switch } from '@limonify/zest-ui';

export function DarkModeToggle() {
  return (
    <Switch.Root style={(state) => [styles.track, state.checked && styles.trackOn]}>
      <Switch.Thumb style={(state) => [styles.thumb, state.checked && styles.thumbOn]} />
    </Switch.Root>
  );
}

const styles = StyleSheet.create({
  track: { width: 44, height: 26, borderRadius: 13, backgroundColor: '#d4d4d4', padding: 3 },
  trackOn: { backgroundColor: '#4c7a0b' },
  thumb: { width: 20, height: 20, borderRadius: 10, backgroundColor: '#fff' },
  thumbOn: { transform: [{ translateX: 18 }] },
});

Compound overlays use the same part tree as Base UI. Portals are React Native Modals:

import { Text, StyleSheet } from 'react-native';
import { Dialog } from '@limonify/zest-ui';

export function DeleteDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger style={styles.button}>
        <Text style={styles.buttonText}>Delete</Text>
      </Dialog.Trigger>

      <Dialog.Portal>
        <Dialog.Backdrop style={styles.backdrop} />
        <Dialog.Viewport style={styles.viewport}>
          <Dialog.Popup style={styles.card}>
            <Dialog.Title style={styles.title}>Delete file?</Dialog.Title>
            <Dialog.Description style={styles.body}>This can't be undone.</Dialog.Description>
            <Dialog.Close style={styles.button}>
              <Text style={styles.buttonText}>Cancel</Text>
            </Dialog.Close>
          </Dialog.Popup>
        </Dialog.Viewport>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

const styles = StyleSheet.create({
  button: {
    alignSelf: 'flex-start',
    backgroundColor: '#171717',
    borderRadius: 10,
    paddingVertical: 10,
    paddingHorizontal: 16,
  },
  buttonText: { color: '#fff', fontWeight: '600' },
  backdrop: { ...StyleSheet.absoluteFillObject, backgroundColor: 'rgba(0,0,0,0.5)' },
  viewport: { flex: 1, alignItems: 'center', justifyContent: 'center', padding: 24 },
  card: { width: '100%', maxWidth: 340, gap: 8, borderRadius: 16, backgroundColor: '#fff', padding: 20 },
  title: { fontSize: 17, fontWeight: '700' },
  body: { color: '#737373' },
});

Common props

Every part accepts the same small set on top of its own API:

| Prop | Role | | --- | --- | | style | RN style, or (state) => style | | className | String or (state) => string for Uniwind / NativeWind | | render | (props, state) => ReactNode — swap the host element, keep behaviour | | ref | Ref to the underlying element (React 19 — ref is a regular prop) |

<Dialog.Trigger render={(props) => <MyButton {...props}>Open</MyButton>} />

<Checkbox.Root
  className={(state) =>
    ['size-6 rounded border', state.checked && 'bg-lime-600'].filter(Boolean).join(' ')
  }
/>

Toast

Most components need no provider. Toast is the exception — it must not block the app, so it is not a Modal. Mount Toast.Provider and Toast.Viewport once at the root:

import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { Toast } from '@limonify/zest-ui';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <Toast.Provider timeout={4000} limit={3}>
        <RootNavigator />
        <Toast.Viewport style={{ paddingHorizontal: 16, paddingBottom: 48 }}>
          {/* map toasts → Toast.Root — see https://zestui.limonify.com/docs/components/toast */}
        </Toast.Viewport>
      </Toast.Provider>
    </GestureHandlerRootView>
  );
}

Skip GestureHandlerRootView if you use neither Slider nor Drawer; skip Toast setup if you don't use toasts.

Components

33 components. Import from @limonify/zest-ui:

import { Dialog, Switch, Toast } from '@limonify/zest-ui';

Forms & input

| Component | Parts | | --- | --- | | Button | — | | Input | — | | Checkbox | Root, Indicator | | CheckboxGroup | — | | Radio | Root, Indicator | | RadioGroup | — | | Switch | Root, Thumb | | Toggle | — | | ToggleGroup | — | | Slider | Root, Label, Value, Control, Track, Indicator, Thumb | | NumberField | Root, Group, Input, Increment, Decrement, ScrubArea | | OTPField | Root, Input, Separator | | Field | Root, Item, Label, Control, Description, Error, Validity | | Form | Form | | Fieldset | Root, Legend | | Select | Root, Label, Trigger, Value, Icon, Portal, Backdrop, Positioner, Arrow, Popup, List, Group, GroupLabel, Item, ItemText, ItemIndicator, Separator | | Combobox | Root, Trigger, Input, Chips, Chip, ChipRemove, Clear, Portal, Backdrop, Positioner, Popup, List, Group, GroupLabel, Collection, Item, ItemIndicator, Empty, Status, Value, Icon | | Autocomplete | Root, Trigger, Input, Clear, Portal, Backdrop, Positioner, Popup, List, Group, GroupLabel, Collection, Item, Empty, Status |

Disclosure

| Component | Parts | | --- | --- | | Collapsible | Root, Trigger, Panel | | Accordion | Root, Item, Header, Trigger, Panel | | Tabs | Root, List, Tab, Indicator, Panel |

Overlays

| Component | Parts | | --- | --- | | Dialog | Root, Trigger, Portal, Backdrop, Viewport, Popup, Title, Description, Close | | AlertDialog | same shape as Dialog | | Drawer | Root, Provider, Indent, IndentBackground, Trigger, Portal, Backdrop, Viewport, Popup, SwipeArea, Title, Description, Close | | Popover | Root, Trigger, Portal, Backdrop, Positioner, Popup, Arrow, Title, Description, Close | | Tooltip | Root, Trigger, Portal, Positioner, Popup, Arrow | | Menu | Root, Trigger, Portal, Backdrop, Positioner, Popup, Arrow, Item, LinkItem, CheckboxItem, RadioGroup, RadioItem, Group, GroupLabel, SubmenuRoot, SubmenuTrigger, Separator | | ContextMenu | Root, Trigger, Positioner, Arrow (+ Menu item family) |

Feedback & misc

| Component | Parts | | --- | --- | | Progress | Root, Track, Indicator, Value, Label | | Meter | Root, Track, Indicator, Label, Value | | Avatar | Root, Image, Fallback | | Separator | — | | Toast | Provider, Viewport, Root, Positioner, Arrow, Title, Description, Action, Close |

Popup families also support handles (createHandle, detached triggers, imperative open) — see the docs for each component.

Design notes

Portals are Modals. Every Portal (Dialog, Drawer, Popover, Tooltip, Menu, Select, Combobox, …) is a React Native Modal. That keeps context across the portal boundary and wires Android back / Escape to dismiss. Toast is the exception: an absolutely positioned View with pointerEvents="box-none" so the app underneath stays usable.

State, not data attributes. On the web, Base UI publishes data-* and CSS variables. In zest, state reaches you through the state object on style / className / render — state.open, state.checked, state.height, and so on.

zest never animates. Animated parts publish transitionStatus and measured geometry on state; you drive Animated (or Reanimated) yourself. Exit animations need keepMounted (or the part’s equivalent, e.g. Toast’s removeOnClose), otherwise the tree unmounts as soon as it closes.

Not ported

These Base UI pieces stay web/desktop-only:

| Component | Why | | --- | --- | | PreviewCard | Hover card — no hover on touch | | Menubar | Desktop navigation pattern | | NavigationMenu | Desktop multi-level hover menu | | ScrollArea | RN already has ScrollView / FlatList | | Toolbar | Desktop toolbar / roving tabindex | | CSPProvider | Content Security Policy is web-only |

Form is ported, adapted: there is no <form> submission, so it does the parts that still matter — spreading a server's errors onto the fields they name, and validating every field on submit. Submission is imperative, through actionsRef.

Base UI's useFilter is ported — Combobox and Autocomplete filter through it, and it is exported for filtering your own lists. See the docs.

DirectionProvider is ported. Direction defaults to React Native's own I18nManager.isRTL; wrap a subtree to override it. It decides which edge align="start" anchors a popup to and which way a horizontal slider grows — React Native mirrors the layout itself. See the docs.

Monorepo

This repository is a bun + turborepo workspace:

| Path | Role | | --- | --- | | packages/zest-ui | The publishable library | | apps/example | Expo demo exercising every component | | apps/docs | Documentation site (zestui.limonify.com) |

bun install
bun run test        # typecheck + tests via turbo
bun run build
bun run dev         # Expo example

The full implementation plan, milestones, and architecture notes live in ARCHITECTURE.md. Contributor notes for porting components live in packages/zest-ui/CLAUDE.md.

License

MIT © Limonify