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.
<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.
<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
sizefullScreen<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.
<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.
<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….
<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
xlshadow, 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 byModalTitleand described byModalDescription. - 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.