A Modal is a dialog window that can contain alerts, confirmation requests, workflows, long content, or images. While active, it prevents users from interacting with the rest of the page.

• Modal opens when the user clicks a button or link, or when a system event occurs (like the user leaving the page).
• Modal appears above a darkened overlay or scrim that blocks the content below. This reduces visual clutter and focuses user attention.
• To interact with the Modal, the user reads its contents (this can be done using the Tab key) and/or completes a workflow.
• To close the Modal, the user clicks the primary button (usually OK or Done).
• In some cases, the user can click the Close icon in the upper right corner, click a button like Cancel or Back in the footer, press Esc, or click outside the Modal to close it.

• For alerts (like errors or warnings) or a potentially hazardous situation (like a drug interaction)
• To ask users to confirm that they want to take a destructive or permanent action (like deleting data)
• To ask users to complete a workflow, without displaying a new page
• To show videos or enlarged images on the page

• For long workflows where user input will be lost if Modal is closed (use a separate web page instead)
• Repeatedly in the same workflow or on the same page

Modal is great for displaying important information that users must acknowledge or letting users complete short workflows without having to go to a new page, but it’s also very disruptive, so use it sparingly. Avoid workflows that use Modal repeatedly.

For workflows that present more complex data but need to keep users on the page, consider using the left-panel. Static, reference information should be presented on the left and areas with user action should be displayed on the right.

Modal is available in two styles:

• Simple: contains short alert text that is used to convey important information or prompt user action with a primary call to action button
  • Simple style Modals can have optional alert coloring with an attention bar/alert icon. Also, footer buttons will be center aligned.
• Complex: contains long forms, media, or lengthy custom content and uses a primary call to action button to complete workflows and return users to the page.
  • For complex style Modals, buttons will be right aligned.

Modal has 4 width options:

• Small: 440px wide
• Medium (default): 600px wide
• Large: 800px wide
• Full: 90% of the width of the browser window

Height can be manually selected or calculated automatically based on the contents.

Please note: Left panel is only available for Large and Full widths to ensure the panel is readable.

Colors and emphasis

Modal has optional alert styling which is available in several color types:

• Default (Non Alert) Colors:
  • Default (gray) is the recommended color for non specific alert style Modals, such as reminders.
• Alert (Semantic) Colors: 
  • Info (purple) is for uses like "disclaimer" or "insight".
  • New (teal) is for uses like "new".
  • Success (green) is for uses like “Completed” and “Approved".
  • Attention (yellow) is for uses like “Warning" and “Issue Detected".
  • Critical (red) is for uses like “At Risk”. This color is reserved for the highest risk and most severe issues, like patient safety matters.

Modal is centered horizontally and vertically on the page, floating above both the page content and the scrim or overlay.

Header

This is the title of the dialog and the first content users see, so it should indicate why the Modal appeared. Use title case for header text (e.g., “Edit Details”).

For short alerts, the header can be the only copy in a Modal (for instance, “Delete this file?” followed by OK and Cancel buttons). In this scenario, use sentence case for the header text.

When using Modal for a short workflow or other user action, header text should reflect the action, not the content. For example:

• Button or link label: “Add questions from library”
• Lightbox header: “Add Questions from Library”, not “Question Library”

The header can also include up to 2 icon-only Buttons. These don’t have labels, so they should represent actions that are clear from just the icon itself (like the Print icon or the Email icon). Don’t use these icon-only Buttons to complete the workflow or close the window. If you use these buttons, test your layout on the smallest screen size your use case supports.

You can also set a secondary header for the left panel. The left panel header should give more insight into the data inside the left panel body, and should not be the primary header.  

Body

This is the dialog content or workflow. It can contain a range of content, including short alerts, images, forms, and long copy. Modal has different size options to fit varied content needs, but it’s still best to keep the content clear and concise. Avoid content that requires scrolling.

When using the left panel, the right-side body should focus on user actions while the left body should provide supporting information. Any interactive elements should be solely in the right-side body. 

