Dialog

View on GitHub

Introduction

The Dialog component is used to show content on top of an overlay. It blocks any interaction with the page — until the overlay is clicked, or a close action is triggered.

When to use

When you require your user to interact with you app and don’t want your users to jump to a different page and break their workflow.

You should also use a dialog in cases where you need to ask for confirmation from the user before doing a lengthy or dangerous action. This could be a deletion of some sorts or initiating a lengthy download.

Terminology

BlueprintJS pointed out in their documentation that “modal” is a misnomer for “dialog”.

The term “modal” is sometimes used to mean “dialog”, but this is a misnomer. Modal is an adjective that describes parts of a UI. An element is considered modal if it blocks interaction with the rest of the application. We use the term “dialog” to avoid confusion with the adjective.

Focus Management

When opening a Dialog, focus will be brought inside the Dialog When using both the cancel and confirm button, the cancel button will get focus first.

When closing the Dialog, focus will be brought back to the element that was focused before opening the Dialog. This is normally the button that triggered the Dialog.

Default dialog example

The `Component` component is not part of Evergreen. It is only used in examples to create state. Learn more.
<Component initialState={{ isShown: false }}>
  {({ state, setState }) => (
    <Pane>
      <Dialog
        isShown={state.isShown}
        title="Dialog title"
        onCloseComplete={() => setState({ isShown: false })}
        confirmLabel="Custom Label"
      >
        Dialog content
      </Dialog>

      <Button onClick={() => setState({ isShown: true })}>Show Dialog</Button>
    </Pane>
  )}
</Component>
code Hide code

Default with a danger intent

The intent prop determines the appearance of the confirm button, danger is red.

The `Component` component is not part of Evergreen. It is only used in examples to create state. Learn more.
<Component initialState={{ isShown: false }}>
  {({ state, setState }) => (
    <Pane>
      <Dialog
        isShown={state.isShown}
        title="Danger intent"
        intent="danger"
        onCloseComplete={() => setState({ isShown: false })}
        confirmLabel="Delete Something"
      >
        Dialog content
      </Dialog>

      <Button onClick={() => setState({ isShown: true })}>Show Dialog</Button>
    </Pane>
  )}
</Component>
code Hide code

Confirm button with loading confirmation

The `Component` component is not part of Evergreen. It is only used in examples to create state. Learn more.
<Component
  initialState={{ isShown: false, isLoading: false }}
  didUpdate={({ state, setState }) => {
    if (state.isLoading === true) {
      window.setTimeout(() => {
        setState({
          isShown: false
        })
      }, 2000)
    }
  }}
>
  {({ state, setState }) => (
    <Pane>
      <Dialog
        isShown={state.isShown}
        title="Loading confirmation"
        onCloseComplete={() => setState({ isShown: false, isLoading: false })}
        isConfirmLoading={state.isLoading}
        onConfirm={() => setState({ isLoading: true })}
        confirmLabel={state.isLoading ? 'Loading...' : 'Confirm Loading'}
      >
        Dialog content
      </Dialog>

      <Button onClick={() => setState({ isShown: true })}>Show Dialog</Button>
    </Pane>
  )}
</Component>
code Hide code

Internal scrolling

When content makes the dialog height greater than the available space in the viewport, the content area will become scrollable It will add a symmetric offset on the top and bottom — based on the topOffset prop.

The `Component` component is not part of Evergreen. It is only used in examples to create state. Learn more.
<Component initialState={{ isShown: false }}>
  {({ state, setState }) => (
    <Pane>
      <Dialog
        isShown={state.isShown}
        title="Internal scrolling"
        onCloseComplete={() => setState({ isShown: false })}
      >
        <Pane height={1800} width="100%" backgroundColor="#ddd" />
      </Dialog>

      <Button onClick={() => setState({ isShown: true })}>Show Dialog</Button>
    </Pane>
  )}
</Component>
code Hide code

Self managed close

