Pharos
JSTOR's Design System
 Getting started Help FAQs DocumentationDevelopment GitHub JSTOR LogosTypographyColorImageryIconographyElevationVoice and toneJSTOR termsWeb elementsGrammar and styleEditing checklistAlertButtonBreadcrumbCheckboxCheckbox groupCoach MarkComboboxDropdown menuDropdown menu navFooterHeaderHeadingIconImage cardInput groupLayoutLinkLoading spinnerModalMultiselect dropdownPaginationPillPopoverProgress barRadio buttonRadio groupSelectSheetSidenavSliderSwitchTableTabsToastTooltipText inputTextareaToggle button groupOverviewAlias colorsGlobal colorsFont familyFont sizeFont weightLine heightElevationRadiusSpacingTransitionsType scaleType styles
Skip to main navigation
Modal
Modals are overlays that present a user with focused information and actions that sit on top of a page's content. They are used for getting a user's attention and for taking action without changing page context.
Example
Open modal

I am a modal

CancelOk

See live code examples in Storybook
Usage Overview

Modals are used to present critical information or request user input needed to complete a task. Modals are meant to purposely interrupt a user's workflow and should be used sparingly to limit disruption to the user experience.

Modals are used for quick tasks that put a user into a specific "mode," like editing, deleting, and citing, or displaying specific, focused information like a data table.

When to Use
  • When a user needs to do a focused task (e.g., enter specific information)
  • When a user needs to go through a workflow with multiple steps (e.g., "Create a report")
  • To confirm a user wants to take an action (e.g., deleting information)
  • To display pertinent, quick information
  • To display promotional or product marketing (e.g., "Welcome to workspace")
Best practices
Dos
  • Allow users to take an action to complete a task in their workflow
  • Display critical information to give users more context
  • When using form elements in a modal, it's recommended to validate the user's data before submission (inline validation)
Don'ts
  • Don't use for long forms, instead, incorporate into the page's content
Content guidelines Modal heading

A modal's heading should be concise, describing the information or action being presented. They should be written in sentence case and describe the action a user will take (e.g., "Delete folder," "Create report," or "Cite") or relevant information to the copy being displayed. Punctuation is generally not needed or encouraged in modal headings.

Modal content

There are no specific requirements for the content of a modal; it can be composed as the information calls for. The content could include supporting body copy or form elements.

Modal footer

The footer content contains all possible actions for the user to take, but can also include further pertinent/relevant information. For buttons, use descriptive words such as "Add," and Save.

States No footer

Use for information-only based content that does not require the user to take an action.

Mobile

For screen sizes smaller than our Tablet (768px) down to our Mobile size (320px), the modal will act as a "sheet" and take over the entire width and height of the screen.

Variants Small

Use for quick, short information. The small modal size should also be used to confirm delete actions.

Medium (Default)

Medium is our default modal size. It can be used in most instances.

Large

For displaying more complex information, such as data tables, use the large modal for maximum screen real-estate.

Accessibility Relevant WCAG guidelines
  • 1.3.1 Info and Relationships A
Importance

Modals should not open automatically as this can interrupt a users workflow. By giving the user control when they would like to view this modal, this gives them the freedom to decide when they would like to be given the additional information in the overlay.

Code expectations

Via w3 :

  • When the modal is open, only interactable elements and content should be able to be accessed. No element behind the modal overlay should be in the tab index or accessible to screen readers for as long as the modal is visible. We can achieve this by using a focus trap.
  • Div has a role of "dialog"
  • Div also has aria-labelledby="id" to give an accessible name. It will point to the element that provides the dialog title.
    • The title or purpose of the element should contain the "id" that is being referenced by the aria-labelledby
  • Div has aria-modal="true"
  • An aria-label should be placed on the "X" that contains "close modal"
Expected actions Screen reader
  • Reads: "first element in focus, dialog"
    • The most important thing is that the screen reader says that it is a "dialog"
  • *Note: there should also be an aria-label on the "X" that reads "close modal, button"
Keyboard
  • Tab: moves focus within the modal
  • Shift + Tab: moves focus to the previous element in the tab order
  • Esc: closes the modal