This is version 4 beta of Forma 36Go back to last stable version 3
Forma 36

Modal

Modal dialogs interrupt a user by isolating information that needs to be acted upon. They are often triggered by an action a user took, and should be used to inform, confirm or complete a task.

Table of contents

How to use Modal

  • Use modal dialogs to request information critical for a user to continue their current process
  • Use modal dialogs to warn users about a potentially destructive action they are taking
  • Use modal dialogs consistently across use cases
  • Do not use modal dialogs for nonessential information that is not related to the current user flow
  • Avoid modal dialogs that interrupt high-stake processes such as checkout flows

Import

import { Modal } from '@contentful/f36-components';
// or
import { Modal } from '@contentful/f36-modal';

Code examples

The Modal component can be configured in a number of different ways. Use this guidance to determine when to use certain variations:

Basic example

Content recommendations

  • Practice progressive disclosure. Eliminate extra details to keep copy concise and actionable
  • Focus on the objective of the modal dialog. Start each sentence with the objective when possible
  • To enable users to navigate quickly, write concise sentences that are easy to understand at a glance
  • Limit the number of concepts in each sentence. Write simple sentences for all audiences
  • To keep UX copy actionable use present tense for user interactions
  • Avoid “never,” “always” and other absolutes
  • Use contractions when possible
  • Avoid exclamation marks

Accessibility

  • When the modal opens, focus is trapped within it.
  • When the modal opens, focus is automatically set to the close button, or the element from initialFocusRef.
  • When the modal closes, focus returns to the element that was focused before the modal activated, or the element from finalFocusRef.
  • Clicking on the overlay closes the Modal.
  • Pressing Esc closes the Modal.
  • Scrolling is blocked on the elements behind the modal.

Props

NameRequiredDefaultTypeDescription
isShownrequired
false
true
When true, the dialog is shown.
onCloserequired(event: MouseEvent<Element, MouseEvent> | KeyboardEvent<Element>) => voidFunction that will be run when the modal is requested to be closed, prior to actually closing.
allowHeightOverflowfalse
false
true
Are modals higher than viewport allowed
ariaAriaAdditional aria attributes
initialFocusRefRefObject<HTMLElement>Optional property to set initial focus
modalContentPropsPartial<ModalContentProps>Optional props to override ModalContent behaviour
modalHeaderPropsPartial<ModalHeaderProps>Optional props to override ModalHeader behaviour
onAfterOpenOnAfterOpenCallbackFunction that will be run after the modal has opened.
positioncenter
"center"
"top"
Indicating if modal is centered or linked to the top
shouldCloseOnEscapePresstrue
false
true
Boolean indicating if pressing the esc key should close the overlay.
shouldCloseOnOverlayClicktrue
false
true
Boolean indicating if clicking the overlay should close the overlay.
sizemedium
string
number
Size of the modal window
titlestringModal title that is used in header
topOffset50px
string
number
Top offset if position is 'top'
childrenrequiredReactNode | RenderModal
classNamestringCSS class to be appended to the root element
styleCSSPropertiesAccepts a JavaScript object with camelCased properties rather than a CSS string
testIdcf-ui-modalstringA [data-test-id] attribute used for testing purposes