#Modal

#Import

import { Modal } from '@dnb/eufemia'

#Description

Modal is the root component for Drawer and Dialog. If one of these satisfies your needs, use them instead of directly using Modal. The Modal component allows you to implement other modal variants beyond what we currently provide (Drawer and Dialog).

Note: Modal dialogs interrupt users and demand action. They're appropriate when the user's attention needs to be directed toward important information.

#Relevant links

• Source code
• Docs code

#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

Since Modal is often used with other components and frequently enhances contextual content, it includes a trigger button (HelpButton) with a question mark icon by default. You can disable this behavior with omitTriggerButton={true}.

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

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

#Accessibility

Modals implement many accessibility considerations.

Entering a Modal (all variants) will:

1. Set focus on the heading or close button
2. Enable escape key listener
3. Make every DOM element outside the Modal/Drawer inaccessible to keyboard and screen reader users. A helper function is available for use in your application
4. Disable body scrolling
5. Make the Modal/Drawer scrollable if needed
6. 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

1. They require immediate attention
2. They interrupt users
3. They cause users to forget what they were doing
4. They add extra goals: reading, interacting, and closing the Modal
5. They block the content in the background

#Guidelines

1. Use for important warnings to prevent or correct critical errors
2. Do not use for nonessential information unrelated to the user's current workflow
3. Use for requesting user input critical to the current process

#Nested modals

While it is possible to nest a Modal within another Modal, you as a developer must ensure the browser's back button (alongside the URL path) handles the nested Modal situation. A user should still be able to use the back button as expected and return to the last visited "page".

#Root Element (React Portal)

The Modal component uses PortalRoot internally to render its content. See the PortalRoot documentation for information on how to control where the portal content appears in the DOM.

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

#Example

<Modal>
  <ExampleCard>
    <P>This is a Modal 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)}
      >
        <ExampleCard>
          <P>This Modal was opened by a custom trigger button.</P>
        </ExampleCard>
      </Modal>
    </>
  )
}
render(<Component />)

#Close Modal by handlers

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

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