Skip to main content

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.

Import
import { Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle, DialogTrigger } from 'patine-ui';
Subpath
patine-ui/dialog
Source
GitHubMarkdown for LLMs
Runs on
iOSAndroidWebFree · MIT

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.

Loading…
<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​

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.

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

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

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

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

Loading…
<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:

Loading…
<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​

Delete “Q3 roadmap”?
Do

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

Are you sure?
Don’t

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

Turn on backups?
Photos are saved every night.
Do

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

Edit profile
Name · Email · Phone · Address · Bio · Links · Photo…
Don’t

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

Accessibility​

Behaviour
Roledialog with aria-modal, labelled by DialogTitle and described by DialogDescription. Without a title, give DialogContent an aria-label.
AnnouncedDialogTrigger 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 targetThe buttons you pass keep their 44pt targets; the backdrop closes it unless dismissible={false}.
Reduce motionWith reduce motion on, it appears and disappears without animating.
  • iOS's escape gesture closes it.

API​

Dialog​

PropTypeDefaultDescription
openboolean—Open, when you control it.
defaultOpenbooleanfalseOpen at first, when it keeps its own state.
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 DialogTitle.
descriptionReactNode—Shorthand: the DialogDescription.
actionsDialogAction[]—Shorthand: the footer's buttons, { label, onPress?, variant?, ...ButtonProps }. Each runs its onPress, then closes.
childrenReactNode—The parts, or the body when you use the shorthand.
dismissiblebooleantrueCloses on the backdrop, Escape and Android back.
themeDeepPartial<Theme>—Theme override, for every part.
design'brand' | 'ios' | 'material' | 'web' | 'native'from PatineProviderThe look to follow: brand, iOS, Material or web, or 'native' for the platform's own.

DialogTrigger and DialogClose​

PropTypeDefaultDescription
childrenReactElementRequiredOne pressable element, such as a Button.

DialogContent​

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

PropTypeDefaultDescription
childrenReactNode—The header, body and footer.

DialogHeader and DialogFooter​

Take React Native's View props.

PropTypeDefaultDescription
childrenReactNode—The title and description, or the buttons.

DialogTitle​

level defaults to 2.

PropTypeDefaultDescription
level, size, weight, font, color, theme, designThe props of Heading.

DialogDescription​

PropTypeDefaultDescription
size, weight, font, color, theme, designThe 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" })