# React Native Dialog

> An accessible React Native dialog (modal) for iOS, Android and the web, built like shadcn/ui: DialogTrigger, DialogContent, DialogTitle, DialogDescription, DialogFooter and DialogClose. Closes on the backdrop, Escape and Android back, traps focus on the web, scrolls when tall, and draws in brand, iOS, Material 3 or web style. Zero native code. Use it as one element with props, or compose the parts.

# Dialog

A window over the screen that keeps the user's attention until they finish or close it: an edit form, details, a choice that needs more room than a menu. It's put together from parts with the same names as shadcn/ui's Dialog. To ask "are you sure?", use [`AlertDialog`](./alert-dialog). For rich content that should fill a phone screen (a form with a pinned footer, details, media), or a side panel, use [`Modal` and `Drawer`](./modal).

The quickest way: give `Dialog` a `trigger`, a `title`, a `description` and `actions`, and it draws the parts itself. Its children are the body. Each action is a [`Button`](./button) that runs its `onPress`, then closes.

```tsx live

export default function Example() {
  return (
    <Dialog
      trigger={<Button variant="outline">Edit profile</Button>}
      title="Edit profile"
      description="Make changes to your profile. Save when you're done."
      actions={[{ label: 'Cancel', variant: 'outline' }, { label: 'Save changes', onPress: () => {} }]}
    />
  );
}
```

## Anatomy

A dialog is a trigger and a card of parts. Each part is optional except `DialogContent`:

```tsx
<Dialog>
  <DialogTrigger />          {/* opens it: your button */}
  <DialogContent>            {/* the card, over a backdrop */}
    <DialogHeader>
      <DialogTitle />        {/* names it for screen readers */}
      <DialogDescription />
    </DialogHeader>
    {/* your content */}
    <DialogFooter>
      <DialogClose />        {/* closes it: your button */}
    </DialogFooter>
  </DialogContent>
</Dialog>
```

For full control, leave those props out and compose the parts, as in shadcn/ui. Both work the same way, and you can switch any time.

```tsx live
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from 'patine-ui';

export default function Example() {
  return (
    <Dialog>
      <DialogTrigger>
        <Button variant="outline">Edit profile</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Edit profile</DialogTitle>
          <DialogDescription>Make changes to your profile. Save when you're done.</DialogDescription>
        </DialogHeader>
        <DialogFooter>
          <DialogClose>
            <Button variant="outline">Cancel</Button>
          </DialogClose>
          <DialogClose>
            <Button>Save changes</Button>
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}
```

- `Dialog` holds the state. Every other part goes inside it.
- `DialogTrigger` wraps one pressable element, such as a `Button`, and opens the dialog when it's pressed. The child's own `onPress` still runs.
- `DialogContent` is the window: a card centered over a dimmed backdrop.
- `DialogHeader` holds `DialogTitle` and `DialogDescription`. The title names the dialog for screen readers and the description describes it.
- `DialogFooter` holds the buttons: in a row at the end, or in the iOS design as full-width cells split by hairlines.
- `DialogClose` wraps one pressable element and closes the dialog when it's pressed.

## Examples

Each example is live: edit the code and it runs.

### Invite a teammate

A controlled dialog that checks its form before closing: `onOpenChange` reports the user's closes, and the Send button closes it from your code once the input is valid.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import {
  Button,
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  RadioGroup,
  Text,
  TextField,
  Toaster,
  toast,
} from 'patine-ui';

