Dialog

Dialogs are windows containing contextual information, tasks, or workflows that appear over the user interface. Depending on the kind of Dialog, further interactions may be blocked until the Dialog is acknowledged.

size

isDismissible

isKeyboardDismissDisabled

import {Dialog, DialogTrigger, Button, ButtonGroup, Heading, Content, Footer, Checkbox, Image, Form, TextField} from '@react-spectrum/s2';
import heroImage from 'url:./assets/preview.png';

function Example(props) {
  return (
    <DialogTrigger>
      <Button variant="primary">Open Dialog</Button>
      <Dialog {...props}>
        {({close}) => (
          <>
            <Image slot="hero" src={heroImage} />
            <Heading slot="title">Subscribe to our newsletter</Heading>
            <Content>
              <p>Enter your information to subscribe to our newsletter and receive updates about new features and announcements.</p>
              <Form>
                <TextField label="Name" />
                <TextField label="Email" type="email" />
              </Form>
            </Content>
            <Footer>
              <Checkbox>Don't show this again</Checkbox>
            </Footer>
            <ButtonGroup>
              <Button onPress={close} variant="secondary">Cancel</Button>
              <Button onPress={close} variant="accent">Subscribe</Button>
            </ButtonGroup>
          </>
        )}
      </Dialog>
    </DialogTrigger>
  );
}

Content

Dialogs are windows containing contextual information, tasks, or workflows that appear over the user interface. Spectrum includes several pre-defined dialog components with layouts for specific use cases, or you can use CustomDialog to create a custom layout.

Standard Dialog

Use Dialog for standard dialog layouts. It supports Image, Heading, Header, Content, Footer, and ButtonGroup slots. Dismissible dialogs replace their ButtonGroup with a close button.

size

isDismissible

import {Dialog, DialogTrigger, Button, ButtonGroup, Heading, Header, Content, Footer, Checkbox, Image, Form, TextField} from '@react-spectrum/s2';
import heroImage from 'url:./assets/preview.png';

function Example(props) {
  return (
    <DialogTrigger>
      <Button variant="primary">Open Dialog</Button>
      <Dialog {...props}>
        {({close}) => (
          <>
            <Image slot="hero" src={heroImage} />
            <Heading slot="title">Dialog Title</Heading>
            <Header>Header</Header>
            <Content>
              <p>Standard dialog description. This should briefly communicate any additional information or context about the standard dialog title, to help users make one of the decisions offered by the buttons. Make it no more than a few short sentences.</p>
            </Content>
            <Footer>
              <Checkbox>Don't show this again</Checkbox>
            </Footer>
            <ButtonGroup>
              <Button onPress={close} variant="secondary">Cancel</Button>
              <Button onPress={close} variant="accent">Subscribe</Button>
            </ButtonGroup>
          </>
        )}
      </Dialog>
    </DialogTrigger>
  );
}

Alert Dialog

Use AlertDialog for confirmation, error messages, and other critical information that must be acknowledged.

title

children

variant

size

primaryActionLabel

secondaryActionLabel

cancelLabel

isPrimaryActionDisabled

isSecondaryActionDisabled

autoFocusButton

import {AlertDialog, DialogTrigger, Button} from '@react-spectrum/s2';

function Example(props) {
  return (
    <DialogTrigger>
      <Button>Publish</Button>
      <AlertDialog
        {...props}
        title="Publish Document"
        primaryActionLabel="Publish"
        secondaryActionLabel="Save Draft"
        cancelLabel="Cancel"
        onPrimaryAction={() => alert('onPrimaryAction')}
        onSecondaryAction={() => alert('onSecondaryAction')}>
        {props.children}
      </AlertDialog>
    </DialogTrigger>
  );
}

Fullscreen Dialog

Use FullscreenDialog for complex workflows that require more space. It supports Heading, Header, Content, and ButtonGroup slots.

variant

