Dialog

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

Page navigation navigation

React

readyNot 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	Default	Description
title		`React.ReactNode` Title of the Dialog. Also serves as the aria-label for this Dialog.
subtitle		`React.ReactNode` The Dialog's subtitle. Optional. Rendered below the title in smaller type with less contrast. Also serves as the aria-describedby for this Dialog.
renderHeader		`React.FunctionComponent<React.PropsWithChildren<DialogHeaderProps>>` Provide a custom renderer for the dialog header. This content is rendered directly into the dialog body area, full bleed from edge to edge, top to the start of the body element. Warning: using a custom renderer may violate Primer UX principles.
renderBody		`React.FunctionComponent<React.PropsWithChildren<DialogProps>>` Provide a custom render function for the dialog body. This content is rendered directly into the dialog body area, full bleed from edge to edge, header to footer. Warning: using a custom renderer may violate Primer UX principles.
renderFooter		`React.FunctionComponent<React.PropsWithChildren<DialogProps>>` Provide a custom render function for the dialog footer. This content is rendered directly into the dialog footer area, full bleed from edge to edge, end of the body element to bottom. Warning: using a custom renderer may violate Primer UX principles.
footerButtons		`DialogButtonProps[]` Specifies the buttons to be rendered in the Dialog footer.
onClose		`(gesture: 'close-button' \| 'escape') => void` This method is invoked when a gesture to close the dialog is used (either an Escape key press or clicking the 'X' in the top-right corner). The gesture argument indicates the gesture that was used to close the dialog (either 'close-button' or 'escape').
role		`'dialog' \| 'alertdialog'` The ARIA role to assign to this dialog. @see https://www.w3.org/TR/wai-aria-practices-1.1/#dialog_modal @see https://www.w3.org/TR/wai-aria-practices-1.1/#alertdialog
width		`'small' \| 'medium' \| 'large' \| 'xlarge'` The width of the dialog. small: 296px medium: 320px large: 480px xlarge: 640px
height		`'small' \| 'large' \| 'auto'` The height of the dialog. small: 296x480 large: 480x640 auto: variable based on contents
returnFocusRef		`React.RefObject<HTMLElement>`
initialFocusRef		`React.RefObject<HTMLElement>` Focus this element when the Dialog opens
position		`'center' \| 'left' \| 'right' \| { narrow: 'center' \| 'left' \| 'right' \| 'bottom' \| 'fullscreen', regular: 'center' \| 'left' \| 'right' \| 'bottom' \| 'fullscreen', wide: 'center' \| 'left' \| 'right' \| 'bottom' \| 'fullscreen' }` The position of the dialog
className		`string \| undefined` CSS string

Dialog.Body

No props documented

Dialog.Buttons

Name	Default	Description
buttons Required		`DialogButtonProps[] (see table below)`

Dialog.CloseButton

Name	Default	Description
onClose Required		`() => void` Callback for closing the Dialog

No props documented

Dialog.Title

No props documented

DialogButtonProps

Name	Default	Description
buttonType		`'default' \| 'danger' \| 'primary' \| 'normal'` The variant of Button to use
content Required		`React.ReactNode` The Button's inner text
autoFocus		`boolean` If true, and if this is the only button with autoFocus set to true, focus this button automatically when the dialog appears.
ref		`React.RefObject<HTMLButtonElement>` A reference to the rendered Button’s DOM node, used together with `autoFocus` for `focusTrap`’s `initialFocus`.

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.Body

Dialog.Buttons

Dialog.CloseButton

Dialog.Footer

Dialog.Header

Dialog.Title

DialogButtonProps