export default function Example() {
  const [open, setOpen] = useState(false);
  const [email, setEmail] = useState('');
  const [role, setRole] = useState('editor');
  const [tried, setTried] = useState(false);
  const valid = /^\S+@\S+\.\S+$/.test(email);
  const send = () => {
    setTried(true);
    if (!valid) return;
    setOpen(false);
    toast.success('Invitation sent', { description: `${email} can join as ${role === 'editor' ? 'an editor' : 'a viewer'}.`, toasterId: 'invite' });
    setEmail('');
    setTried(false);
  };
  return (
    <View style={{ height: 160 }}>
      <Dialog open={open} onOpenChange={setOpen}>
        <DialogTrigger>
          <Button startIcon={<Text color="onPrimary">＋</Text>} style={{ alignSelf: 'flex-start' }}>Invite teammate</Button>
        </DialogTrigger>
        <DialogContent>
          <DialogHeader>
            <DialogTitle>Invite to Acme Design</DialogTitle>
            <DialogDescription>They'll get an email with a link to join.</DialogDescription>
          </DialogHeader>
          <TextField
            label="Email"
            placeholder="name@company.com"
            keyboardType="email-address"
            autoCapitalize="none"
            value={email}
            onValueChange={setEmail}
            error={tried && !valid ? 'Enter a valid email' : undefined}
            onSubmitEditing={send}
          />
          <RadioGroup
            value={role}
            onValueChange={setRole}
            aria-label="Role"
            options={[
              { value: 'editor', label: 'Editor', description: 'Can edit and comment' },
              { value: 'viewer', label: 'Viewer', description: 'Can view and comment' },
            ]}
          />
          <DialogFooter>
            <Button variant="outline" onPress={() => setOpen(false)}>Cancel</Button>
            <Button onPress={send}>Send invite</Button>
          </DialogFooter>
        </DialogContent>
      </Dialog>
      <Toaster id="invite" />
    </View>
  );
}
```

### Order details, opened from code

Pass `open` and `onOpenChange` to open it from your own state, for example after a request finishes. `onOpenChange` fires only when the user opens or closes it, never when you change `open`. Without `open`, the dialog keeps its own state, starting from `defaultOpen`. `DialogTrigger` is optional when you control it.

```tsx live
import { useState } from 'react';
import {
  Button,
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
} from 'patine-ui';

export default function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button onPress={() => setOpen(true)}>Show details</Button>
      <Dialog open={open} onOpenChange={setOpen}>
        <DialogContent>
          <DialogHeader>
            <DialogTitle>Order #1042</DialogTitle>
            <DialogDescription>Shipped today. It should arrive on Thursday.</DialogDescription>
          </DialogHeader>
          <DialogFooter>
            <Button onPress={() => setOpen(false)}>OK</Button>
          </DialogFooter>
        </DialogContent>
      </Dialog>
    </>
  );
}
```

### Dismissing

A press on the backdrop, Escape on the web, Android's back button and the iOS VoiceOver escape gesture all close the dialog and call `onOpenChange(false)`. Pass `dismissible={false}` when the user must choose a button, for example during a step that can't be left half done.

### Rename a list

Put inputs right inside `DialogContent`. The dialog moves up out of the keyboard's way, and a tap on a button doesn't first just close the keyboard. When the content is taller than the screen, the card stops at the screen's edges and scrolls.

```tsx live
import { TextInput } from 'react-native';
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from 'patine-ui';

