# Kara UI

> Real SwiftUI and Jetpack Compose views for React Native, styled through one token-typed sx surface — in the platform’s colours by default, and yours through the theme.

## Install

```bash
npx expo install @hzblj/kara-ui @expo/ui @lodev09/react-native-true-sheet expo-image react-native-reanimated react-native-worklets
```

Add the config plugin — `plugins: [['@hzblj/kara-ui', {icons: {source: './assets/icons'}}]]` — prebuild, and mount `<KaraProvider>` at the root. Native components render inside `<Screen>` or `<Island>`; style through token props (`p="s16"`, `bg="surface.primary"`), never raw values.

## Button

The platform’s own button, in four variants: accent, secondary, destructive and glass.

iOS: SwiftUI Button. Android: Compose Button / OutlinedButton. Native: renders inside <Screen> or <Island>.

```tsx
import {Button} from '@hzblj/kara-ui'

<VStack spacing="s12" wide>
  <Button label="Continue" onPress={next} wide />
  <Button label="Add to wishlist" variant="secondary" wide />
  <Button label="Delete account" variant="destructive" wide />
</VStack>
```

### ButtonProps

- `buttonStyle?: ButtonStyleName` — Replaces the style the variant picks — `borderedProminent` for `accent` and `destructive`, `bordered` for `secondary`, `glass` for `glass`. iOS only — Android ignores it.
- `controlSize?: ButtonControlSize` (default `'large'`) — SwiftUI's control size. `large` by default. iOS only — Android ignores it.
- `disabled?: boolean` (default `false`) — Draws the button in its disabled colours and stops it responding to presses.
- `label: string` — The button's text.
- `onPress?: () => void` — Called when the button is pressed.
- `testID?: string` — Test identifier, forwarded to the native view.
- `tint?: ColorToken` — Overrides the variant's own tint. A prominent style takes it as the fill and picks a contrasting label. `glass` has to reach the material through `glassEffect` instead, so tinting one costs it the stock `.glass` style — see the iOS implementation.
- `variant?: ButtonVariant` (default `'accent'`) — The look. `accent` by default. Material has no glass, so on Android `glass` is an outlined button.
- `wide?: boolean` (default `true`) — Stretches the button to the full width it is offered. On by default.

Notes:

- `buttonStyle` and `controlSize` are SwiftUI’s own and iOS only; Android keeps drawing the variant’s tokens.
- `glass` is Liquid Glass on iOS 26 and a translucent tonal button on Android.
- Any colour token can `tint` a button, and the label picks a colour that reads on it.

## IconButton

A button that is just an icon, for toolbars and compact rows.

iOS: SwiftUI Button. Android: Compose IconButton. Native: renders inside <Screen> or <Island>.

```tsx
import {IconButton} from '@hzblj/kara-ui'

<HStack spacing="s8">
  <IconButton name="share" onPress={share} />
  <IconButton name="heart" onPress={favourite} />
  <IconButton disabled name="lock" />
</HStack>
```

### IconButtonProps

- `disabled?: boolean` (default `false`) — Draws the icon in `btn.content.disabled` and stops the button responding to presses.
- `name: IconName` — The icon, one of the app's.
- `onPress?: () => void` — Called when the button is pressed.
- `testID?: string` — Test identifier, forwarded to the native view on iOS — Android ignores it.

Notes:

- `name` is one of your own icons — see Icons.

## Fab

The screen’s primary action, floating above the content.

iOS: SwiftUI Button, round and prominent. Android: Compose FloatingActionButton. Native: renders inside <Screen> or <Island>.

```tsx
import {Fab} from '@hzblj/kara-ui'

<Fab name="add" onPress={create} />
```

### FabProps

- `name: IconName` — The icon, one of the app's, drawn in `content.on.bg`.
- `onPress?: () => void` — Called when the button is pressed.
- `testID?: string` — Test identifier, forwarded to the native view on iOS — Android ignores it.

Notes:

- A real screen pins it to the bottom trailing corner; the component itself sits wherever it is laid out.

## FabMenu

A floating button that opens a few related actions.

iOS: SwiftUI Menu. Android: Material 3 FloatingActionButtonMenu. Native: renders inside <Screen> or <Island>.

```tsx
import {FabMenu, type MenuAction} from '@hzblj/kara-ui'

const actions: MenuAction[] = [
  {icon: 'share', label: 'Share', onPress: share},
  {icon: 'heart', label: 'Add to favourites', onPress: favourite},
  {destructive: true, icon: 'trash', label: 'Delete', onPress: remove},
]

<FabMenu actions={actions} />
```

### FabMenuProps

- `actions: MenuAction[]` — The actions the button unfolds into.
- `icon?: IconName` — The closed button's icon — one of the app's. A plus by default.
- `testID?: string` — Test identifier, forwarded to the SwiftUI `Menu`. iOS only — Android ignores it.

### MenuAction

- `destructive?: boolean` — Draws the action in the destructive colour — the system's destructive role on iOS. `FabMenu` ignores it on Android.
- `icon?: IconName` — One of the app's icons, before the label. `ContextMenu` and `FabMenu` show it on both platforms, `Menu` and `ActionSheet` on Android only.
- `label: string` — The action's text. Rows are keyed by it, so keep labels unique within one list.
- `onPress: () => void` — Called when the action is chosen; the menu closes by itself.

Notes:

- Android: Material 3 Expressive’s FAB menu — the button turns into a close and the actions rise above it as pills.
- iOS: the same round button as the label of a SwiftUI `Menu`.

## Link

Text that opens a URL.

iOS: SwiftUI HStack of Image and Text. Android: Compose Row of Icon and Text. Native: renders inside <Screen> or <Island>.

```tsx
import {Link} from '@hzblj/kara-ui'

<Link label="expo.dev" url="https://expo.dev" />
<Link icon="info" label="Read the docs" url="https://github.com/hzblj/kara-ui" />
```

### LinkProps

- `color?: ColorToken` (default `'content.accent'`) — Colours the label and the icon. `content.accent` by default.
- `icon?: IconName` — One of the app's icons, before the label.
- `label: string` — The link's text.
- `testID?: string` — Test identifier, forwarded to the native view.
- `url: string` — Opened through React Native's `Linking` on press. A URL nothing can open fails silently.
- `variant?: TextVariant` (default `'body'`) — The label's text style. `body` by default.

Notes:

- Opens the URL in the platform browser, or in whichever app claims the scheme. For in-app navigation use the router.

## Menu

A list of actions that drops down from a label.

iOS: SwiftUI Menu. Android: Compose DropdownMenu. Native: renders inside <Screen> or <Island>.

```tsx
import {Menu, type MenuAction} from '@hzblj/kara-ui'

const actions: MenuAction[] = [
  {icon: 'share', label: 'Share', onPress: share},
  {icon: 'heart', label: 'Add to favourites', onPress: favourite},
  {destructive: true, icon: 'trash', label: 'Delete', onPress: remove},
]

<Menu actions={actions} label="More options" />
```

### MenuProps

- `actions: MenuAction[]` — The menu's actions, top to bottom.
- `label: string` — The trigger's text. Android draws it in the accent colour, with a chevron.

### MenuAction

- `destructive?: boolean` — Draws the action in the destructive colour — the system's destructive role on iOS. `FabMenu` ignores it on Android.
- `icon?: IconName` — One of the app's icons, before the label. `ContextMenu` and `FabMenu` show it on both platforms, `Menu` and `ActionSheet` on Android only.
- `label: string` — The action's text. Rows are keyed by it, so keep labels unique within one list.
- `onPress: () => void` — Called when the action is chosen; the menu closes by itself.

Notes:

- iOS does not draw an action’s `icon` in the menu; Android does.

## ActionSheet

Actions that slide up from the bottom of the screen.

iOS: SwiftUI confirmationDialog. Android: Sheet with a list of actions. Native: renders inside <Screen> or <Island>.

```tsx
import {ActionSheet} from '@hzblj/kara-ui'

const [open, setOpen] = useState(false)

<Button label="Show actions" onPress={() => setOpen(true)} variant="secondary" />
<ActionSheet actions={actions} onDismiss={() => setOpen(false)} title="Air Max 90" visible={open} />
```

### ActionSheetProps

- `actions: MenuAction[]` — The choices, top to bottom. Picking one closes the sheet.
- `onDismiss: () => void` — The sheet closed — after a pick too — so turn `visible` off.
- `title: string` — The heading above the actions. Android always shows it; on iOS the system decides, and may hide it.
- `visible: boolean` — Presents the sheet while true.

Notes:

- Controlled: `visible` opens it, and `onDismiss` is where you set it back to `false`.
- iOS is a SwiftUI confirmation dialog — on iOS 26 a popover over its host — which may hide the title and draws no icons. Android is Material’s bottom-sheet menu, each action’s icon before its label.

## ContextMenu

A long-press menu on any React Native content, with a custom preview on iOS.

iOS: UIContextMenuInteraction. Android: Compose DropdownMenu on a long press. React Native tier: renders anywhere.

