Modal

stable

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.

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


function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  return (
    <React.Fragment>
      <Button onClick={() => setShown(true)}>Show centered modal</Button>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        title="Centered modal"
        isShown={isShown}
      >
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button
                size="small"
                variant="transparent"
                onClick={() => setShown(false)}
              >
                Close
              </Button>
              <Button
                size="small"
                variant="positive"
                onClick={() => setShown(false)}
              >
                Confirm
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  return (
    <React.Fragment>
      <Button onClick={() => setShown(true)}>Show centered modal</Button>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        title="Centered modal"
        isShown={isShown}
      >
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button
                size="small"
                variant="transparent"
                onClick={() => setShown(false)}
              >
                Close
              </Button>
              <Button
                size="small"
                variant="positive"
                onClick={() => setShown(false)}
              >
                Confirm
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}


function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  const [position, setPosition] = React.useState('top');
  return (
    <React.Fragment>
      <Form>
        <Button
          variant="positive"
          onClick={() => {
            setPosition('top');
            setShown(true);
          }}
        >
          Show top modal
        </Button>
        <Button
          onClick={() => {
            setPosition('center');
            setShown(true);
          }}
        >
          Show center modal
        </Button>
      </Form>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        title="Centered modal"
        isShown={isShown}
        position={position}
      >
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button variant="transparent" onClick={() => setShown(false)}>
                Close
              </Button>
              <Button variant="positive" onClick={() => setShown(false)}>
                Confirm
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  const [position, setPosition] = React.useState('top');
  return (
    <React.Fragment>
      <Form>
        <Button
          variant="positive"
          onClick={() => {
            setPosition('top');
            setShown(true);
          }}
        >
          Show top modal
        </Button>
        <Button
          onClick={() => {
            setPosition('center');
            setShown(true);
          }}
        >
          Show center modal
        </Button>
      </Form>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        title="Centered modal"
        isShown={isShown}
        position={position}
      >
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button variant="transparent" onClick={() => setShown(false)}>
                Close
              </Button>
              <Button variant="positive" onClick={() => setShown(false)}>
                Confirm
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}


function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  const [size, setSize] = React.useState('medium');
  return (
    <React.Fragment>
      <Form>
        <FormControl>
          <FormControl.Label>Select a width</FormControl.Label>
          <Select
            onChange={(e) => {
              setSize(e.target.value);
            }}
          >
            <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);
          }}
        >
          Show modal
        </Button>
      </Form>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        title="Centered modal"
        isShown={isShown}
        size={size}
      >
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button variant="transparent" onClick={() => setShown(false)}>
                Close
              </Button>
              <Button variant="positive" onClick={() => setShown(false)}>
                Confirm
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}function ModalExample() {
  const [isShown, setShown] = React.useState(false);
  const [size, setSize] = React.useState('medium');
  return (
    <React.Fragment>
      <Form>
        <FormControl>
          <FormControl.Label>Select a width</FormControl.Label>
          <Select
            onChange={(e) => {
              setSize(e.target.value);
            }}
          >
            <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);
          }}
        >
          Show modal
        </Button>
      </Form>
      <Modal
        onClose={() => setShown(false)}
        shouldCloseOnOverlayClick
        shouldCloseOnEscapePress
        title="Centered modal"
        isShown={isShown}
        size={size}
      >
        {() => (
          <React.Fragment>
            <Modal.Header title="Title" onClose={() => setShown(false)} />
            <Modal.Content>Hello from controlled modal window</Modal.Content>
            <Modal.Controls>
              <Button variant="transparent" onClick={() => setShown(false)}>
                Close
              </Button>
              <Button variant="positive" onClick={() => setShown(false)}>
                Confirm
              </Button>
            </Modal.Controls>
          </React.Fragment>
        )}
      </Modal>
    </React.Fragment>
  );
}

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

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

Help improve this page

Edit on Github Read the contribution guide

How to use Modal

Import

Code examples

Basic example

Modal position

Modal sizes

Content recommendations

Accessibility

Props

children(required)

isShown(required)

onClose(required)

allowHeightOverflow

aria

className

initialFocusRef

modalContentProps

modalHeaderProps

onAfterOpen

position

shouldCloseOnEscapePress

shouldCloseOnOverlayClick

size

testId

title

topOffset

Help improve this page