Dialog

Dialog is a floating surface used to display transient content such as confirmation actions, selection options, and more.

Page navigation navigation

React

deprecatedNot reviewed for a11y

Storybook|Source

Rails

readyReviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

React examples

Default

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'


export default function Default() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog title="My Dialog" onClose={onDialogClose} returnFocusRef={buttonRef}>
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'

export default function Default() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog title="My Dialog" onClose={onDialogClose} returnFocusRef={buttonRef}>
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

With subtitle

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'


export default function Default() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog
          title="My Dialog"
          subtitle="This subtitle adds additional context"
          onClose={onDialogClose}
          returnFocusRef={buttonRef}
        >
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'

export default function Default() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog
          title="My Dialog"
          subtitle="This subtitle adds additional context"
          onClose={onDialogClose}
          returnFocusRef={buttonRef}
        >
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'


export default function FooterButtons() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog
          title="My Dialog"
          onClose={onDialogClose}
          footerButtons={[
            {buttonType: 'default', content: 'Cancel', onClick: onDialogClose},
            {buttonType: 'danger', content: 'Delete the universe'},
            {
              buttonType: 'primary',
              content: 'Continue',
              onClick: () => {
                alert('Continuing')
              },
            },
          ]}
          returnFocusRef={buttonRef}
        >
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'

export default function FooterButtons() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog
          title="My Dialog"
          onClose={onDialogClose}
          footerButtons={[
            {buttonType: 'default', content: 'Cancel', onClick: onDialogClose},
            {buttonType: 'danger', content: 'Delete the universe'},
            {
              buttonType: 'primary',
              content: 'Continue',
              onClick: () => {
                alert('Continuing')
              },
            },
          ]}
          returnFocusRef={buttonRef}
        >
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

Side sheet (right)

Regular viewport Dialog placement guidelines

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'


export default function SideSheet() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog title="My Dialog" onClose={onDialogClose} position="right" returnFocusRef={buttonRef}>
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'

export default function SideSheet() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog title="My Dialog" onClose={onDialogClose} position="right" returnFocusRef={buttonRef}>
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

Responsive positioning: bottom-sheet in narrow viewports

Narrow viewport Dialog placement guidelines

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'


export default function ResponsiveBottom() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog
          title="My Dialog"
          onClose={onDialogClose}
          position={{narrow: 'bottom', regular: 'center'}}
          returnFocusRef={buttonRef}
        >
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'

export default function ResponsiveBottom() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog
          title="My Dialog"
          onClose={onDialogClose}
          position={{narrow: 'bottom', regular: 'center'}}
          returnFocusRef={buttonRef}
        >
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

Height and width size variant

Small: The small size variant is used for Dialogs with very little content.
Medium (default): Used for most tasks such as completing a form or selecting an option from a list.
Large: Large Dialogs are suitable for content that requires more horizontal space for the body compared to size medium, such as a comment box.
Extra large: Before using an extra large Dialog, consider whether or not the content would be more appropriate for a new page.

By default the Dialog height will adjust to the height of the body content. If the maximum height is reached, the body contents will scroll.

This example uses the 'small' height and width variant.

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'


export default function Size() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog title="My Dialog" onClose={onDialogClose} width="small" height="small" returnFocusRef={buttonRef}>
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

import React from 'react'
import {Button} from '@primer/react'
import {Dialog} from '@primer/react/experimental'

export default function Size() {
  const [isOpen, setIsOpen] = React.useState(false)
  const buttonRef = React.useRef<HTMLButtonElement>(null)
  const onDialogClose = React.useCallback(() => setIsOpen(false), [])
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(!isOpen)}>
        Show dialog
      </Button>
      {isOpen && (
        <Dialog title="My Dialog" onClose={onDialogClose} width="small" height="small" returnFocusRef={buttonRef}>
          This is where the dialog content would go.
        </Dialog>
      )}
    </>
  )
}

More code examples

See the Dialog Storybook stories

Props

Dialog

Name	Required	Description
isOpen		`boolean` Whether or not the dialog is open
onDismiss		`() => void` Function that will be called when the dialog is closed
returnFocusRef		`React.RefObject<HTMLElement>` The element to restore focus back to after the `Dialog` is closed
initialFocusRef		`React.RefObject<HTMLElement>` Element inside of the `Dialog` you'd like to be focused when the Dialog is opened. If nothing is passed to `initialFocusRef` the close button is focused.
aria-labelledby		`string` Pass an id to use for the aria-label. Use either a `aria-label` or an `aria-labelledby` but not both.
aria-label		`string` Pass a label to be used to describe the Dialog. Use either a `aria-label` or an `aria-labelledby` but not both.
narrow		`boolean`
wide		`boolean`
sx		`SystemStyleObject`

Name	Required	Description
sx		`SystemStyleObject`

Dialog

Page navigation navigation

React examples

Default

With subtitle

With footer buttons

Side sheet (right)

Responsive positioning: bottom-sheet in narrow viewports

Height and width size variant

More code examples

Props

Dialog

Dialog.Header