```tsx
import {ContextMenu} from '@hzblj/kara-ui'

<ContextMenu actions={actions} preview={<ProductPreview />} p="s16">
  <ProductCard />
</ContextMenu>
```

### ContextMenuProps

Also takes: ResponsiveViewSx

- `actions: MenuAction[]` — The menu's actions, top to bottom.
- `children: ReactNode` — The trigger, laid out as usual.
- `onPreviewPress?: () => void` — iOS: the user tapped the lifted preview, committing to it — open the detail the card stands for.
- `preview?: ReactNode` — iOS: lifted in place of the trigger while the menu is open — a larger version of the card, say. A snapshot of the trigger when unset. Mounted only once a finger has rested on the trigger, so a list of cards does not pay for every preview up front.
- `previewTransition?: 'dismiss' | 'pop' | 'zoom'` — iOS: how the preview leaves once tapped, before `onPreviewPress`. `zoom`: its photo grows straight into the pushed screen, the way the App Store expands a preview — needs a `ZoomTransition.Source` (`@hzblj/kara-ui/router`) in the trigger, a `preview` and iOS 18, and shrinks back like `dismiss` otherwise. `pop`: UIKit's default, the preview flies out. `dismiss`: it shrinks back onto the trigger first. Default: `zoom` when the trigger holds a `ZoomTransition.Source`, `pop` otherwise.
- `testID?: string` — Test identifier — on the native view around the trigger on iOS, on the trigger's `Pressable` on Android.

Notes:

- The trigger is ordinary React Native layout, so it needs no `Screen` or `Island`, and takes the view `sx` props.
- iOS lifts `preview` (or a snapshot of the trigger) above the menu. Material has no lifted preview: Android ripples, plays the long-press haptic and opens a dropdown where the finger is.
- With a `ZoomTransition.Source` in the trigger, a tap on the iOS preview zooms its photo straight into the pushed screen.

## SwipeActions

Buttons revealed by swiping a list row.

iOS: SwiftUI swipeActions. Android: Anchored drag (kara). Native: renders inside <Screen> or <Island>.

```tsx
import {SwipeActions} from '@hzblj/kara-ui'

<List>
  {orders.map(order => (
    <SwipeActions
      key={order.id}
      leading={[{icon: 'star', label: 'Pin', onPress: () => pin(order)}]}
      trailing={[
        {destructive: true, icon: 'trash', label: 'Delete', onPress: () => remove(order)},
        {icon: 'share', label: 'Share', onPress: () => share(order)},
      ]}
    >
      <ListItem subtitle={order.status} title={order.title} />
    </SwipeActions>
  ))}
</List>
```

### SwipeActionsProps

- `allowsFullSwipe?: boolean` (default `true`) — iOS: a swipe all the way across performs the edge's first action, as in Mail. Android has no full swipe. `true` by default, as in SwiftUI.
- `children: ReactNode` — The row.
- `leading?: SwipeAction[]` (default `[]`) — The buttons at the leading edge, uncovered by a swipe toward the trailing one. The first sits outermost.
- `testID?: string` — Test identifier. iOS: on the row. Android: the row is a Compose node, reach it by its content.
- `trailing?: SwipeAction[]` (default `[]`) — The buttons at the trailing edge, uncovered by a swipe toward the leading one. The first sits outermost.

### SwipeAction

- `destructive?: boolean` — Fills the button with `fill.destructive.primary` unless `tint` says otherwise.
- `icon: IconName` — One of the app's icons, on the button — a round one on iOS 26, as in Mail, a filled stadium on Android.
- `label: string` — The action's name, written under the button — before iOS 26 a row of the usual height shows the icon alone and keeps the label for VoiceOver. Actions are keyed by it, so keep labels unique within one row.
- `onPress: () => void` — Called when the button is pressed. The row closes by itself.
- `tint?: ColorToken` — The button's fill — `fill.destructive.primary` for a destructive action, `fill.accent.primary` otherwise. The icon on it is white, so pick a fill that holds white in both appearances.

Notes:

- A row of a `List`: SwiftUI only offers swipe actions there.
- iOS 26 draws each action as a round button in its tint with the label under it, the way Mail does. Compose has no swipe actions, so Android has kara’s own: the row slides on an anchored drag, and filled icon buttons with their labels under them show in the strip it leaves.
- One row is open at a time, and a tap on an open row closes it. A press closes the row before the action runs.
- `allowsFullSwipe` (on by default) runs the edge’s first action on a swipe all the way across — iOS only.

## Pressable

Makes any React Native content tappable, with press feedback built in.

iOS: React Native Pressable. Android: React Native Pressable. React Native tier: renders anywhere.

```tsx
import {Pressable} from '@hzblj/kara-ui'

<Pressable bg="fill.accent.primary" borderRadius="large" haptic onPress={open} p="s20">
  <RnText color="content.on.bg" variant="headline">Press me</RnText>
</Pressable>
```

### PressableProps

Also takes: ResponsiveViewSx

- `children?: ReactNode` — The pressable content.
- `disabled?: boolean` (default `false`) — Ignores presses — no `onPress`, no haptic, no spring.
- `haptic?: boolean | Haptic` (default `false`) — Played on press. `true` is a `light` impact; a name picks the haptic, e.g. `selection` for a choice.
- `onPress?: () => void` — Called when the press is released, after the `haptic` plays.
- `testID?: string` — Test identifier, forwarded to the view.

Notes:

- Springs to 96 % while held and takes touches 8 points past its edges.
- `haptic` is `true` for a light impact, or any haptic by name. iOS prepares it on press-in.

## Switch

An on/off setting, tinted with your accent.

iOS: SwiftUI Toggle. Android: Compose Switch. Native: renders inside <Screen> or <Island>.

```tsx
import {Switch} from '@hzblj/kara-ui'

const [wifi, setWifi] = useState(true)

<Switch label="Wi-Fi" onValueChange={setWifi} value={wifi} />
```

### SwitchProps

- `disabled?: boolean` (default `false`) — Stops the user flipping it, and dims it.
- `label?: string` — Shown beside the switch. On Android it makes a full-width row — label at the start, switch at the end — that toggles wherever it is tapped.
- `onValueChange?: (value: boolean) => void` — Called with the new value when the user flips it. On Android a flip plays `toggleOn` / `toggleOff`.
- `value: boolean` — Whether it is on. Controlled: pass back what `onValueChange` reports.

Notes:

- With a `label`, the whole row toggles.
- Android plays `toggleOn` / `toggleOff`, which Compose’s switch does not; iOS’s own switch keeps its own feedback.

## Checkbox

A yes/no choice, usually one of several in a form.

iOS: SwiftUI Toggle. Android: Compose Checkbox. Native: renders inside <Screen> or <Island>.

```tsx
import {Checkbox} from '@hzblj/kara-ui'

<Checkbox label="I agree to the terms" onValueChange={setAgreed} value={agreed} />
```

### CheckboxProps

- `disabled?: boolean` (default `false`) — Dims the control and ignores taps.
- `label?: string` — Text beside the control. On Android the whole labelled row toggles it.
- `onValueChange?: (value: boolean) => void` — Called with the new value when the user toggles it.
- `value: boolean` — Whether it is checked. Controlled — update it from `onValueChange`.

Notes:

- iOS has no checkbox of its own, so there it is a switch.

## RadioGroup

One choice out of a few, all visible at once.

iOS: SwiftUI rows with a checkmark. Android: Compose RadioButton rows. Native: renders inside <Screen> or <Island>.

```tsx
import {RadioGroup} from '@hzblj/kara-ui'

const options = [
  {label: 'Standard · 3–5 days', value: 'standard'},
  {label: 'Express · tomorrow', value: 'express'},
  {label: 'Pick up in store', value: 'store'},
]

<RadioGroup onValueChange={setDelivery} options={options} value={delivery} />
```

### RadioGroupProps

- `onValueChange?: (value: string) => void` — The user pressed an option; it passes that option's `value`.
- `options: RadioOption[]` — The choices, top to bottom.
- `value: string` — The selected option's `value`. Update it from `onValueChange`.

### RadioOption

- `label: string` — The option's text.
- `value: string` — Identifies the option to `value` and `onValueChange`, and keys its row — keep it unique.

Notes:

- Exactly one option is selected at all times. For an independent on/off, use `Switch` or `Checkbox`.

## Slider

A value along a range, picked by dragging.

iOS: SwiftUI Slider. Android: Compose Slider. Native: renders inside <Screen> or <Island>.

```tsx
import {Slider} from '@hzblj/kara-ui'

<Slider onValueChange={setVolume} value={volume} />
```

### SliderProps

- `disabled?: boolean` (default `false`) — Stops the user moving the thumb, and dims the slider.
- `max?: number` (default `1`) — The upper end. `1` by default.
- `min?: number` (default `0`) — The lower end. `0` by default.
- `onValueChange?: (value: number) => void` — Called with the new value as the thumb moves.
- `step?: number` — The increment between stops; leave it unset for a continuous slider. On Android every stop plays a `tick`.
- `value: number` — Between `min` and `max`. Controlled: pass back what `onValueChange` reports.

