Dialog

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

Page navigation navigation

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

Loading data for dialog_v2...