# Presentation components

> Present controlled native sheets, alerts, and anchored popovers.

Canonical: https://natui.dev/docs/components/presentation

All presentation state is controlled by React. Native dismissal reports `false` through `onChange`.

## Sheet [#sheet]

### SheetProps

A modal sheet. `value` controls presentation; host-side dismissal is an
optimistic change(false), so an app that keeps `value` true gets
prevent-dismissal via the standard corrective update. Children materialize
eagerly; gate expensive content with `{open && <Content/>}`.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `boolean` | Yes |  |
| `onChange` | `((presented: boolean) => void) \| undefined` | No |  |
| `children` | `ReactNode` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<Sheet value={open} onChange={setOpen}>
  <VStack spacing={12} padding={20}>
    <Text font="headline">New item</Text>
    <Button onPress={() => setOpen(false)}>Done</Button>
  </VStack>
</Sheet>
```

Children materialize even while the sheet is closed. Gate expensive content with `{open && <Content />}` when necessary.

On macOS a sheet uses native sheet presentation. Windows renders an in-tree scrim and card, so it appears in host-rendered screenshots.

## Alert [#alert]

Alerts are data-driven rather than child-based:

### AlertProps

A native alert dialog, fully data-driven (no children). Button presses
emit onSelect(buttonId) FIRST, then the dismissal change(false).

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `boolean` | Yes |  |
| `title` | `string` | Yes |  |
| `message` | `string \| undefined` | No |  |
| `buttons` | `AlertButtonSpec[]` | Yes |  |
| `onSelect` | `((buttonId: string) => void) \| undefined` | No |  |
| `onChange` | `((presented: boolean) => void) \| undefined` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<Alert
  value={confirming}
  title="Delete item?"
  message="This cannot be undone."
  buttons={[
    { id: 'cancel', label: 'Cancel', role: 'cancel' },
    { id: 'delete', label: 'Delete', role: 'destructive' },
  ]}
  onSelect={handleAlertButton}
  onChange={setConfirming}
/>
```

Button selection fires before the dismissal change. Windows supports at most one cancel button and two other buttons, drops additional buttons with a warning, and does not render destructive styling.

## Popover and PopoverContent [#popover-and-popovercontent]

Ordinary `Popover` children form the anchor. A single `PopoverContent` child forms the presented body.

### PopoverProps

An anchored popover. Ordinary children render inline as the anchor; the
single PopoverContent child is the presented content.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `boolean` | Yes |  |
| `arrowEdge` | `"top" \| "bottom" \| "leading" \| "trailing" \| undefined` | No |  |
| `onChange` | `((presented: boolean) => void) \| undefined` | No |  |
| `children` | `ReactNode` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

### PopoverContentProps


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | No |  |
| `padding` | `number \| EdgeInsets \| undefined` | No |  |
| `background` | `string \| undefined` | No |  |
| `cornerRadius` | `number \| undefined` | No |  |
| `frame` | `Frame \| undefined` | No |  |
| `opacity` | `number \| undefined` | No |  |
| `disabled` | `boolean \| undefined` | No |  |
| `hidden` | `boolean \| undefined` | No |  |
| `color` | `string \| undefined` | No | Foreground color. |
| `help` | `string \| undefined` | No | Tooltip. |
| `tag` | `string \| undefined` | No | Stable row identity for selectable containers (List/Table selection). A selectable List reports and receives selection as its rows' tags. |
| `badge` | `string \| number \| undefined` | No | Badge shown on Tab items and List rows (counts, short strings). |
| `accessibilityLabel` | `string \| undefined` | No | Assistive-tech label (VoiceOver / Narrator). |
| `accessibilityHint` | `string \| undefined` | No | Assistive-tech hint describing the result of activating the element. |
| `accessibilityIdentifier` | `string \| undefined` | No | Stable identifier for UI automation (AX identifier / AutomationId). |
| `key` | `string \| number \| undefined` | No |  |

```tsx
<Popover value={open} arrowEdge="bottom" onChange={setOpen}>
  <Button onPress={() => setOpen(true)}>Help</Button>
  <PopoverContent padding={12}>
    <Text>This is native UI.</Text>
  </PopoverContent>
</Popover>
```

Open alerts, popovers, and menus use popup layers on Windows and are not included in `RenderTargetBitmap` screenshots.