Forma 36 - 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.

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

Import

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

Example

Basic


function ModalBasicExample() {
  const [isShown, setShown] = useState(false);
  const [contentTypeName, setContentTypeName] = useState('');
  return (
    <>
      <Button onClick={() => setShown(true)}>Create new content type</Button>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        isShown={isShown}
      >
        {() => (
          <>
            <Modal.Header
              title="Create new content type"
              onClose={() => setShown(false)}
            />
            <Modal.Content>
              <FormControl>
                <FormControl.Label isRequired>Name</FormControl.Label>
                <TextInput
                  maxLength={20}
                  value={contentTypeName}
                  placeholder="For example Product, Blog Post, Author"
                  onChange={(e) => {
                    setContentTypeName(e.target.value);
                  }}
                />
              </FormControl>
            </Modal.Content>
            <Modal.Controls>
              <Button
                size="small"
                variant="transparent"
                onClick={() => setShown(false)}
              >
                Close
              </Button>
              <Button
                size="small"
                variant="positive"
                isDisabled={contentTypeName.length === 0}
                onClick={() => {
                  alert('Created: ' + contentTypeName);
                  setContentTypeName('');
                  setShown(false);
                }}
              >
                Create
              </Button>
            </Modal.Controls>
          </>
        )}
      </Modal>
    </>
  );
}function ModalBasicExample() {
  const [isShown, setShown] = useState(false);
  const [contentTypeName, setContentTypeName] = useState('');
  return (
    <>
      <Button onClick={() => setShown(true)}>Create new content type</Button>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        isShown={isShown}
      >
        {() => (
          <>
            <Modal.Header
              title="Create new content type"
              onClose={() => setShown(false)}
            />
            <Modal.Content>
              <FormControl>
                <FormControl.Label isRequired>Name</FormControl.Label>
                <TextInput
                  maxLength={20}
                  value={contentTypeName}
                  placeholder="For example Product, Blog Post, Author"
                  onChange={(e) => {
                    setContentTypeName(e.target.value);
                  }}
                />
              </FormControl>
            </Modal.Content>
            <Modal.Controls>
              <Button
                size="small"
                variant="transparent"
                onClick={() => setShown(false)}
              >
                Close
              </Button>
              <Button
                size="small"
                variant="positive"
                isDisabled={contentTypeName.length === 0}
                onClick={() => {
                  alert('Created: ' + contentTypeName);
                  setContentTypeName('');
                  setShown(false);
                }}
              >
                Create
              </Button>
            </Modal.Controls>
          </>
        )}
      </Modal>
    </>
  );
}

Changing sizes

There are 4 different sizes for modals: small, medium, large, fullWidth. 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.


