Modal

Description

Modal is the root component for Drawer and Dialog. If one of these satisfy your needs, you probably want to use those rather than directly using Modal. It is possible to implement other modal variants using mode="custom". The new Modal is backward compatible with the previous Modal version using mode="dialog" (default) or mode="drawer". The old documentation for Modal can be viewed in Previous Modal (v1).

NB! Modal dialogs interrupt users and demand an action. They are appropriate when the user’s attention needs to be directed toward important information.

Behavior

The modal can be triggered from either a button or by using the open_state property. Triggering a modal will activate the opaque overlay and display the contents.

Help button

As the Modal is very often used in combination with other components and often as an enhancement of contextual content, it comes with a trigger button (HelpButton) with a question mark icon by default. You can for sure disable that behavior by using omitTriggerButton={true}.

You can also used the broadly available suffix property, like so:

<Input
  label="Input"
  placeholder="Placeholder ..."
  suffix={<HelpButton>Help text</HelpButton>}
/>

Accessibility

In order to make modals accessible, a lot of things are considered.

Entering a Modal (all variants) will:

Set focus on the heading or close button.
Enable escape key listener.
Invalidate every DOM element outside of the Modal / Drawer, so they are not accessible to keyboard and screen reader users. For doing that, there is a helper function to be used in your application as well.
Disable the body scroll possibility.
Make the Modal / Drawer scrollable if needed.
Dim the body / background with an overlay

Structure and content

Typically an opaque cover over the main content (fullscreen) and a small centered box containing information and interactive elements (buttons, forms etc.)

What is it

Modal dialogs appear on top of the main content changing the mode of the system into a special mode requiring user interaction. The main content is disabled until the user interacts with the modal dialog.

Disadvantages of Modal

They require immediate attention
They interrupt users
They cause users to forget what they were doing
They add extra goals - reading, interacting, and closing the Modal
They block the content in the background

Guidelines

Use for important warnings as a way to prevent or correct critical errors.
Do not use for unessential information that is not related to the user's current workflow.
Use for requesting the user to enter information critical to the current process.

Nested modals

While it is possible to nest a Modal within another Modal, you as a developer have to ensure the Browsers back-button (alongside the URL path), does take care of the nested Modal situation. Because a user should still be able to use the back button as expected and return to the last visited "page".

Root Element

NB: If the wrapper is not set manually, a wrapper is inserted automatically as a child node to the body.

To make sure the HTML structure is decoupled from all the page content, you can optionally define a wrapper div like <div class="dnb-modal-root" />.

Just place this as a sibling of your app root HTML element. This ensures that we always can stack the modal content above the App Content.

<body>
  <div id="app" />
  <div id="dnb-modal-root" />
</body>

Z-index

The Modal component is using 3000 as the z-index.

:root {
  --modal-z-index: 3000;
}

data-dnb-modal-active

When a Modal / Drawer is open, it will set an HTML attribute on the main HTML Element called data-dnb-modal-active. The attribute value will be the ID of the current Modal / Drawer.

This can be used to handle z-index issues from within CSS only:

html[data-dnb-modal-active='MODAL-ID'] {
  /* Your css */
}

Demos

The following examples are to demonstrate the functionality of Modal. Please go to Drawer demos or Dialog demos for complete component demos.

Mode custom

Use mode="custom" in the Modal component to create other components with overlay.

<Modal mode="custom">
  <ExampleCard>
    <P>
      This is a Modal mode that you can use to make custom variations
    </P>
  </ExampleCard>
</Modal>

<Modal mode="custom">
  <ExampleCard>
    <P>
      This is a Modal mode that you can use to make custom variations
    </P>
  </ExampleCard>
</Modal>

Open Modal by the state only

Use a custom trigger button and state handling by setting omitTriggerButton to Modal.

const Component = () => {
  const [modalIsActive, setModalState] = React.useState(false)
  return (
    <>
      <Button
        id="custom-triggerer"
        text="Custom trigger Button"
        on_click={() => setModalState((s) => !s)}
      />
      <Modal
        title="Modal Title"
        omit_trigger_button
        open_state={modalIsActive}
        labelled_by="custom-triggerer"
        on_close={() => setModalState(false)}
        mode="custom"
      >
        <ExampleCard>
          <P>This Modal was opened by a custom trigger button.</P>
          </ExampleCard>
      </Modal>
    </>
  )
}
render(<Component />)

const Component = () => {
  const [modalIsActive, setModalState] = React.useState(false)
  return (
    <>
      <Button
        id="custom-triggerer"
        text="Custom trigger Button"
        on_click={() => setModalState((s) => !s)}
      />
      <Modal
        title="Modal Title"
        omit_trigger_button
        open_state={modalIsActive}
        labelled_by="custom-triggerer"
        on_close={() => setModalState(false)}
        mode="custom"
      >
        <ExampleCard>
          <P>This Modal was opened by a custom trigger button.</P>
          </ExampleCard>
      </Modal>
    </>
  )
}
render(<Component />)

Close Modal by handlers

Use the close_modal prop to set another close handler, like a timeout for when the modal should close.

<Modal
  title="Auto close"
  trigger_text="Click me"
  align_content="center"
  max_width="40rem"
  close_modal={close => {
    const timeout = setTimeout(close, 3e3)
    return () => clearTimeout(timeout) 
  }}
  mode="custom"
>
  <ExampleCard>
    <P>This Modal will close in 3 seconds.</P>
  </ExampleCard>
</Modal>

<Modal
  title="Auto close"
  trigger_text="Click me"
  align_content="center"
  max_width="40rem"
  close_modal={close => {
    const timeout = setTimeout(close, 3e3)
    return () => clearTimeout(timeout) 
  }}
  mode="custom"
>
  <ExampleCard>
    <P>This Modal will close in 3 seconds.</P>
  </ExampleCard>
</Modal>

#Modal

#Description

#Behavior

#Help button

#Accessibility

#Structure and content

#What is it

#Disadvantages of Modal

#Guidelines

#Nested modals

#Root Element

#Z-index

#data-dnb-modal-active

#Demos

#Mode custom

#Open Modal by the state only

#Close Modal by handlers