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. 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.
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 that runs its onPress, then closes.
<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: () => {} }]} />
Try the props
design<Dialog open={open} onOpenChange={setOpen}>
…
</Dialog>
Anatomy
A dialog is a trigger and a card of parts. Each part is optional except DialogContent:
<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.
<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>
Dialogholds the state. Every other part goes inside it.DialogTriggerwraps one pressable element, such as aButton, and opens the dialog when it's pressed. The child's ownonPressstill runs.DialogContentis the window: a card centered over a dimmed backdrop.DialogHeaderholdsDialogTitleandDialogDescription. The title names the dialog for screen readers and the description describes it.DialogFooterholds the buttons: in a row at the end, or in the iOS design as full-width cells split by hairlines.DialogClosewraps 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.
<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="[email protected]" 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.
<> <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.
<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.
<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:
<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
Name the action in the button. People answer the question without reading it twice.
Don't answer with Yes and No. The buttons don't say what happens.
Keep it to one decision. A title, a sentence and up to two buttons.
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, 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. |
DialogDescription
| Prop | Type | Default | Description |
|---|---|---|---|
size, weight, font, color, theme, design | The props of Text. |
Right to left and custom styles work the same on every component: see Internationalization and right to left and Styling.
For AI
Give this page to an assistant as Markdown, with Copy page at the top, or the whole API in llms-full.txt.
With the Patine MCP server, it asks for get_component_docs({ name: "Dialog" })