export default function Example() {
  return (
    <Dialog>
      <DialogTrigger>
        <Button variant="outline">Rename</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Rename list</DialogTitle>
        </DialogHeader>
        <TextInput
          defaultValue="Groceries"
          accessibilityLabel="List name"
          style={{ borderWidth: 1, borderColor: '#DFE5EA', borderRadius: 8, padding: 10, fontSize: 16 }}
        />
        <DialogFooter>
          <DialogClose>
            <Button>Save</Button>
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}
```

### Share a document

A dialog for a short task, closed with the ✕ in its header or a press on the backdrop.

```tsx live
import { useState } from 'react';
import {
  Avatar,
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  HStack,
  Switch,
  Text,
  TextField,
  VStack,
} from 'patine-ui';

const PEOPLE = [
  { name: 'Maya Cohen', access: 'Owner' },
  { name: 'Leo Martin', access: 'Can edit' },
];

export default function Example() {
  const [copied, setCopied] = useState(false);
  return (
    <Dialog>
      <DialogTrigger>
        <Button variant="outline" style={{ alignSelf: 'flex-start' }}>Share</Button>
      </DialogTrigger>
      <DialogContent>
        <HStack justify="space-between" align="flex-start">
          <DialogHeader style={{ flex: 1 }}>
            <DialogTitle>Share “Q3 roadmap”</DialogTitle>
            <DialogDescription>Anyone with the link can view.</DialogDescription>
          </DialogHeader>
          <DialogClose>
            <Button size="icon" variant="ghost" accessibilityLabel="Close">
              <Text>✕</Text>
            </Button>
          </DialogClose>
        </HStack>
        <HStack gap="sm" align="flex-end">
          <TextField label="Link" readOnly defaultValue="https://acme.app/d/q3-roadmap" style={{ flex: 1 }} />
          <Button variant="secondary" onPress={() => setCopied(true)}>{copied ? 'Copied' : 'Copy'}</Button>
        </HStack>
        <Switch label="Allow comments" defaultChecked />
        <VStack gap="sm">
          {PEOPLE.map((person) => (
            <HStack key={person.name} gap="sm" align="center">
              <Avatar size="sm" name={person.name} />
              <Text style={{ flex: 1 }}>{person.name}</Text>
              <Text size="sm" color="textSecondary">{person.access}</Text>
            </HStack>
          ))}
        </VStack>
      </DialogContent>
    </Dialog>
  );
}
```

## In real apps

Patine Pro screens built with it. Each opens on that screen, live, in the screens gallery.

## Designs

- **Patine**: a card with large corners that fades and grows in, the title at the start and the buttons at the end.
- **iOS**: an iOS alert, 270pt wide, with centered text and the buttons as full-width cells split by hairlines; three or more stack.
- **Material**: a Material 3 dialog with 28dp corners, a large title and the buttons at the end.
- **Web**: a centered modal with a deep shadow.

Open each one to compare:

```tsx live
import { Button, Dialog, HStack } from 'patine-ui';

const DESIGNS = { brand: 'Brand', ios: 'iOS', material: 'Material', web: 'Web' } as const;

export default function Example() {
  return (
    <HStack gap="sm" wrap>
      {Object.entries(DESIGNS).map(([design, label]) => (
        <Dialog
          key={design}
          design={design as keyof typeof DESIGNS}
          trigger={<Button variant="outline">{label}</Button>}
          title="Turn on backups?"
          description="Your photos and messages are saved to the cloud every night."
          actions={[{ label: 'Not now', variant: 'outline' }, { label: 'Turn on' }]}
        />
      ))}
    </HStack>
  );
}
```

## Guidelines

<Do preview={<>Delete “Q3 roadmap”?CancelDelete</>}>

**Name the action in the button.** People answer the question without reading it twice.

<Dont preview={<>Are you sure?NoYes</>}>

**Don't answer with Yes and No.** The buttons don't say what happens.

<Do preview={<>Turn on backups?Photos are saved every night.</>}>

**Keep it to one decision.** A title, a sentence and up to two buttons.

<Dont preview={<>Edit profileName · Email · Phone · Address · Bio · Links · Photo…</>}>

**Don't put a whole screen in a dialog.** Long forms belong in a sheet or their own screen.

## Accessibility

| | Behaviour |
| --- | --- |
| Role | `dialog` with `aria-modal`, labelled by `DialogTitle` and described by `DialogDescription`. Without a title, give `DialogContent` an `aria-label`. |
| Announced | `DialogTrigger` reports `expanded` while it's open. On iOS, VoiceOver stays inside (`accessibilityViewIsModal`). |
| Keyboard (web) | Focus moves to the first control when it opens; Tab stays inside; Escape closes it and focus goes back to the trigger. |
| Touch target | The buttons you pass keep their 44pt targets; the backdrop closes it unless `dismissible={false}`. |
| Reduce motion | With reduce motion on, it appears and disappears without animating. |

- iOS's escape gesture closes it.

## API

### Dialog

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | — | Open, when you control it. |
| `defaultOpen` | `boolean` | `false` | Open at first, when it keeps its own state. |
| `onOpenChange` | `(open: boolean) => void` | — | Called when the user opens or closes it. |
| `trigger` | `ReactElement` | — | Shorthand: one pressable, such as a `Button`, that opens it. |
| `title` | `ReactNode` | — | Shorthand: the `DialogTitle`. |
| `description` | `ReactNode` | — | Shorthand: the `DialogDescription`. |
| `actions` | `DialogAction[]` | — | Shorthand: the footer's buttons, `{ label, onPress?, variant?, ...ButtonProps }`. Each runs its `onPress`, then closes. |
| `children` | `ReactNode` | — | The parts, or the body when you use the shorthand. |
| `dismissible` | `boolean` | `true` | Closes on the backdrop, Escape and Android back. |
| `theme` | `DeepPartial<Theme>` | — | Theme override, for every part. |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |

### DialogTrigger and DialogClose

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactElement` | **Required** | One pressable element, such as a `Button`. |

### DialogContent

Takes React Native's `View` props, such as `style`, `testID` and `aria-label`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | The header, body and footer. |

### DialogHeader and DialogFooter

Take React Native's `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | — | The title and description, or the buttons. |

### DialogTitle

`level` defaults to `2`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `level`, `size`, `weight`, `font`, `color`, `theme`, `design` | | | The props of [`Heading`](./text). |

### DialogDescription

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size`, `weight`, `font`, `color`, `theme`, `design` | | | The props of [`Text`](./text). |

Right to left and custom styles work the same on every component: see [Internationalization and right to left](../guides/i18n-rtl) and [Styling](../guides/styling).
