# React Native Modal and Drawer

> An accessible React Native modal for iOS, Android and the web: centered on a wide screen and full screen on a phone, with sizes, a pinned header and footer around a scrolling body, a close button, nested modals, focus trap and return focus, Escape, backdrop press and scroll lock. Drawer slides a side panel in from either edge. Built on Dialog, shadcn-style parts. Use it as one element with props, or compose the parts.

# Modal and Drawer

A window for rich content: an edit form, a detail view, media, a multi-step flow. On a wide screen it's a centered card with a size you pick; on a phone it fills the screen, as phone apps show rich content, with the header and footer pinned around a body that scrolls. `Drawer` is the same window as a full-height panel sliding in from the side.

Both are built on [`Dialog`](./dialog): the same state, focus handling and ways to close. Use **Dialog** for a short message or form, **AlertDialog** to confirm, and **Modal** for anything that needs room.

```tsx
import { Modal, ModalBody, ModalClose, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalTitle, ModalTrigger } from 'patine-ui';
```

The quickest way: give `Modal` (or `Drawer`) a `trigger`, a `title`, a `description` and `actions`, and it draws the parts itself. Its children are the scrolling body. `size` and `fullScreen` (Modal) or `side` and `size` (Drawer) set the panel.

```tsx live
import { Text, View } from 'react-native';
import { Button, Drawer, Modal } from 'patine-ui';

export default function Example() {
  return (
    <View style={{ flexDirection: 'row', gap: 8 }}>
      <Modal
        trigger={<Button>Edit profile</Button>}
        title="Edit profile"
        description="Changes show on your public page."
        actions={[{ label: 'Cancel', variant: 'outline' }, { label: 'Save', onPress: () => {} }]}
      >
        <Text>Your form goes here.</Text>
      </Modal>
      <Drawer trigger={<Button variant="outline">Filters</Button>} title="Filters" side="start">
        <Text>Your filters go here.</Text>
      </Drawer>
    </View>
  );
}
```

## Compose the parts

For full control, leave those props out and compose the parts, as in shadcn/ui.

```tsx live
import { Button, Modal, ModalBody, ModalClose, ModalContent, ModalDescription, ModalFooter, ModalHeader, ModalTitle, ModalTrigger, TextField, TextArea } from 'patine-ui';

export default function Example() {
  return (
    <Modal>
      <ModalTrigger>
        <Button>New event</Button>
      </ModalTrigger>
      <ModalContent>
        <ModalHeader>
          <ModalTitle>New event</ModalTitle>
          <ModalDescription>It shows on everyone's calendar.</ModalDescription>
        </ModalHeader>
        <ModalBody>
          <TextField label="Title" placeholder="Team sync" />
          <TextField label="Where" placeholder="Room 4 or a link" />
          <TextArea label="Notes" placeholder="Agenda, links…" />
        </ModalBody>
        <ModalFooter>
          <ModalClose>
            <Button variant="outline">Cancel</Button>
          </ModalClose>
          <ModalClose>
            <Button>Create</Button>
          </ModalClose>
        </ModalFooter>
      </ModalContent>
    </Modal>
  );
}
```

## Example: edit a shipping address

A checkout's address card: Edit opens a modal with the form, Save writes it back to the card and closes, and Cancel leaves the card as it was.

