Modal

Modal appears on top of the main content and moves the system into a special mode requiring user interaction. It blocks interaction with the main content until an action is taken.

Modal dialogs are often triggered by an action a user took, and should be used to inform, confirm or complete a task. Content behind a modal dialog is inert, meaning that users cannot interact with it.

Import

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

Examples

Use Modal:

  • to request information critical for a user to continue their current process
  • to warn users about a potentially destructive action they are taking

Don't use Modal:

  • for nonessential information that is not related to the current user flow
  • for interrupting high-stake processes such as checkout flows

Basic

Changing sizes

There are 4 different sizes for modals: small, medium, large, fullWidth, and fullscreen. Pick a size based on the amount of content you have to present in them.

You can also pass an arbitary width in pixels, but we recommend to choose of the predefined values.

Choosing a fullWidth modal

As a rule of thumb, fullWidth modals shouldn’t be used frequently. Use them modals specially to present imagery or when you need to present a layout with columns in it. Never use fullWidth modals for a single column layout as the length of the line will affect readability.

Setting initial focus

When the modal opens, focus is automatically set to the close button, but you have the possibility to set an initial focus to a specific element of your modal dialog.

Either by using the initialFocusRef prop:

... or by setting the autoFocus attribute to an interactive element, such as an input or button:

Using Modal.Controls

Using Modal.Controls is optional and you may have a modal without control buttons. When you have control buttons, follow the following rules:

  • always use Button component with size="small"
  • your primary action button should be aligned to the right
  • there should be only one primary action
  • ideally, 1 secondary button should be enough when paired with a primary one. It’s allowed, however, to add a second one for another action.

Using ModalLauncher

When you want to open a modal from a function (outside of React component code), use ModalLauncher.

Props (API reference)

Open in Storybook

Name

Type

Default

children
required
ReactNode | RenderModal

isShown
required
false
true

When true, the dialog is shown.

onClose
required
(event: MouseEvent<Element, MouseEvent> | KeyboardEvent<Element>) => void

Function that will be run when the modal is requested to be closed, prior to actually closing.

allowHeightOverflow
false
true

Are modals higher than viewport allowed

false
aria
Aria

Additional aria attributes

className
string

CSS class to be appended to the root element

initialFocusRef
RefObject<HTMLElement>

Optional property to set initial focus

modalContentProps
Partial<ModalContentProps>

Optional props to override ModalContent behaviour

modalHeaderProps
Partial<ModalHeaderProps>

Optional props to override ModalHeader behaviour

onAfterOpen
OnAfterOpenCallback

Function that will be run after the modal has opened.

overlayProps
Pick<CommonProps, "className" | "style">

Optional props to override overlay behaviour

position
"center"
"top"

Indicating if modal is centered or linked to the top

center
shouldCloseOnEscapePress
false
true

Boolean indicating if pressing the esc key should close the overlay.

true
shouldCloseOnOverlayClick
false
true

Boolean indicating if clicking the overlay should close the overlay.

true
size
string
number

Size of the modal window

medium
subtitle
string

Modal subtitle that is used in header

testId
string

A [data-test-id] attribute used for testing purposes

cf-ui-modal
title
string

Modal title that is used in header

topOffset
string
number

Top offset if position is 'top'

50px

Content guidelines

For general guidelines around content and how to better write copy, consult this UX writing page . Find below a few suggestions on how to elaborate good content for modals:

Titles

Make them brief and easily inteligible, following this structure: verb + noun

✅ Do:

  • Create content type
  • Delete entry?
  • Add to release

❌ Don't:

  • Do you want to add this page to your release?
  • Permanently delete this entry?
  • Are you sure you want to delete this entry?

Body

The body is the main content of a modal. Therefore, try not to get chatty and keep it to the information that is necessary for users to accomplish their tasks. For more guidance on how to write good content for a modal, refer to this UX writing document.

Buttons label

A good way to think about buttons labels is to mentalize what users will be thinking when pressing the button. Actions should be clear and have a verb + noun structure that describes the action.

Buttons in modals should be short and sweet and shouldn’t require a lot of effort from users to understand what’s going to happen.

As a rule of thumb, users shouldn’t feel unclear of the outcomes of clicking on a specific button.

✅ Do: Add field, Remove page, Create content type, Add page to release

❌ Don't: Discard, New page, New content type, Go, Add

Avoid vague actions such as Remove (without saying what’s going to be removed) or Add.

Another scenario to avoid is to create lengthy buttons and with more that one action being described.

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.
  • By default, clicking on the overlay closes the modal.
  • By default, pressing Esc closes the modal.
  • Scrolling is blocked on the elements behind the modal.