function ModalSizesExample() {
  const [isShown, setShown] = useState(false);
  const [size, setSize] = useState('medium');
  return (
    <>
      <Form>
        <FormControl>
          <FormControl.Label>Select a width</FormControl.Label>
          <Select
            onChange={(e) => {
              setSize(e.target.value);
            }}
            value={size}
          >
            <Select.Option value="small">small</Select.Option>
            <Select.Option value="medium">medium</Select.Option>
            <Select.Option value="large">large</Select.Option>
            <Select.Option value="fullWidth">full width</Select.Option>
            <Select.Option value="333px">
              333px (specific width value)
            </Select.Option>
          </Select>
        </FormControl>
        <Button
          onClick={() => {
            setShown(true);
          }}
        >
          Click to open a modal
        </Button>
      </Form>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        isShown={isShown}
        size={size}
      >
        {() => (
          <>
            <Modal.Header
              title="A modal with a specific size"
              onClose={() => setShown(false)}
            />
            <Modal.Content>
              <Text>
                My size is <strong>{size}</strong>
              </Text>
            </Modal.Content>
            <Modal.Controls>
              <Button
                variant="transparent"
                size="small"
                onClick={() => setShown(false)}
              >
                Close
              </Button>
              <Button
                variant="positive"
                size="small"
                onClick={() => setShown(false)}
              >
                Confirm
              </Button>
            </Modal.Controls>
          </>
        )}
      </Modal>
    </>
  );
}function ModalSizesExample() {
  const [isShown, setShown] = useState(false);
  const [size, setSize] = useState('medium');
  return (
    <>
      <Form>
        <FormControl>
          <FormControl.Label>Select a width</FormControl.Label>
          <Select
            onChange={(e) => {
              setSize(e.target.value);
            }}
            value={size}
          >
            <Select.Option value="small">small</Select.Option>
            <Select.Option value="medium">medium</Select.Option>
            <Select.Option value="large">large</Select.Option>
            <Select.Option value="fullWidth">full width</Select.Option>
            <Select.Option value="333px">
              333px (specific width value)
            </Select.Option>
          </Select>
        </FormControl>
        <Button
          onClick={() => {
            setShown(true);
          }}
        >
          Click to open a modal
        </Button>
      </Form>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        isShown={isShown}
        size={size}
      >
        {() => (
          <>
            <Modal.Header
              title="A modal with a specific size"
              onClose={() => setShown(false)}
            />
            <Modal.Content>
              <Text>
                My size is <strong>{size}</strong>
              </Text>
            </Modal.Content>
            <Modal.Controls>
              <Button
                variant="transparent"
                size="small"
                onClick={() => setShown(false)}
              >
                Close
              </Button>
              <Button
                variant="positive"
                size="small"
                onClick={() => setShown(false)}
              >
                Confirm
              </Button>
            </Modal.Controls>
          </>
        )}
      </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 a possibility to set an initial focus to a specific element of your modal dialog.


function ModalInitialFocusExample() {
  const [isShown, setShown] = useState(false);
  const [contentTypeName, setContentTypeName] = useState('');
  const inputRef = useRef();
  return (
    <>
      <Button onClick={() => setShown(true)}>Create new content type</Button>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        isShown={isShown}
        initialFocusRef={inputRef}
      >
        {() => (
          <>
            <Modal.Header
              title="Create new content type"
              onClose={() => setShown(false)}
            />
            <Modal.Content>
              <FormControl>
                <FormControl.Label isRequired>Name</FormControl.Label>
                <TextInput
                  ref={inputRef}
                  maxLength={20}
                  value={contentTypeName}
                  placeholder="For example Product, Blog Post, Author"
                  onChange={(e) => {
                    setContentTypeName(e.target.value);
                  }}
                />
              </FormControl>
            </Modal.Content>
          </>
        )}
      </Modal>
    </>
  );
}function ModalInitialFocusExample() {
  const [isShown, setShown] = useState(false);
  const [contentTypeName, setContentTypeName] = useState('');
  const inputRef = useRef();
  return (
    <>
      <Button onClick={() => setShown(true)}>Create new content type</Button>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        isShown={isShown}
        initialFocusRef={inputRef}
      >
        {() => (
          <>
            <Modal.Header
              title="Create new content type"
              onClose={() => setShown(false)}
            />
            <Modal.Content>
              <FormControl>
                <FormControl.Label isRequired>Name</FormControl.Label>
                <TextInput
                  ref={inputRef}
                  maxLength={20}
                  value={contentTypeName}
                  placeholder="For example Product, Blog Post, Author"
                  onChange={(e) => {
                    setContentTypeName(e.target.value);
                  }}
                />
              </FormControl>
            </Modal.Content>
          </>
        )}
      </Modal>
    </>
  );
}

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
children(required)
ReactNode | RenderModal
Name
isShown(required)
Description
When true, the dialog is shown.
false
true
Name
onClose(required)
Description
Function that will be run when the modal is requested to be closed, prior to actually closing.
(event: MouseEvent<Element, MouseEvent> | KeyboardEvent<Element>) => void
Name
allowHeightOverflow
Description
Are modals higher than viewport allowed
false
true
Default
false
Name
aria
Description
Additional aria attributes
Aria
Name
className
Description
CSS class to be appended to the root element
string
Name
initialFocusRef
Description
Optional property to set initial focus
RefObject<HTMLElement>
Name
modalContentProps
Description
Optional props to override ModalContent behaviour
Partial<ModalContentProps>
Name
modalHeaderProps
Description
Optional props to override ModalHeader behaviour
Partial<ModalHeaderProps>
Name
onAfterOpen
Description
Function that will be run after the modal has opened.
OnAfterOpenCallback
Name
position
Description
Indicating if modal is centered or linked to the top
"center"
"top"
Default
center
Name
shouldCloseOnEscapePress
Description
Boolean indicating if pressing the esc key should close the overlay.
false
true
Default
true
Name
shouldCloseOnOverlayClick
Description
Boolean indicating if clicking the overlay should close the overlay.
false
true
Default
true
Name
size
Description
Size of the modal window
string
number
Default
medium
Name
testId
Description
A [data-test-id] attribute used for testing purposes
string
Default
cf-ui-modal
Name
title
Description
Modal title that is used in header
string
Name
topOffset
Description
Top offset if position is 'top'
string
number
Default
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.

Import

Example

Basic

Changing sizes

Choosing a fullWidth modal

Setting initial focus

Using Modal.Controls

Using ModalLauncher

Props (API reference)

children(required)

isShown(required)

onClose(required)

allowHeightOverflow

aria

className

initialFocusRef

modalContentProps

modalHeaderProps

onAfterOpen

position

shouldCloseOnEscapePress

shouldCloseOnOverlayClick

size

testId

title

topOffset

Content guidelines

Titles

Body

Buttons label

Accessibility

Help improve this page