Notes:

- A stepped slider ticks at every stop on Android; iOS 26’s slider plays its own.

## Stepper

A number nudged up and down.

iOS: SwiftUI Stepper. Android: Compose row with minus and plus buttons. Native: renders inside <Screen> or <Island>.

```tsx
import {Stepper} from '@hzblj/kara-ui'

<Stepper label="Quantity" max={5} min={1} onValueChange={setCount} value={count} />
```

### StepperProps

- `label: string` — The leading text. iOS shows only the label, not the value — put the value in it if it should be seen. Android shows the value between its buttons.
- `max?: number` (default `Number.MAX_SAFE_INTEGER`) — The highest value. When unset, Android has no upper limit and iOS stops at `100`.
- `min?: number` (default `Number.MIN_SAFE_INTEGER`) — The lowest value. When unset, Android has no lower limit and iOS stops at `0`.
- `onValueChange: (value: number) => void` — A button was pressed; it passes the new value, kept within `min` and `max`.
- `step?: number` (default `1`) — How much one press adds or takes away. `1` by default.
- `value: number` — The current value. Update it from `onValueChange`. iOS's native stepper counts in whole numbers.

Notes:

- Without `min` and `max`, iOS stops at 0 and 100 and Android has no limits — set both.
- iOS steps in whole numbers.

## SegmentedControl

Switches between a few views of the same thing.

iOS: UISegmentedControl (kara). Android: Material segmented buttons. Brings its own host: renders anywhere.

```tsx
import {SegmentedControl} from '@hzblj/kara-ui'

<SegmentedControl
  onChange={index => setRange(index)}
  selectedIndex={range}
  values={['Day', 'Week', 'Month']}
/>
```

### SegmentedControlProps

- `disabled?: boolean` (default `false`) — Stops the user changing the segment, and dims the control.
- `onChange?: (index: number, value: string) => void` — Called with the index and label of the segment the user picked — never for a tap on the one already selected. Android plays `selection`; iOS's control plays its own feedback.
- `selectedIndex: number` — The selected segment. Controlled: pass back what `onChange` reports.
- `testID?: string` — Test identifier, on the whole control — reach a segment by its label.
- `values: string[]` — The segments' labels, in order.

Notes:

- The selected segment is in the accent on both platforms — on iOS through kara’s own `UISegmentedControl`, since neither the system control nor SwiftUI’s segmented picker lets the labels be coloured.
- It needs no `Screen` or `Island`: iOS is a plain view, Android brings its own host. It takes the width it is given; the height is the platform’s.
- `onChange` fires for a new segment only. Android plays `selection`; iOS plays the control’s own feedback.

## Picker

One choice out of a longer list.

iOS: Wheel picker. Android: Compose ExposedDropdownMenu. Brings its own host: renders anywhere.

```tsx
import {Picker} from '@hzblj/kara-ui'

const sizes = [
  {label: 'EU 41', value: '41'},
  {label: 'EU 42', value: '42'},
  {label: 'EU 43', value: '43'},
]

<Picker onValueChange={setSize} options={sizes} value={size} />
```

### PickerProps

- `disabled?: boolean` (default `false`) — Stops the user changing the selection, and dims the picker.
- `onValueChange?: (value: string) => void` — Called with the chosen option's `value`.
- `options: PickerOption[]` — The choices, in order.
- `testID?: string` — Android: the dropdown field's test tag. iOS: `@expo/ui`'s wheel picker drops it.
- `value: string` — The selected option's `value`. Controlled: pass back what `onValueChange` reports.

### PickerOption

- `label: string` — What the user reads.
- `value: string` — What `onValueChange` reports. It also keys the option, so it must be unique.

Notes:

- A wheel on iOS, an exposed dropdown menu on Android.

## DatePicker

A date, picked from the platform’s own calendar.

iOS: UIDatePicker, compact. Android: Material date picker dialog. Brings its own host: renders anywhere.

```tsx
import {DatePicker} from '@hzblj/kara-ui'

<DatePicker onValueChange={setDate} value={date} />
```

### DatePickerProps

- `max?: Date` — The latest date that can be picked. Android ignores it in `time` mode.
- `min?: Date` — The earliest date that can be picked. Android ignores it in `time` mode.
- `mode?: DatePickerMode` (default `'date'`) — What it picks. `date` by default. Android has no combined dialog, so there `datetime` picks the date and keeps `value`'s time of day.
- `onValueChange?: (date: Date) => void` — Called with the new date — on iOS as it changes, on Android when the dialog is confirmed.
- `testID?: string` — Test identifier — on the native picker on iOS, on the tappable field on Android.
- `value: Date` — The selected date. Controlled — update it from `onValueChange`.

Notes:

- iOS shows a compact field that opens the calendar; Android a field that opens Material’s date dialog.
- It sizes itself to its value — put it at the end of a row, beside its label.
- Android reports the date once the dialog is confirmed; iOS as it changes.

## ColorPicker

The system colour picker.

iOS: SwiftUI ColorPicker. Android: —. Native: renders inside <Screen> or <Island>.

```tsx
import {ColorPicker} from '@hzblj/kara-ui'

<ColorPicker label="Accent" onValueChange={setColor} value={color} />
```

### ColorPickerProps

- `label?: string` — Text beside the colour well.
- `onValueChange?: (color: string) => void` — Called with the colour the user picks.
- `supportsOpacity?: boolean` (default `false`) — Lets the user pick an opacity as well. Off by default.
- `testID?: string` — Test identifier, forwarded to the native view.
- `value: string | null` — `#RRGGBB` or `#RRGGBBAA`.

Notes:

- iOS only — Compose has no colour picker, and on Android it renders nothing (with a dev warning).

## TextField

Text input with a label, for secure entry and errors too.

iOS: SwiftUI TextField / SecureField. Android: Compose OutlinedTextField. Native: renders inside <Screen> or <Island>.

```tsx
import {TextField} from '@hzblj/kara-ui'

<VStack spacing="s16" wide>
  <TextField label="Email" onChangeText={setEmail} />
  <TextField label="Password" secure />
  <TextField error label="Postcode" />
</VStack>
```

### TextFieldProps

- `defaultValue?: string` (default `''`) — The text it starts with. Read once, on mount — the field is uncontrolled.
- `disabled?: boolean` (default `false`) — Stops editing and dims the field. On iOS it outranks `error`.
- `error?: boolean` (default `false`) — Marks the field invalid: a destructive outline and label.
- `label?: string` — Shown above the field, in `labelMedium`.
- `multiline?: boolean` (default `false`) — Wraps the text and grows the field to fit it. iOS ignores it when `secure`.
- `onChangeText?: (text: string) => void` — Called with the whole text after every change.
- `secure?: boolean` (default `false`) — Masks the text, for a password.
- `testID?: string` — iOS: forwarded to the native field. Android ignores it.

Notes:

- Uncontrolled: start it with `defaultValue` and read changes from `onChangeText`.

## SearchBar

A search field with the platform’s look.

iOS: React Native, UIKit style. Android: React Native, Material style. React Native tier: renders anywhere.

```tsx
import {SearchBar} from '@hzblj/kara-ui'

<SearchBar onChangeText={setQuery} placeholder="Search stores" value={query} />
```

### SearchBarProps

- `onChangeText?: (text: string) => void` — Every edit, and `''` when the clear button is pressed.
- `placeholder?: string` (default `'Search'`) — Shown while the field is empty. `Search` by default.
- `testID?: string` — Test identifier, put on the field's container view rather than on the `TextInput`.
- `value: string` — The field's text. Controlled — pass back what `onChangeText` reports.

Notes:

- React Native tier: it hosts nothing native, so it renders outside `Screen` and `Island` too.

## Chip

Compact toggles for filters and tags.

iOS: React Native. Android: React Native. React Native tier: renders anywhere.

```tsx
import {Chip} from '@hzblj/kara-ui'

<Box flexDirection="row" gap="s8" wrap="wrap">
  {topics.map(topic => (
    <Chip key={topic} label={topic} onPress={() => toggle(topic)} selected={picked.includes(topic)} />
  ))}
</Box>
```

### ChipProps

- `label: string` — The text in the pill.
- `onPress?: () => void` — Called when the chip is pressed, with the `selection` haptic.
- `selected?: boolean` (default `false`) — Draws the chip in the accent colours. Off by default.
- `testID?: string` — Test identifier, forwarded to the view.

Notes:

- A filter pill in the React Native tier, not a native control. It plays `selection` when pressed.

## Text

Text in the type scale, coloured by token.

iOS: SwiftUI Text. Android: Compose Text. Native: renders inside <Screen> or <Island>.

```tsx
import {Text} from '@hzblj/kara-ui'

<Text variant="headline">Order summary</Text>
<Text color="content.secondary">Arrives Friday</Text>
```

### TextProps