import {FullscreenDialog, DialogTrigger, Button, ButtonGroup, Heading, Header, Content} from '@react-spectrum/s2';

function Example(props) {
  return (
    <DialogTrigger>
      <Button variant="primary">Open Fullscreen</Button>
      <FullscreenDialog {...props}>
        {({close}) => (
          <>
            <Heading slot="title">Advanced Settings</Heading>
            <Header>Configure your application preferences</Header>
            <Content>
              <p>This fullscreen dialog provides ample space for complex forms, detailed content, or multi-step workflows.</p>
              <p>The content area can scroll if needed, making it perfect for lengthy forms or comprehensive settings panels.</p>
            </Content>
            <ButtonGroup>
              <Button onPress={close} variant="secondary">Cancel</Button>
              <Button onPress={close} variant="accent">Save Changes</Button>
            </ButtonGroup>
          </>
        )}
      </FullscreenDialog>
    </DialogTrigger>
  );
}

Custom Dialog

Use CustomDialog for complete control over the dialog layout.

size

padding

import {CustomDialog, DialogTrigger, Button, Heading, CloseButton} from '@react-spectrum/s2';
import Checkmark from '@react-spectrum/s2/illustrations/gradient/generic1/Checkmark';
import {style} from '@react-spectrum/s2/style' with {type: 'macro'};

function Example(props) {
  return (
    <DialogTrigger>
      <Button>Open dialog</Button>
      <CustomDialog {...props} size="M">
        <div className={style({display: 'flex', flexDirection: 'column', rowGap: 8, alignItems: 'center'})}>
          <Checkmark />
          <Heading slot="title" styles={style({font: 'heading-lg', textAlign: 'center', marginY: 0})}>Thank you!</Heading>
          <p className={style({font: 'body', textAlign: 'center', marginY: 0})}>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
          <CloseButton styles={style({position: 'absolute', top: 12, insetEnd: 12})} />
        </div>
      </CustomDialog>
    </DialogTrigger>
  );
}

Dialog Container

Use DialogContainer to show a dialog programmatically or mount in a different part of the JSX tree (e.g. outside a menu).

import {DialogContainer, Dialog, Button, ButtonGroup, Heading, Content, ActionMenu, MenuItem} from '@react-spectrum/s2';
import {useState} from 'react';

function DialogContainerExample() {
  let [dialogType, setDialogType] = useState(null);

  return (
    <>
      <ActionMenu onAction={setDialogType}>
        <MenuItem id="edit">Edit Item</MenuItem>
        <MenuItem id="delete">Delete Item</MenuItem>
        <MenuItem id="share">Share Item</MenuItem>
      </ActionMenu>
      
      <DialogContainer onDismiss={() => setDialogType(null)}>
        {dialogType === 'edit' && (
          <Dialog>
            {({close}) => (
              <>
                <Heading slot="title">Edit Item</Heading>
                <Content>Make changes to your item here.</Content>
                <ButtonGroup>
                  <Button onPress={close} variant="secondary">Cancel</Button>
                  <Button onPress={close} variant="accent">Save</Button>
                </ButtonGroup>
              </>
            )}
          </Dialog>
        )}
        {dialogType === 'delete' && (
          <Dialog>
            {({close}) => (
              <>
                <Heading slot="title">Delete Item</Heading>
                <Content>Are you sure you want to delete this item? This action cannot be undone.</Content>
                <ButtonGroup>
                  <Button onPress={close} variant="secondary">Cancel</Button>
                  <Button onPress={close} variant="negative">Delete</Button>
                </ButtonGroup>
              </>
            )}
          </Dialog>
        )}
        {dialogType === 'share' && (
          <Dialog>
            {({close}) => (
              <>
                <Heading slot="title">Share Item</Heading>
                <Content>Choose how you would like to share this item.</Content>
                <ButtonGroup>
                  <Button onPress={close} variant="secondary">Cancel</Button>
                  <Button onPress={close} variant="accent">Share</Button>
                </ButtonGroup>
              </>
            )}
          </Dialog>
        )}
      </DialogContainer>
    </>
  );
}