Please note: Modal contains top and bottom padding to separate body content from the header and footer, please remove extra padding from your body content where applicable.

Footer

By default, the footer contains a single primary call to action button. Start button text with a verb, and use title case (e.g., “Save Changes”). Any additional buttons should be secondary or tertiary. The footer is optional but recommended.

The footer is styled in two different formats based on the style of content contained in the Modal:

• Simple: Modal only contains short alert text that is used to convey important information or prompt user action with a primary call to action button. For alert style Modals buttons will be center aligned.
• Complex: Modal contains long forms, media, or lengthy custom content and uses a primary call to action button to complete workflows and return users to the page. For workflow/media/custom style Modals buttons will be right aligned.

For help writing error messages and confirmation dialogs, see Content.

Content

'contentStyle' defaults to "simple". Modal content can have three styles: "Simple", "Complex", and "Complex with Left Panel". The left panel from the legacy Lightbox component is only allowed when the content style is set to "complex".

Both "simple" and "complex" content styles also have preset width, height, and alignment to make it look like a legacy Modal or Lightbox.

Please note: Modal contains top and bottom padding to separate body content from the header and footer, please remove extra padding from your body content where applicable.

Auto Focus

Options for autoFocusTarget include the close icon, header buttons, primary button, secondary buttons or no auto-focus. By default, 'autoFocusTarget' is set to 'none', an option we believe is suitable for many use cases. If you choose to set an auto-focus target, it should be based on the Modal's content:

1. Simple Modals: For short Modals that primarily display alert text without any interactive buttons, it is recommended to place the auto-focus target on the close button. This allows users to easily dismiss the Modal and return to the main screen.
2. Complex Modals: In cases where the Modal contains lengthy content, we recommend placing the auto-focus target on the primary button. This ensures that users can quickly engage with the Modal's interactive elements and proceed with the intended workflow.

Footer

Modal now accepts "footerSecondaryButtons" and "footerTertiaryButtons" as an array of buttons, allowing multiple secondary and tertiary buttons.

'includeButtonRow' By default, "includeButtonRow" is set to true, and a primary button will be displayed in the footer section.

z-index

Modal's grey background has a z-index of 1000. If there is other content in the same iframe that is in front of the grey background, then add a className to the Modal, and use that className to set a higher z-index

Implementation links

Modal directory in Bitbucket

Implementation details

It is strongly recommended to familiarize yourself with the Forge source code. While this documentation is a best effort to document the intent and usage of a component, sometimes some features only become clear when looking at the source code. Also, looking at Forge's source code may help identify and fix bugs in either your application or Forge itself.

Storybook files

Forge maintains at least one storybook file per component. While the primary audience for these files is typically the Forge team, these storybook files may cover usages of the component not covered by a demo. The storybook for the latest version of forge can be found at go/forge-storybook.

Testing library

Forge strongly encourages using testing-library to write tests for your application.

"The more your tests resemble the way your software is used, the more confidence they can give you."

If you're having trouble testing a Forge component using testing-library, it would be a good idea to see how Forge tests its own components. For the most part, Forge tries to use screen.getByRole as much as it can, as that API provides the best feedback on a11y compliance. Forge discourages the use of document.querySelector and screen.getByTestId as both APIs encourage using implementation details to test your component, and discourage adding roles to your component.

With that being said, many of Forge's components were not built with accessibility in mind. These components do break the recommendations listed above.

In Nimbus applications

athenaOne serves the Forge bundle independently from your application's bundle. Importing Forge components directly from '@athena/forge' takes advantage of this feature.

import { Modal } from '@athena/forge'

In standalone applications

Importing components using the exact path to the module takes advantage of webpack's tree shaking feature. Webpack will include only that module and its dependencies.

import Modal from '@athena/forge/Modal';

To use this import guidance, Typescript applications must use typescript >= 4.7.3, and should add this setting to their tsconfig.json file:

{
  "compilerOptions": {
    "moduleResolution": "Node16",
  }
}

If this setting doesn't work for your application, use this import statement instead:

import Modal from '@athena/forge/dist/Modal';