Skip to main content

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: 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.

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.

Behaves like
Loading…
<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.

Behaves like
Loading…
<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>

Try the props​

Behaves like
Props
size
fullScreen
<Modal open={open} onOpenChange={setOpen}>
…
</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.

Behaves like
Loading…
<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.

<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.

Behaves like
Loading…
<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….

Behaves like
Loading…
<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.

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.

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​

PropTypeDefaultDescription
openboolean—Open, controlled. Pair with onOpenChange.
defaultOpenbooleanfalseOpen at first, when uncontrolled.
onOpenChange(open: boolean) => void—Called when the user opens or closes it.
triggerReactElement—Shorthand: one pressable, such as a Button, that opens it.
titleReactNode—Shorthand: the ModalTitle.
descriptionReactNode—Shorthand: the ModalDescription.
actionsDialogAction[]—Shorthand: the footer's buttons, { label, onPress?, variant? }. Each runs its onPress, then closes.
sizeModalSize'md' (Drawer 'sm')Shorthand: the panel's size.
fullScreenboolean—Shorthand, Modal only: the panel's fullScreen.
side'start' | 'end''end'Shorthand, Drawer only: the edge it slides in from.
childrenReactNode—The parts, or the body when you use the shorthand.
dismissiblebooleantrueCloses on the backdrop, Escape and Android back.
themeDeepPartial<Theme>—Theme override.
designDesignfrom PatineProviderThe look to follow.

ModalContent​

Also takes React Native's View props.

PropTypeDefaultDescription
size'sm' | 'md' | 'lg' | 'xl' | 'full''md'Its widest: 400, 520, 720, 960, or the full screen.
fullScreenbooleanbelow 600pt wide, all sizes but 'sm'Fill the screen.
showCloseButtonbooleantrueThe ✕ in the top corner.
closeLabelstring'Close'The close button's label for screen readers.

DrawerContent​

Also takes React Native's View props.

PropTypeDefaultDescription
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.
showCloseButtonbooleantrueThe ✕ in the top corner.
closeLabelstring'Close'The close button's label.

The other parts​

PartWhat it is
ModalTrigger / DrawerTriggerOpens it when its one child, such as a Button, is pressed.
ModalClose / DrawerCloseCloses it when its one child is pressed.
ModalHeader / DrawerHeaderThe title and description, clear of the ✕.
ModalTitle / DrawerTitleA heading that names the window.
ModalDescription / DrawerDescriptionSecondary text that describes it.
ModalBody / DrawerBodyThe content; a ScrollView that scrolls when tall.
ModalFooter / DrawerFooterActions in a row at the end.

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