- `align?: TextAlign` — How its lines align. iOS reads `left` and `right` as leading and trailing, so they flip in a right-to-left layout; Android keeps them as they are.
- `children?: ReactNode` — The text.
- `color?: ColorToken` (default `'content.primary'`) — The text's colour. `content.primary` by default.
- `decoration?: TextDecoration` — An underline or a strikethrough.
- `numberOfLines?: number` — The most lines it wraps to. iOS truncates the last with an ellipsis; Android clips it.
- `testID?: string` — Test identifier, forwarded to the native view.
- `transform?: TextTransform` — Upper- or lower-cases the text. Android applies it only when `children` is a plain string.
- `variant?: TextVariant` (default `'body'`) — The typography variant. `body` by default.

Notes:

- Native text, inside a host. Outside one, use `RnText` — same variants, same colours.
- Every variant grows with Dynamic Type on iOS and font scale on Android.
- With `numberOfLines`, iOS ends the last line with an ellipsis; Android clips it.

## Label

An icon and a short text, aligned.

iOS: SwiftUI HStack of Image and Text. Android: Compose Row of Icon and Text. Native: renders inside <Screen> or <Island>.

```tsx
import {Label} from '@hzblj/kara-ui'

<Label icon="star" title="Featured" color="content.accent" variant="labelMedium" />
```

### LabelProps

- `color?: ColorToken` (default `'content.primary'`) — Colours the icon and the title alike. `content.primary` by default.
- `icon: IconName` — One of the app's icons, before the title.
- `iconSize?: SpaceSize` (default `'s20'`) — The icon's size. `s20` by default.
- `testID?: string` — Test identifier, forwarded to the native view.
- `title: string` — The text beside the icon.
- `variant?: TextVariant` (default `'body'`) — The title's text style. `body` by default.

Notes:

- An inline pair for a button, a menu row or a section header. For a tappable row with a subtitle, use `ListItem`.

## LabeledContent

A label with a value or a control beside it.

iOS: SwiftUI HStack. Android: Compose Row. Native: renders inside <Screen> or <Island>.

```tsx
import {LabeledContent} from '@hzblj/kara-ui'

<LabeledContent label="Version" px="s16" value="2.4.0" />
<LabeledContent label="Back up photos" px="s16">
  <Switch onValueChange={setBackup} value={backup} />
</LabeledContent>
```

### LabeledContentProps

- `children?: ReactNode` — The trailing side when it is a control, in place of `value`.
- `icon?: IconName` — One of the app's icons, before the label, in the secondary colour.
- `label: string` — The leading text.
- `onPress?: () => void` — Makes the row pressable and adds a chevron on the trailing edge.
- `px?: SpaceSize` — Horizontal padding inside the row — inside its press area too, so Android's ripple reaches the card's edges.
- `testID?: string` — Test identifier, forwarded to the native view.
- `value?: string` — The trailing text, in the secondary colour. Ignored when `children` is given.

Notes:

- Pass `children` instead of `value` when the trailing side is a control rather than text.

## Badge

A small status label.

iOS: SwiftUI capsule. Android: Compose Badge. Native: renders inside <Screen> or <Island>.

```tsx
import {Badge} from '@hzblj/kara-ui'

<Badge label="New" />
<Badge label="Sale" tone="accent" />
<Badge label="In stock" tone="success" />
<Badge label="Sold out" tone="destructive" />
```

### BadgeProps

- `label: string` — The text inside.
- `tone?: BadgeTone` (default `'neutral'`) — The fill and text colours. `neutral` by default.

## Avatar

A person’s initials or photo in a circle.

iOS: React Native. Android: React Native. React Native tier: renders anywhere.

```tsx
import {Avatar} from '@hzblj/kara-ui'

<Avatar initials="AN" size="lg" />
<Avatar size="md" source={{uri: user.photo}} />
```

### AvatarProps

- `initials?: string` — Shown in place of the image when there is no `source`.
- `size?: AvatarSize` (default `'md'`) — The diameter — `sm` is `s24`, `md` `s40`, `lg` `s64`. `md` by default.
- `source?: ImageSourcePropType` — The image, cropped to the circle.
- `testID?: string` — Test identifier, forwarded to the view.

Notes:

- Falls back to `initials` when there is no `source`.

## Icon

Your own SVG icons, drawn natively in both tiers.

iOS: SwiftUI Image from the asset catalog. Android: Compose Icon with a vector drawable. Native: renders inside <Screen> or <Island>.

```tsx
import {Icon, RnIcon} from '@hzblj/kara-ui'

<Icon name="heart" />
<RnIcon color="content.accent" name="heart" />
```

### IconProps

- `accessibilityLabel?: string` — What a screen reader says. Unset, the icon is decorative and hidden from it.
- `color?: ColorToken` (default `'content.primary'`) — The icon's tint. `content.primary` by default.
- `name: IconName` — Which of the app's icons — a key of `KaraIcons`.
- `size?: SpaceSize` (default `'s24'`) — Its width and height, a spacing token. `s24` by default.
- `testID?: string` — Test identifier, forwarded to the native view on iOS — Android ignores it.

Notes:

- Your own SVGs, made native at prebuild by the config plugin — see Icons. The library ships no icon set.
- `Icon` draws inside a host; `RnIcon` draws the same asset anywhere in React Native layout.

## Image

A remote or local image that fades in.

iOS: expo-image. Android: expo-image. React Native tier: renders anywhere.

```tsx
import {Image} from '@hzblj/kara-ui'

<Image contentFit="cover" source={{uri: photo}} style={{borderRadius: 20, height: 220, width: '100%'}} />
```

Notes:

- `expo-image`, with the design system’s 100 ms linear fade already applied, so a loaded image never pops in. It takes every `expo-image` prop.

## Card

A raised container for one piece of content.

iOS: SwiftUI VStack. Android: Compose Column. Native: renders inside <Screen> or <Island>.

```tsx
import {Card} from '@hzblj/kara-ui'

<Card>
  <VStack align="start" spacing="s4">
    <Text variant="headingXs">Air Max 90</Text>
    <Text color="content.secondary" variant="subheadline">Leather, mesh and a visible Air unit.</Text>
  </VStack>
</Card>
```

### CardProps

Also takes: ResponsiveSx

- `children?: ReactNode` — Native views, stacked vertically from the leading edge.
- `testID?: string` — Test identifier, forwarded to the native view.

Notes:

- Carries `surface.primary`, the `card` shadow and a large radius on both platforms — pass `sx` props to override any of them.

## Surface

A coloured, rounded background — plain or glass.

iOS: SwiftUI VStack in a GlassEffectContainer. Android: Compose Surface. Native: renders inside <Screen> or <Island>.

```tsx
import {Surface} from '@hzblj/kara-ui'

<Surface wide>
  <Text variant="labelMedium">Plain surface</Text>
</Surface>
<Surface bg="fill.accent.base" glass wide>
  <Text variant="labelMedium">Glass surface</Text>
</Surface>
```

### SurfaceProps

Also takes: ResponsiveSx

- `children?: ReactNode` — Stacked vertically, from the leading edge.
- `glass?: boolean` (default `false`) — iOS wraps the content in a `GlassEffectContainer`; Android raises it to a tonal elevation of `3`.
- `testID?: string` — Test identifier, forwarded to the native view.

Notes:

- `glass` reaches for iOS 26 glass and a Material 3 tonal surface on Android — the two do not look alike, and are not meant to.

## GlassView

Liquid Glass around any React Native content.

iOS: UIGlassEffect. Android: A translucent capsule. React Native tier: renders anywhere.

```tsx
import {GlassView} from '@hzblj/kara-ui'

<Pressable onPress={play}>
  <GlassView interactive px="s20" py="s12">
    <RnText pointerEvents="none" variant="labelMedium">Play</RnText>
  </GlassView>
</Pressable>
```

### GlassViewProps

Also takes: ResponsiveViewSx

- `children?: ReactNode` — React Native views. Give them `pointerEvents="none"` when `interactive`, so the press reaches the `Pressable`.
- `interactive?: boolean` (default `false`) — Swells toward the finger on touch, carrying the children with it. Wrap the view in a `Pressable` for the press.
- `testID?: string` — Test identifier, forwarded to the view.
- `tint?: ColorToken` — Tints the material. Unset leaves it clear.

Notes:

- Liquid Glass on iOS 26, as a UIKit view — no host, so it is cheap enough for every cell of a list.
- Below iOS 26 and on Android it is a capsule of `tint`, or of the translucent glass fill.
- Interactive glass swells toward the finger and carries its children; the press itself belongs to a `Pressable` around it.

## EmptyState

What to show when there is nothing to show.

iOS: SwiftUI VStack. Android: Compose Column. Native: renders inside <Screen> or <Island>.

```tsx
import {EmptyState} from '@hzblj/kara-ui'

<EmptyState
  action={<Button label="Clear filters" onPress={clear} variant="secondary" />}
  description="Try a different search, or clear the filters."
  icon="search"
  title="No results"
/>
```

### EmptyStateProps