```tsx live
import { useState } from 'react';
import { Box, Button, HStack, Modal, Text, TextField, VStack } from 'patine-ui';

const START = { name: 'Maya Cohen', street: 'Prinsengracht 263', city: 'Amsterdam', postcode: '1016 GV' };

export default function Example() {
  const [address, setAddress] = useState(START);
  const [draft, setDraft] = useState(START);
  const [open, setOpen] = useState(false);
  const field = (key: keyof typeof START) => ({ value: draft[key], onChangeText: (text: string) => setDraft({ ...draft, [key]: text }) });
  return (
    <Box border radius="lg" padding="md" style={{ width: '100%', maxWidth: 400 }}>
      <HStack justify="space-between" align="flex-start">
        <VStack gap="xs">
          <Text weight="semibold">Ship to</Text>
          <Text>{address.name}</Text>
          <Text color="textSecondary">{address.street}</Text>
          <Text color="textSecondary">
            {address.postcode} {address.city}
          </Text>
        </VStack>
        <Button
          size="sm"
          variant="outline"
          onPress={() => {
            setDraft(address);
            setOpen(true);
          }}
        >
          Edit
        </Button>
      </HStack>
      <Modal
        open={open}
        onOpenChange={setOpen}
        title="Shipping address"
        description="We deliver Monday to Saturday."
        actions={[
          { label: 'Cancel', variant: 'outline' },
          { label: 'Save', onPress: () => setAddress(draft) },
        ]}
      >
        <VStack gap="sm">
          <TextField label="Full name" {...field('name')} />
          <TextField label="Street and number" {...field('street')} />
          <HStack gap="sm">
            <TextField label="Postcode" {...field('postcode')} style={{ flex: 1 }} />
            <TextField label="City" {...field('city')} style={{ flex: 2 }} />
          </HStack>
        </VStack>
      </Modal>
    </Box>
  );
}
```

## Sizes and full screen

`size` caps a centered modal's width: `'sm'` 400, `'md'` 520 (the default), `'lg'` 720, `'xl'` 960. `'full'` always fills the screen. On a screen narrower than 600pt every size but `'sm'` fills the screen; `fullScreen` decides either way.

```tsx
<ModalContent size="lg">…</ModalContent>              // centered up to 720 wide; full screen on a phone
<ModalContent size="sm">…</ModalContent>              // a small centered card, even on a phone
<ModalContent fullScreen={false}>…</ModalContent>     // never full screen
```

## Nested modals

Open a modal from inside another. Each one stacks on top, Escape and the backdrop close only the top one, and focus goes back to what opened it.

```tsx live
import { Button, Modal, ModalBody, ModalClose, ModalContent, ModalFooter, ModalHeader, ModalTitle, ModalTrigger, Text } from 'patine-ui';

export default function Example() {
  return (
    <Modal>
      <ModalTrigger>
        <Button variant="outline">Order details</Button>
      </ModalTrigger>
      <ModalContent size="lg">
        <ModalHeader>
          <ModalTitle>Order #1042</ModalTitle>
        </ModalHeader>
        <ModalBody>
          <Text>2 × Linen shirt, 1 × Canvas tote. Paid with Visa •• 4242.</Text>
        </ModalBody>
        <ModalFooter>
          <Modal>
            <ModalTrigger>
              <Button variant="destructive">Cancel order</Button>
            </ModalTrigger>
            <ModalContent size="sm">
              <ModalHeader>
                <ModalTitle>Cancel this order?</ModalTitle>
              </ModalHeader>
              <ModalBody>
                <Text color="textSecondary">You'll get a full refund in 3–5 days.</Text>
              </ModalBody>
              <ModalFooter>
                <ModalClose>
                  <Button>Keep order</Button>
                </ModalClose>
              </ModalFooter>
            </ModalContent>
          </Modal>
        </ModalFooter>
      </ModalContent>
    </Modal>
  );
}
```

## Drawer

A full-height side panel: navigation, filters, a detail pane. `side` is the edge it slides in from, in the reading direction (`'start'` is the left in English and the right in Hebrew or Arabic); `size` its width (`'sm'` 320, `'md'` 400, `'lg'` 560, at most 85% of the screen, or `'full'`). It uses the same parts, named `Drawer…`.

```tsx live
import { Button, Drawer, DrawerBody, DrawerContent, DrawerHeader, DrawerTitle, DrawerTrigger, HStack, List, ListItem } from 'patine-ui';

export default function Example() {
  return (
    <HStack gap="sm">
      {['start', 'end'].map((side) => (
        <Drawer key={side}>
          <DrawerTrigger>
            <Button variant="outline">{side === 'start' ? 'Menu' : 'Filters'}</Button>
          </DrawerTrigger>
          <DrawerContent side={side}>
            <DrawerHeader>
              <DrawerTitle>{side === 'start' ? 'Menu' : 'Filters'}</DrawerTitle>
            </DrawerHeader>
            <DrawerBody>
              <List>
                <ListItem title="Inbox" onPress={() => {}} />
                <ListItem title="Starred" onPress={() => {}} />
                <ListItem title="Archive" onPress={() => {}} />
              </List>
            </DrawerBody>
          </DrawerContent>
        </Drawer>
      ))}
    </HStack>
  );
}
```