The `Component` component is not part of Evergreen. It is only used in examples to create state. Learn more.
<Component initialState={{ isShown: false }}>
  {({ state, setState }) => (
    <Pane>
      <Dialog
        isShown={state.isShown}
        title="Self managed close"
        onCloseComplete={() => setState({ isShown: false })}
      >
        {({ close }) => (
          <Pane>
            <Paragraph>Manage your own buttons and close interaction</Paragraph>
            <Button marginTop={16} onClick={close}>
              Self Managed Close
            </Button>
          </Pane>
        )}
      </Dialog>

      <Button onClick={() => setState({ isShown: true })}>Show Dialog</Button>
    </Pane>
  )}
</Component>
code Hide code

Remove default footer

Use the hasFooter prop to show or hide the footer. This will hide the confirm and cancel buttons.

The `Component` component is not part of Evergreen. It is only used in examples to create state. Learn more.
<Component initialState={{ isShown: false }}>
  {({ state, setState }) => (
    <Pane>
      <Dialog
        isShown={state.isShown}
        title="No footer"
        onCloseComplete={() => setState({ isShown: false })}
        hasFooter={false}
      >
        No footer
      </Dialog>

      <Button onClick={() => setState({ isShown: true })}>Show Dialog</Button>
    </Pane>
  )}
</Component>
code Hide code

Remove default header

Use the hasHeader prop to show or hide the header. This will hide both the close icon button as the title.

The `Component` component is not part of Evergreen. It is only used in examples to create state. Learn more.
<Component initialState={{ isShown: false }}>
  {({ state, setState }) => (
    <Pane>
      <Dialog
        isShown={state.isShown}
        onCloseComplete={() => setState({ isShown: false })}
        hasHeader={false}
      >
        No header
      </Dialog>

      <Button onClick={() => setState({ isShown: true })}>Show Dialog</Button>
    </Pane>
  )}
</Component>
code Hide code

Remove default footer and header

Use the hasFooter, hasHeader props to show or hide the footer and header.

The `Component` component is not part of Evergreen. It is only used in examples to create state. Learn more.
<Component initialState={{ isShown: false }}>
  {({ state, setState }) => (
    <Pane>
      <Dialog
        isShown={state.isShown}      
        onCloseComplete={() => setState({ isShown: false })}
        hasFooter={false}
        hasHeader={false}
      >
        Completely custom dialog
      </Dialog>

      <Button onClick={() => setState({ isShown: true })}>Show Dialog</Button>
    </Pane>
  )}
</Component>
code Hide code

Dialog Props

childrenunionrequired
Children can be a string, node or a function accepting `({ close })`. When passing a string, <Paragraph /> is used to wrap the string.
intentenum = 'none'
The intent of the Dialog. Used for the button.
isShownbool = false
When true, the dialog is shown.
titlenode
Title of the Dialog. Titles should use Title Case.
hasHeaderbool = true
When true, the header with the title and close icon button is shown.
hasFooterbool = true
When true, the footer with the cancel and confirm button is shown.
hasCancelbool = true
When true, the cancel button is shown.
onCloseCompletefunc
Function that will be called when the exit transition is complete.
onOpenCompletefunc
Function that will be called when the enter transition is complete.
onConfirmfunc = close => close()
Function that will be called when the confirm button is clicked. This does not close the Dialog. A close function will be passed as a paramater you can use to close the dialog. `onConfirm={(close) => close()}`
confirmLabelstring = 'Confirm'
Label of the confirm button.
isConfirmLoadingbool = false
When true, the confirm button is set to loading.
isConfirmDisabledbool = false
When true, the confirm button is set to disabled.
onCancelfunc = close => close()
Function that will be called when the cancel button is clicked. This closes the Dialog by default. `onCancel={(close) => close()}`
cancelLabelstring = 'Cancel'
Label of the cancel button.
shouldCloseOnOverlayClickbool = true
Boolean indicating if clicking the overlay should close the overlay.
shouldCloseOnEscapePressbool = true
Boolean indicating if pressing the esc key should close the overlay.
widthunion = 560
Width of the Dialog.
topOffsetunion = '12vmin'
The space above the dialog. This offset is also used at the bottom when there is not enough vertical space available on screen — and the dialog scrolls internally.
sideOffsetunion = '16px'
The space on the left/right sides of the dialog when there isn't enough horizontal space available on screen.
minHeightContentunion = 80
The min height of the body content. Makes it less weird when only showing little content.
containerPropsobject
Props that are passed to the dialog container.