- `action?: ReactNode` — Under the text — a `Button`, say.
- `description?: string` — A second line under the title, in the secondary colour.
- `icon?: IconName` — One of the app's icons, large and muted above the title.
- `testID?: string` — Test identifier, forwarded to the native view.
- `title: string` — The headline.

## Stacks

VStack, HStack and ZStack lay native views out in a column, a row or layers.

iOS: SwiftUI VStack, HStack, ZStack. Android: Compose Column, Row, Box. Native: renders inside <Screen> or <Island>.

```tsx
import {VStack, HStack, ZStack, Spacer, Divider} from '@hzblj/kara-ui'

<VStack align="start" bg="surface.primary" borderRadius="large" p="s16" spacing="s12" wide>
  <Text variant="headline">Order #1024</Text>
  <Divider />
  <HStack wide>
    <Text>Subtotal</Text>
    <Spacer />
    <Text variant="headline">€129</Text>
  </HStack>
</VStack>
```

### VStackProps

Also takes: ResponsiveSx

- `align?: VStackAlign` (default `'start'`) — The children's horizontal alignment. `start` by default.
- `children?: ReactNode` — Laid out top to bottom, `spacing` apart.
- `onPress?: () => void` — Makes the whole stack pressable. iOS adds a tap gesture with no press feedback; Android a `clickable` whose ripple fills the stack's shape.
- `spacing?: SpaceSize` — The space between children.
- `testID?: string` — Test identifier, forwarded to the native view.

### HStackProps

Also takes: ResponsiveSx

- `align?: HStackAlign` (default `'start'`) — How the children line up vertically — `start` is the top, `end` the bottom. `start` by default.
- `children?: ReactNode` — Native views, laid out from the leading edge.
- `onPress?: () => void` — Makes the stack pressable — a tap gesture on iOS, a `clickable` with Material's ripple on Android.
- `spacing?: SpaceSize` — The gap between children. Unset, SwiftUI puts its default spacing between them and Compose none.
- `testID?: string` — Test identifier, forwarded to the native view.

### ZStackProps

Also takes: ResponsiveSx

- `align?: ZStackAlign` (default `'center'`) — Where the children sit vertically; they are always centred horizontally. `center` by default.
- `children?: ReactNode` — Drawn in order, the last on top.
- `onPress?: () => void` — Makes the whole stack pressable. iOS adds a tap gesture with no press feedback; Android a `clickable` whose ripple fills the stack's shape.
- `testID?: string` — Test identifier, forwarded to the native view.

### SpacerProps

- `min?: SpaceSize` — The least room it takes. iOS holds it along the stack's axis; Android as a minimum height only.
- `testID?: string` — iOS: forwarded to the native view. Android ignores it.

### DividerProps

- `color?: ColorToken` (default `'border.tertiary'`) — The line's colour. `border.tertiary` by default.
- `testID?: string` — Test identifier, forwarded to the native view on iOS — Android ignores it.

Notes:

- Native stacks take the native `sx` surface: `spacing` rather than `gap`, `wide` and `tall` rather than flex.
- A stack with `onPress` is pressable, and on Android its ripple covers the whole shape, padding included.
- `Spacer` eats the free space; `spacing` is the fixed gap. A `ZStack` draws its last child on top.

## Island

Where native views meet React Native layout.

iOS: SwiftUI Host. Android: Compose Host. Brings its own host: renders anywhere.

```tsx
import {Island, RnView} from '@hzblj/kara-ui'

<RnScrollView content={{gap: 's24', p: 's20'}}>
  <RnText variant="headingS">Checkout</RnText>
  <Island>
    <Button label="Pay €129" onPress={pay} wide />
  </Island>
</RnScrollView>
```

### IslandProps

- `children?: ReactNode` — The native views it hosts.
- `matchContents?: boolean` (default `true`) — Sizes the island's height to its native content while the width still comes from the parent, which is what a full-width card wants. On by default. Only the height is ever measured: auto-sizing the width maps to `fixedSize(horizontal: true)`, so the native side ignores the proposed width and resolves a `wide` stack's ideal width as unbounded. Turn it off — and give the island an explicit size via `style` — when the subtree contains an `RnView`: that host drives its SwiftUI frame from the child's Yoga-laid-out bounds while this one writes its measured size back into the Yoga style, and the two together spin a layout loop that hangs the main thread as soon as the views lay out on screen.
- `style?: StyleProp<ViewStyle>` — A React Native style for the host view — its size and placement. It needs a height when `matchContents` is off.
- `testID?: string` — Test identifier, forwarded to the host view on iOS — Android ignores it.

### RnViewProps

- `children: ReactElement` — A single React Native *view*. It may not contain React Native text: a bare string becomes a `RawText` node, which has no component view, so mounting it across the SwiftUI host boundary fails the `RCTComponentViewFactory` assertion and takes the whole app down. `@expo/ui` states the rule itself in `ListItem.ios.tsx` — "SwiftUI hosts can't render bare strings" — and wraps every raw string in a SwiftUI `Text` before it reaches a host. Do the same: use the `Text` atom inside the host, and keep `RnText` outside it.
- `matchContents?: boolean` (default `true`) — Sizes the host to the child's measured layout. On by default because a raw RN view has no intrinsic size and would otherwise stretch to fill the SwiftUI parent.
- `testID?: string` — Not forwarded on either platform — give the child its own `testID`.

Notes:

- Native views only render inside an `Island` or a `Screen`. Outside one they silently disappear (in development, a warning says so).
- Sized to its content by default. Give it `matchContents={false}` and a height when the content has none of its own — a `List`, a `Form`, a `Pager` — or contains an `RnView`.
- `RnView` carries a React Native view back into a native layout.

## Screen

A whole screen of native views.

iOS: SwiftUI Host filling the screen. Android: Compose Host filling the screen. Brings its own host: renders anywhere.

```tsx
import {Screen} from '@hzblj/kara-ui'

export default function Settings() {
  return (
    <Screen>
      <List>
        <ListItem icon="user" onPress={openAccount} title="Account" />
        <ListItem icon="lock" title="Privacy" />
      </List>
    </Screen>
  )
}
```

### ScreenProps

- `bg?: Sx['bg']` (default `'surface.base'`) — The screen's colour. `surface.base` by default.
- `children?: ReactNode` — Laid out in a column that fills the screen.
- `ignoreKeyboardInset?: boolean` — Keeps the content where it is when the keyboard opens, instead of avoiding it. Android reads it once, on mount.
- `testID?: string` — Test identifier — on the host view on iOS, on the view around it on Android.

Notes:

- The full-bleed native host a screen starts with. Everything inside is native layout — for a React Native page with native islands, use `RnScrollView` and `Island` instead.
- The background runs to the edges; the content keeps clear of the status bar wherever the screen covers it — SwiftUI’s safe area on iOS, measured by kara on Android, where the app is edge to edge.

## List

A native scrolling list of rows.

iOS: SwiftUI List. Android: Compose LazyColumn. Native: renders inside <Screen> or <Island>.

```tsx
import {List, ListItem} from '@hzblj/kara-ui'

<List onRefresh={reload}>
  <ListItem icon="user" onPress={openAccount} subtitle="Name, email, password" title="Account" />
  <ListItem icon="notification" onPress={openNotifications} subtitle="Orders, offers" title="Notifications" />
  <ListItem icon="lock" subtitle="Face ID is on" title="Privacy" />
</List>
```

### ListProps

- `children: ReactNode` — The rows — native views, one row each.
- `onRefresh?: () => Promise<void>` — Enables pull-to-refresh. Async on purpose — see `ScrollViewProps.onRefresh`: the spinner runs until the promise settles, so neither platform needs a `refreshing` flag kept in sync by hand.
- `testID?: string` — Test identifier, forwarded to the native view on iOS — Android ignores it.

Notes:

- A list scrolls, so it needs a height from outside: a `Screen`, or an `Island` with `matchContents={false}` and a height.
- Rows are separated for you — a `Divider` among them is one too many.
- `onRefresh` returns a promise; the spinner runs until it settles.

## ListItem

A row with an icon, a title, a subtitle and a chevron.

iOS: SwiftUI HStack. Android: Compose Row. Native: renders inside <Screen> or <Island>.

```tsx
import {ListItem, RnListItem} from '@hzblj/kara-ui'

<ListItem icon="shopping-bag" onPress={openOrders} px="s16" subtitle="2 in progress" title="Orders" />
```

### ListItemProps

- `icon?: IconName` — One of the app's icons, before the title, in the secondary colour.
- `onPress?: () => void` — Makes the row pressable and adds a chevron on the trailing edge.
- `px?: SpaceSize` — Horizontal padding inside the row — inside its press area too, so Android's ripple reaches the card's edges. For rows in a card of your own; a `List` insets its rows by itself.
- `subtitle?: string` — A second line under the title, smaller and in the secondary colour.
- `testID?: string` — Test identifier, forwarded to the row's view.
- `title: string` — The row's main text.

Notes:

- Passing `onPress` is what earns the row its chevron.
- `RnListItem` is the same row in the React Native tier — no host, cheap to mount by the dozen.