## Controlled

Like Dialog, it keeps its own state, or you control it with `open` and `onOpenChange`. `onOpenChange` fires for the user's changes only: the trigger, a `ModalClose`, the ✕, the backdrop, Escape or Android back.

```tsx
const [open, setOpen] = useState(false);
<Modal open={open} onOpenChange={setOpen}>…</Modal>
```

`dismissible={false}` keeps it open until your own button closes it; add `showCloseButton={false}` on the content to hide the ✕.

## Designs

- **Brand**: Patine's card on the `xl` shadow, growing in from 95%.
- **iOS**: a form sheet: a centered title, a gray round close button, and on a phone the whole screen rising in.
- **Material**: Material 3's dialog with 28dp corners and text buttons, and its full-screen dialog on phones. The drawer rounds its open edge, like the navigation drawer.
- **Web**: shadcn's modal, with dividers around a scrolling body.

The shadow comes from the theme's [shadow scale](../guides/theming#shadows-and-elevation).

## Accessibility

- The window is a `dialog`, modal, named by `ModalTitle` and described by `ModalDescription`.
- On the web, focus moves inside when it opens, Tab stays inside, Escape closes the top modal, and focus goes back to the trigger when it closes. The page behind doesn't scroll while it's open.
- On iOS, VoiceOver stays inside and the two-finger scrub closes it; on Android, back closes it.
- The close button is 44pt and labelled (`closeLabel`, default "Close").
- With the OS set to reduce motion it appears and disappears without moving.

## Props

### Modal and Drawer

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | — | Open, controlled. Pair with `onOpenChange`. |
| `defaultOpen` | `boolean` | `false` | Open at first, when uncontrolled. |
| `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 `ModalTitle`. |
| `description` | `ReactNode` | — | Shorthand: the `ModalDescription`. |
| `actions` | `DialogAction[]` | — | Shorthand: the footer's buttons, `{ label, onPress?, variant? }`. Each runs its `onPress`, then closes. |
| `size` | `ModalSize` | `'md'` (Drawer `'sm'`) | Shorthand: the panel's `size`. |
| `fullScreen` | `boolean` | — | Shorthand, Modal only: the panel's `fullScreen`. |
| `side` | `'start' \| 'end'` | `'end'` | Shorthand, Drawer only: the edge it slides in from. |
| `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. |
| `design` | `Design` | from `PatineProvider` | The look to follow. |

### ModalContent

Also takes React Native's `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` | Its widest: 400, 520, 720, 960, or the full screen. |
| `fullScreen` | `boolean` | below 600pt wide, all sizes but `'sm'` | Fill the screen. |
| `showCloseButton` | `boolean` | `true` | The ✕ in the top corner. |
| `closeLabel` | `string` | `'Close'` | The close button's label for screen readers. |

### DrawerContent

Also takes React Native's `View` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `side` | `'start' \| 'end'` | `'end'` | The edge it slides in from, in the reading direction. |
| `size` | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'sm'` | Its width: 320, 400, 560, 720 (at most 85% of the screen), or the full screen. |
| `showCloseButton` | `boolean` | `true` | The ✕ in the top corner. |
| `closeLabel` | `string` | `'Close'` | The close button's label. |

### The other parts

| Part | What it is |
| --- | --- |
| `ModalTrigger` / `DrawerTrigger` | Opens it when its one child, such as a Button, is pressed. |
| `ModalClose` / `DrawerClose` | Closes it when its one child is pressed. |
| `ModalHeader` / `DrawerHeader` | The title and description, clear of the ✕. |
| `ModalTitle` / `DrawerTitle` | A heading that names the window. |
| `ModalDescription` / `DrawerDescription` | Secondary text that describes it. |
| `ModalBody` / `DrawerBody` | The content; a `ScrollView` that scrolls when tall. |
| `ModalFooter` / `DrawerFooter` | Actions in a row at the end. |

The `Dialog` parts (`DialogTitle`, `DialogClose`…) also work inside a Modal.