API

Dialog

<Dialog>
  <Image slot="hero">
  <Heading slot="title" />
  <Header />
  <Content />
  <Footer />
  <ButtonGroup />
</Dialog>

Name	Type	Default
`isDismissible`	`boolean`	Default: —
Whether the Dialog is dismissible.
`size`	`'S' \| 'M' \| 'L' \| 'XL'`	Default: `'M'`
The size of the Dialog.
`isKeyboardDismissDisabled`	`boolean`	Default: —
Whether pressing the escape key to close the dialog should be disabled.
`children`	`ReactNode \| (opts: DialogRenderProps) => ReactNode`	Default: —
Children of the dialog. A function may be provided to access a function to close the dialog.
`styles`	`StylesProp`	Default: —
Spectrum-defined styles, returned by the `style()` macro.

Render Prop
`close`

AlertDialog

Name	Type	Default
`variant`	`'confirmation' \| 'information' \| 'destructive' \| 'error' \| 'warning'`	Default: —
The visual style of the AlertDialog.
`title`	`string`	Default: —
The title of the AlertDialog.
`children`	`ReactNode`	Default: —
The contents of the AlertDialog.
`cancelLabel`	`string`	Default: —
The label to display within the cancel button.
`primaryActionLabel`	`string`	Default: —
The label to display within the confirm button.
`secondaryActionLabel`	`string`	Default: —
The label to display within the secondary button.
`isPrimaryActionDisabled`	`boolean`	Default: —
Whether the primary button is disabled.
`isSecondaryActionDisabled`	`boolean`	Default: —
Whether the secondary button is disabled.
`autoFocusButton`	`'cancel' \| 'primary' \| 'secondary'`	Default: —
Button to focus by default when the dialog opens.
`size`	`'S' \| 'M' \| 'L'`	Default: `'M'`
The size of the Dialog.

FullscreenDialog

<FullscreenDialog>
  <Heading slot="title" />
  <Header />
  <Content />
  <ButtonGroup />
</FullscreenDialog>

Name	Type	Default
`variant`	`'fullscreen' \| 'fullscreenTakeover'`	Default: `"fullscreen"`
The variant of fullscreen dialog to display.
`isKeyboardDismissDisabled`	`boolean`	Default: —
Whether pressing the escape key to close the dialog should be disabled.
`children`	`ReactNode \| (opts: DialogRenderProps) => ReactNode`	Default: —
Children of the dialog. A function may be provided to access a function to close the dialog.
`styles`	`StylesProp`	Default: —
Spectrum-defined styles, returned by the `style()` macro.

Render Prop
`close`

CustomDialog

Name	Type	Default
`size`	`'S' \| 'M' \| 'L' \| 'fullscreen' \| 'fullscreenTakeover'`	Default: —
The size of the Dialog.
`isDismissible`	`boolean`	Default: —
Whether the Dialog is dismissible.
`isKeyboardDismissDisabled`	`boolean`	Default: —
Whether pressing the escape key to close the dialog should be disabled.
`padding`	`'default' \| 'none'`	Default: `'default'`
The amount of padding around the contents of the dialog.
`children`	`ReactNode \| (opts: DialogRenderProps) => ReactNode`	Default: —
Children of the dialog. A function may be provided to access a function to close the dialog.
`styles`	`StylesProp`	Default: —
Spectrum-defined styles, returned by the `style()` macro.

Render Prop
`close`

DialogTrigger

<DialogTrigger>
  <Button />
  <Dialog />
</DialogTrigger>

Name	Type
`children`	`ReactNode`

DialogContainer

<DialogContainer>
  <Dialog />
</DialogContainer>

Name	Type
`children`	`ReactNode`
The Dialog to display, if any.