## Form

Grouped sections of settings and fields.

iOS: SwiftUI Form. Android: Compose cards. Native: renders inside <Screen> or <Island>.

```tsx
import {Form} from '@hzblj/kara-ui'

<Form>
  <Form.Section footer="We only send what you ask for." title="Notifications">
    <Switch label="Order updates" onValueChange={setUpdates} value={updates} />
    <Switch label="Offers" onValueChange={setOffers} value={offers} />
  </Form.Section>
  <Form.Section title="Profile">
    <TextField label="Display name" />
  </Form.Section>
</Form>
```

### FormProps

- `children: ReactNode` — The form's `Form.Section`s.
- `testID?: string` — Test identifier, forwarded to the native view.

### FormSectionProps

- `children: ReactNode` — The section's rows.
- `footer?: string` — Small print under the section.
- `title?: string` — The section's heading.

Notes:

- On iOS a form scrolls like a list and needs a height from outside. On Android it is a column of cards that sizes itself — inset from its container and with its titles indented to the cards’ content, like SwiftUI’s grouped form.

## Collapsible

Content that expands under its label.

iOS: SwiftUI DisclosureGroup. Android: Compose AnimatedVisibility. Native: renders inside <Screen> or <Island>.

```tsx
import {Collapsible} from '@hzblj/kara-ui'

<Collapsible expanded={open} label="Shipping and returns" onExpandedChange={setOpen}>
  <Text color="content.secondary">Free shipping over €50. Returns within 30 days.</Text>
</Collapsible>
```

### CollapsibleProps

- `children: ReactNode` — Shown while `expanded`.
- `expanded: boolean` — Whether the content is shown. Update it from `onExpandedChange`.
- `label: string` — The row's text.
- `onExpandedChange: (expanded: boolean) => void` — The user pressed the row; it passes the state the row asks for.

## Pager

Swipeable pages that snap into place.

iOS: SwiftUI TabView, page style. Android: Compose HorizontalPager. Native: renders inside <Screen> or <Island>.

```tsx
import {Pager} from '@hzblj/kara-ui'

<Island matchContents={false} style={{height: 220}}>
  <Pager indicators onPageChange={setPage} page={page}>
    <Promo title="New in" />
    <Promo title="Running" />
    <Promo title="Sale" />
  </Pager>
</Island>
```

### PagerProps

- `children?: ReactNode` — The pages, one per child, in order.
- `indicators?: boolean` (default `true`) — Page dots. iOS draws SwiftUI's own, over the bottom edge; Compose has no built-in indicator, so Android composes the dots and places them below the pager, which is where Material puts them.
- `onPageChange?: (page: number) => void` — Fires once a swipe or a programmatic move has settled, never mid-gesture.
- `page?: number` — Zero-based. Controlled when passed; otherwise the pager just starts at 0 and owns its position.
- `pageSpacing?: SpaceSize` — Android only — a SwiftUI page-style `TabView` has no gap between pages.
- `scrollEnabled?: boolean` (default `true`) — Android only. SwiftUI can only disable a `TabView` as a whole, which would take the pages' content down with the swipe, so iOS always stays swipeable.
- `testID?: string` — Test identifier, forwarded to the native view.

Notes:

- Pages are its children, addressed by index.
- `pageSpacing` and `scrollEnabled` are Android only. iOS draws its own dots over the bottom edge; Android places them below.

## ScrollEdgeContainer

Bars over a scroll view, with the iOS 26 scroll edge effect under them.

iOS: UIScrollEdgeEffect. Android: A column of bar, scroll view, bar. React Native tier: renders anywhere.

```tsx
import {ScrollEdgeContainer} from '@hzblj/kara-ui'

<ScrollEdgeContainer bottomBar={<Totals />} flex={1} topBar={<Filters />}>
  <RnScrollView content={{gap: 's12', p: 's16'}}>{rows}</RnScrollView>
</ScrollEdgeContainer>
```

### ScrollEdgeContainerProps

Also takes: ResponsiveViewSx

- `automaticInsets?: boolean` — iOS: adds the bars' heights to the scroll view's own `contentInset` and starts it at the top of that inset, so the content begins below the top bar and scrolls under it. On by default.
- `bottomBar?: ReactNode` — Laid over the scroll view's bottom edge on iOS; stacked below it on Android, where it wants a background.
- `children: ReactElement<ScrollEdgeScrollableProps>` — Exactly one React Native scroll view — `RnScrollView`, `RnFlatList`, `RnSectionList`.
- `effect?: ScrollEdgeEffect` — iOS 26: how hard the edge cuts. `soft` by default.
- `testID?: string` — Test identifier, forwarded to the container view.
- `topBar?: ReactNode` — Laid over the scroll view's top edge on iOS; stacked above it on Android, where it wants a background.

Notes:

- iOS 26 gives both bars the system scroll edge effect — the progressive blur under content scrolling past them.
- Below iOS 26 the bars are still inset, without the effect: check `isScrollEdgeEffectAvailable()` and give them a background.
- Android has no effect, so the bars stack above and below the scroll view instead of over it.

## Progress

How far along something is — or that it is still going.

iOS: SwiftUI ProgressView. Android: Compose Linear / CircularProgressIndicator. Native: renders inside <Screen> or <Island>.

```tsx
import {Progress} from '@hzblj/kara-ui'

<Progress value={0.6} />
<Progress />
<Progress circular />
```

### ProgressProps

- `circular?: boolean` (default `false`) — A circular indicator instead of a bar. Off by default.
- `value?: number` — Between `0` and `1`. Leave it unset for an indeterminate indicator.

Notes:

- Leave `value` unset for the indeterminate spinner; pass 0–1 for a determinate bar.

## ActivityIndicator

A small spinner, for the React Native tier.

iOS: React Native ActivityIndicator. Android: React Native ActivityIndicator. React Native tier: renders anywhere.

```tsx
import {ActivityIndicator} from '@hzblj/kara-ui'

<ActivityIndicator />
```

Notes:

- React Native’s own spinner, tinted with `fill.accent.primary`. It takes every React Native `ActivityIndicator` prop.

## Skeleton

Pulsing placeholders for content on its way.

iOS: Reanimated view. Android: Reanimated view. React Native tier: renders anywhere.

```tsx
import {Skeleton} from '@hzblj/kara-ui'

<Box flexDirection="row" gap="s12">
  <Skeleton borderRadius="full" height={48} width={48} />
  <Box flex={1} gap="s8">
    <Skeleton height={14} width={140} />
    <Skeleton height={14} />
  </Box>
</Box>
```

### SkeletonProps

- `borderRadius?: RadiiSize` (default `'small'`) — The corner radius. `small` by default.
- `height: number` — In points.
- `testID?: string` — Test identifier, forwarded to the view.
- `width?: number` — In points. Leave it unset and it fills the available width.

Notes:

- Leave `width` unset and it fills the row — the usual shape for a line of text.

## Snackbar

A brief message at the bottom of the screen.

iOS: React Native. Android: React Native. React Native tier: renders anywhere.

```tsx
import {Snackbar} from '@hzblj/kara-ui'

<Snackbar actionLabel="Undo" message="Item deleted" onAction={undo} visible={deleted} />
```

### SnackbarProps

- `actionLabel?: string` — The action button's text, on the trailing side. No button without it.
- `message: string` — The message.
- `onAction?: () => void` — The action was pressed. The snackbar stays up — turn `visible` off to hide it.
- `visible: boolean` — Shows the snackbar while true, fading it in and out. It sets no timer of its own.

Notes:

- Pinned to the bottom of its parent, above everything in it. It shows while `visible` is true — hiding it after a while is yours to do.

## Alert

A question that needs an answer before going on.

iOS: SwiftUI alert. Android: Compose AlertDialog. Native: renders inside <Screen> or <Island>.

```tsx
import {Alert} from '@hzblj/kara-ui'

<Alert
  confirmLabel="Delete"
  destructive
  message="This removes your orders and wishlist. It cannot be undone."
  onConfirm={remove}
  onDismiss={() => setOpen(false)}
  title="Delete account?"
  visible={open}
/>
```

### AlertProps

- `confirmLabel?: string` (default `'OK'`) — The confirm button's label. `OK` by default.
- `destructive?: boolean` (default `false`) — Marks the confirm button destructive — the system's destructive role on iOS, the destructive colour on Android.
- `message?: string` — The body text, under the title.
- `onConfirm?: () => void` — The confirm button was pressed. `onDismiss` follows, as it does for every way the alert closes.
- `onDismiss: () => void` — The alert closed — either button, or on Android a tap outside or back — so turn `visible` off.
- `title: string` — The alert's heading.
- `visible: boolean` — Shows the alert while true.

Notes:

- Controlled: `visible` presents it and `onDismiss` reports every way it closed, Cancel included.

## Tooltip

A short hint pointing at what it explains.

iOS: SwiftUI popover. Android: Material plain tooltip (kara). Native: renders inside <Screen> or <Island>.

```tsx
import {Tooltip} from '@hzblj/kara-ui'

<Tooltip onDismiss={() => setOpen(false)} text="Free returns within 30 days" visible={open}>
  <HStack onPress={() => setOpen(true)}>
    <Text color="content.accent">What is this?</Text>
  </HStack>
</Tooltip>
```

### TooltipProps

- `children: ReactNode` — The anchor — a native view.
- `text: string` — The tip.
- `visible: boolean` — Shows the tip while true. Controlled: nothing opens it but this — wire a long press to it if you want one.
- `onDismiss: () => void` — The user dismissed the tip — turn `visible` off. iOS: a tap outside the popover. Android: any touch outside it, the start of a scroll included, or the anchor scrolling out of the window.

Notes:

- Controlled on both platforms: `visible` shows it, `onDismiss` reports a dismissal — nothing else opens it, so wire a long press to `visible` if you want one.
- Android draws Material’s plain tooltip in kara’s controlled `TooltipBox`, centred above the anchor and kept inside the window; any touch outside it, or the anchor scrolling away, dismisses it.

## RnTooltip

A rich tooltip with a title and actions, for React Native content.

iOS: kara’s UIKit tooltip. Android: Material rich tooltip. React Native tier: renders anywhere.

```tsx
import {RnTooltip} from '@hzblj/kara-ui'

<RnTooltip
  actions={[{label: 'Got it', onPress: () => setOpen(false)}]}
  message="Save items you like and find them here later."
  onDismiss={() => setOpen(false)}
  title="Your wishlist"
  visible={open}
>
  <WishlistButton />
</RnTooltip>
```

### RnTooltipProps

- `actions?: RnTooltipAction[]` — A row of buttons under the text, in order.
- `actionsAlignment?: 'end' | 'start'` (default `'end'`) — Which end of the bubble the actions sit at. `end` by default.
- `boundaryInsets?: {bottom?: number; top?: number}` — Insets from the window's top and bottom that the anchor's centre must stay inside — a header or a tab bar over the content. Past them the tooltip asks to be dismissed with `anchorHidden`.
- `children: ReactElement` — The anchor — a single React Native view.
- `message?: string` — The body text, under the title.
- `onDismiss: (reason: RnTooltipDismissReason) => void` — Asks for the tooltip to close, with the reason — turn `visible` off. On Android any touch outside asks, the start of a scroll included; iOS keeps the tooltip through a scroll.
- `onShown?: () => void` — The appear animation finished.
- `title?: string` — The heading line, above the message.
- `visible: boolean` — Shows the tooltip while true. It never hides itself.

Notes:

- Anchored below a React Native view and drawn above every sibling — the anchor needs no host.
- iOS keeps it through a scroll; Material dismisses it on any outside touch, the start of a scroll included.

## Sheet

A native sheet with a native header: titles, back, close and actions, detents and a large title.

iOS: UISheetPresentationController with a UINavigationBar. Android: TrueSheet with a Material top app bar. React Native tier: renders anywhere.

```tsx
import {Sheet} from '@hzblj/kara-ui'

<Sheet onDismiss={close} visible={open}>
  <Sheet.Header title="Choose a size" trailingItems={[{onPress: close, type: 'close'}]} />
  <SizeList />
</Sheet>
```

### SheetProps

- `bg?: ColorToken` (default `'surface.primary'`) — The sheet's colour. `surface.primary` by default.
- `children: ReactNode` — The content. A `<Sheet.Header>` among the direct children becomes the native header instead.
- `detents?: SheetDetent[]` (default `FIT_CONTENT`) — Where the sheet can rest, smallest first. `['auto']` — fit the content — by default.
- `dimmed?: boolean` (default `true`) — Dims what is behind. On by default.
- `dismissible?: boolean` (default `true`) — A swipe down or a tap outside closes it. On by default.
- `draggable?: boolean` (default `true`) — It follows the finger between detents. On by default.
- `footer?: ReactElement` — Pinned to the bottom, above the content and the keyboard.
- `grabber?: boolean` (default `true`) — The drag handle. On by default.
- `onDismiss: () => void` — The user dismissed it — `visible` going false does not call this.
- `onDetentChange?: (detentIndex: number) => void` — The sheet moved to another detent — its index in `detents`.
- `onPresent?: () => void` — The sheet finished presenting.
- `ref?: Ref<SheetRef>` — `present`, `dismiss` and `resize`, for driving the sheet imperatively.
- `scrollable?: boolean` (default `false`) — The content is a scroll view (`<Sheet.ScrollView>`) the sheet drives: dragging past its top resizes the sheet, and a header scrolls with the iOS 26 edge effect. Off by default — set it with a scrolling body.
- `testID?: string` — Test identifier, forwarded to the native sheet.
- `visible: boolean` — Presents the sheet while true; going false dismisses it.

### SheetHeaderProps

- `children?: ReactNode` — Pinned under the bar.
- `inverted?: boolean` — Light items and title, for a sheet with a dark or image background.
- `leadingItems?: NavigationBarItem[]` — In screen order, from the leading edge.
- `search?: NavigationBarSearch` — A search field in place of the title (iOS).
- `title?: string` — The title — in the bar, or above the content with a `large` `titleStyle`.
- `titleStyle?: SheetTitleStyle` — `center` by default.
- `trailingItems?: NavigationBarItem[]` — In screen order, toward the trailing edge — the close item, by convention.

### SheetScrollViewProps

Also takes: Pick<ScrollViewProps, 'keyboardShouldPersistTaps'>

- `children: ReactNode` — The scrolling content, after the large title if there is one.
- `content?: ResponsiveViewSx` — Styles the scrolling content — padding and gap belong here, as with `RnScrollView`.
- `onScroll?: SheetScrollHandler` — Called on every scroll event, after the sheet's own listener.
- `testID?: string` — Test identifier, forwarded to the scroll view.

Notes:

- React Native tier, on TrueSheet: no host, and never inside one — native atoms in its content go in an `Island`.
- `Sheet.Header` is a slot, not a view: a direct child, built from `NavigationBar` into a real native header.
- On iOS 26 a scrollable sheet lays its header over the content, so `Sheet.ScrollView` pads by the header’s height.
- `onDismiss` is the user’s dismissal only — setting `visible` to false dismisses without calling it.

## NavigationBar

A title with items on either side — a real navigation bar outside a navigation stack.

iOS: UINavigationBar. Android: Material TopAppBar. Brings its own host: renders anywhere.

```tsx
import {NavigationBar, type NavigationBarItem} from '@hzblj/kara-ui'

<NavigationBar
  leadingItems={[{onPress: back, type: 'back'}]}
  title="Checkout"
  trailingItems={[{onPress: close, type: 'close'}]}
/>
```

### NavigationBarProps

- `inverted?: boolean` (default `false`) — Light items and title, for a bar laid over an image or a dark hero.
- `leadingItems?: NavigationBarItem[]` — In screen order, from the leading edge.
- `search?: NavigationBarSearch` — Replaces the title with a search field (iOS).
- `testID?: string` — Test identifier, forwarded to the native bar. iOS only — Android ignores it.
- `title?: string` — The bar's title.
- `titleAlignment?: NavigationBarTitleAlignment` (default `'center'`) — `center` by default — iOS's own; `leading` is Material's top app bar.
- `titleVisible?: boolean` (default `true`) — Fades the title out and in without moving the items — for a large title that scrolls under the bar.
- `trailingItems?: NavigationBarItem[]` — In screen order, toward the trailing edge.

Notes:

- For a header that is not a navigation screen — `Sheet.Header` is built on it.
- iOS: a standalone `UINavigationBar`; on iOS 26 neighbours share one glass capsule, and `separated` gives an item its own.
- Android: Material’s top app bar. `search` replaces the title on iOS only.
- It places nothing: items go on the side and in the order you give them.

## Tabs

Native tabs for Expo Router.

iOS: UITabBarController. Android: Material NavigationBar. React Native tier: renders anywhere.

```tsx
import {Tabs} from '@hzblj/kara-ui/router'

// app/(tabs)/_layout.tsx
import {Tabs} from '@hzblj/kara-ui/router'

export default function TabsLayout() {
  return (
    <Tabs>
      <Tabs.Screen icon="home" name="(home)" selectedIcon="home-filled" title="Home" />
      <Tabs.Screen icon="widgets" name="components" title="Components" />
      <Tabs.Screen icon="palette" name="design" title="Design" />
    </Tabs>
  )
}
```

### TabsProps

- `children: ReactNode` — One `Tabs.Screen` per child route; any other child goes to the navigator as it is.
- `minimizeBehavior?: TabsMinimizeBehavior` (default `'never'`) — Whether the iOS 26 tab bar shrinks to a pill while scrolling. Off by default, unlike the system, which minimizes on scroll. Minimizing changes the tab bar's height mid-gesture, and a native tabs screen re-insets the first scroll view inside it to match — so the content shifts under the finger every time the scroll direction changes, and every list in the app inherits that. Opt in per screen once the content is built to absorb it.

### TabsScreenProps

- `hidden?: boolean` — Drops the tab from the bar *and* makes the route unreachable by navigation. Prefer this over conditionally rendering the screen: every child route needs a declared tab, and toggling this at runtime remounts the navigator, so pass a build constant.
- `icon: IconName` — One of the app's icons — the asset-catalog image on iOS, the vector drawable on Android.
- `name: string` — The child route the tab opens, by its Expo Router name.
- `selectedIcon?: IconName` — Swapped in while the tab is active — the filled counterpart of `icon`, say.
- `testID?: string` — Test identifier of the tab's bar item — its accessibility identifier on iOS, its view tag on Android.
- `title: string` — The tab's label in the bar.

Notes:

- An Expo Router layout, on Expo Router’s native tabs: the system tab bar on iOS, Material’s navigation bar on Android, both in the theme’s colours.
- Every child route needs a `Tabs.Screen`. `hidden` drops a tab and makes its route unreachable.
- The iOS 26 bar does not minimise on scroll unless you ask with `minimizeBehavior`.

## ZoomTransition

A push that grows out of the view it was opened from, and shrinks back into it.

iOS: UIKit zoom transition. Android: Material container transform. React Native tier: renders anywhere.

```tsx
import {ZoomTransition, ZOOM_TRANSITION_PARAM, useZoomTransitionParam, useZoomTransitionSourceId, withZoomTransition} from '@hzblj/kara-ui/router'

// the list
const zoomId = useZoomTransitionSourceId(photo.id)
const open = () => router.push({params: {id: photo.id, [ZOOM_TRANSITION_PARAM]: zoomId}, pathname: '/photo/[id]'})

<Pressable onPress={open}>
  <ZoomTransition.Source android={{borderRadius: 'large'}} identifier={zoomId}>
    <Photo />
  </ZoomTransition.Source>
</Pressable>

// the pushed screen
const zoomId = useZoomTransitionParam()

<ZoomTransition.Enabler ios={{dismissGesture: 'vertical'}} sourceIdentifier={zoomId} />
<ZoomTransition.Target android={{borderRadius: 'large'}} identifier={zoomId}>
  <Photo />
</ZoomTransition.Target>

// the root layout — a full-screen modal, the way a gallery opens
<Stack.Screen
  name="photo/[id]"
  options={withZoomTransition({headerShown: Platform.OS === 'android', presentation: 'fullScreenModal'})}
/>
```

### ZoomTransitionSourceProps

- `android?: ZoomTransitionSourceAndroidOptions` — Android-only settings.
- `children: ReactElement` — A single view — the photo or card the zoom grows from.
- `identifier?: string` — Unset renders `children` alone: no zoom from here. Use `useZoomTransitionSourceId` for one unique per item.

### ZoomTransitionEnablerProps

- `android?: ZoomTransitionEnablerAndroidOptions` — Android-only settings: Material's container transform.
- `ios?: ZoomTransitionEnablerIosOptions` — iOS-only settings: UIKit's zoom.
- `scrim?: ColorToken` — Laid over the screen behind the zoomed one. Unset: UIKit's own dimming on iOS, none on Android.
- `sourceIdentifier?: string` — The source's identifier, handed over in the route params. Unset renders nothing: the push stays the stack's own.

### ZoomTransitionTargetProps

- `android?: ZoomTransitionTargetAndroidOptions` — Android-only settings.
- `children: ReactElement` — A single view — what the source lands on in the pushed screen.
- `identifier?: string` — The source's identifier, handed over in the route params. Unset renders `children` alone.
- `ios?: ZoomTransitionTargetIosOptions` — iOS-only settings.

Notes:

- iOS 18: UIKit’s zoom transition, with the interactive dismissal. Below iOS 18 the push stays a slide. Android: Material’s container transform, both ways.
- Three pieces tied by one identifier, which travels in the route params.
- The enabler renders first and unconditionally — behind a loading state, the push is already a slide.
- Zooming into a modal, give it no native header on iOS: a modal’s bar lives in a nested stack, which the zoom does not reach. Draw a close of your own; a drag down closes it too.
- Settings both platforms honour sit at the top; the rest is typed apart under `ios` and `android`.

## Box

A styled React Native view.

iOS: React Native View. Android: React Native View. React Native tier: renders anywhere.

```tsx
import {Box} from '@hzblj/kara-ui'

<Box bg="surface.primary" borderRadius="large" flexDirection="row" gap="s12" p="s16">
  <Avatar initials="AN" />
  <RnText variant="headline">Anna Novak</RnText>
</Box>
```

Notes:

- A React Native `View` wearing the `sx` props — for layout a native stack cannot express.
- It takes the wider of the two `sx` surfaces: `flexDirection`, `gap`, margins, flex and per-corner radii work here and on none of the native atoms.

## RnText

React Native text in the type scale.

iOS: React Native Text. Android: React Native Text. React Native tier: renders anywhere.

```tsx
import {RnText} from '@hzblj/kara-ui'

<RnText color="content.secondary" variant="footnote">2 items</RnText>
```

### RnTextProps

Also takes: Omit<RNTextProps, 'style'>

- `align?: 'center' | 'left' | 'right'` — Horizontal alignment, as React Native's `textAlign`.
- `color?: ColorToken` (default `'content.primary'`) — The text's colour. `content.primary` by default.
- `variant?: TextVariant` (default `'body'`) — The typography variant. `body` by default.

Notes:

- The same variants and colours as `Text`, for text outside a native host. It takes every React Native `Text` prop.

## RnScrollView

A React Native scroll view with the `sx` props.

iOS: React Native ScrollView. Android: React Native ScrollView. React Native tier: renders anywhere.

```tsx
import {RnScrollView} from '@hzblj/kara-ui'

<RnScrollView content={{gap: 's32', p: 's20'}} flex={1}>
  {sections}
</RnScrollView>
```

### RnScrollViewProps

Also takes: ResponsiveViewSx, Omit<RNScrollViewProps, 'contentContainerStyle' | 'horizontal' | 'style'>

- `axis?: ScrollViewAxis` (default `'vertical'`) — The scroll direction. `vertical` by default.
- `children?: ReactNode` — The scrolling content.
- `content?: ResponsiveViewSx` — Styles the scrolling content container — padding and gap belong here.
- `showsIndicators?: boolean` (default `true`) — Shows the scroll indicators. On by default.

Notes:

- The scroll view a page full of `Island`s wants. Top-level `sx` styles the viewport, `content` the scrolling content — padding and gap belong there.

## RnFlatList

React Native lists for rows that host native views.

iOS: React Native FlatList. Android: React Native FlatList. React Native tier: renders anywhere.

```tsx
import {RnFlatList, RnSectionList} from '@hzblj/kara-ui'

<RnFlatList
  data={orders}
  keyExtractor={order => order.id}
  renderItem={({item}) => (
    <Island>
      <ListItem title={item.title} />
    </Island>
  )}
/>
```

### RnFlatListProps

Also takes: ResponsiveViewSx, Omit<RNFlatListProps<TItem>, 'contentContainerStyle' | 'style'>

- `content?: ResponsiveViewSx` — Styles the scrolling content container — padding and gap belong here.

### RnSectionListProps

Also takes: ResponsiveViewSx, Omit<RNSectionListProps<TItem, TSection>, 'contentContainerStyle' | 'style'>

- `content?: ResponsiveViewSx` — Styles the scrolling content container — padding and gap belong here.

Notes:

- The list to reach for when rows host native views: cells stay in normal flow, so a hosted view stays where the layout put it.
- `RnSectionList` is the sectioned sibling. Its sticky headers are off by default.

## ScrollView

A native scroll view.

iOS: SwiftUI ScrollView. Android: Compose scrollable Column. Native: renders inside <Screen> or <Island>.

```tsx
import {ScrollView} from '@hzblj/kara-ui'

<ScrollView p="s16" spacing="s12">
  <Text variant="headline">Order #1024</Text>
  <Text color="content.secondary">Shipped · arrives Friday</Text>
</ScrollView>
```

### ScrollViewProps

Also takes: ResponsiveSx

- `axis?: ScrollViewAxis` (default `'vertical'`) — The scroll direction. `vertical` by default.
- `children?: ReactNode` — Laid out in a stack along `axis`.
- `onRefresh?: () => Promise<void>` — Enables pull-to-refresh. Async on purpose: the spinner runs until the promise settles, which is what SwiftUI's `refreshable` expects and what Compose's controlled indicator is driven from — so neither platform needs a separate `refreshing` flag to be kept in sync by the caller. Only a vertical scroll view can be pulled; on a horizontal one both platforms ignore it.
- `showsIndicators?: boolean` (default `true`) — iOS only — Compose exposes no indicator toggle, so Android always shows the native one.
- `spacing?: SpaceSize` — The space between children.
- `testID?: string` — Test identifier, forwarded to the native view.

Notes:

- The native scroll container, for a subtree that is native all the way down. Its `sx` styles the scrolling content.
- For a React Native subtree, use `RnScrollView` instead.