Modal

View source on GitHub

A Modal displays content that requires user interaction. Modals appear on a layer above the page and therefore block the content underneath, preventing users from interacting with anything else besides the Modal. The most common example of Modal is confirming an action the user has taken.

Props

Name	Type	Default
`accessibilityModalLabel` Required	`string`	-
	String that clients such as VoiceOver will read to describe the modal. Always localize the label. See Accessibility section for more info.
`onDismiss` Required	`() => void`	-
	Callback fired when Modal is dismissed by clicking on the backdrop outside of the Modal (if `closeOnOutsideClick` is true).
`align`	`"start" \| "center"`	`"center"`
	Specify the alignment of `heading` & `subHeading` strings. See the Heading variant for more info.
`children`	`React.Node`	-
	Supply the element(s) that will be used as Modal's main content. See the Best Practices for more info.
`closeOnOutsideClick`	`boolean`	`true`
	Close the modal when you click outside of it. See the outside click variant for more info.
`footer`	`React.Node`	-
	Supply the element(s) that will be used as Modal's custom footer. See the Best Practices for more info.
`heading`	`React.Node`	-
	The text used for Modal's heading. See the Heading variant for more info.
`role`	`"alertdialog" \| "dialog"`	`"dialog"`
	The underlying ARIA role for the Modal. See the Accessibility Role section for more info.
`size`	`"sm" \| "md" \| "lg" \| number`	`"sm"`
	Determines the width of the Modal. See the size variant for more info. sm: `540px` \| md: `720px` \| lg: `900px` \| number
`subHeading`	`string`	-
	Subtext for Modal, only renders with `heading` strings. See the sub-heading variant for more info.

Usage guidelines

When to Use

Interrupting users to get confirmation on a user-triggered action.
Requesting minimal amounts of information from a user (1-2 fields only).
Capturing user's full attention for something important.

When Not to Use

Any time a separate, designated URL is desired.
Requesting large forms of information. Consider a Sheet or new page instead.
Any action that should not interrupt users from their current work stream.
On top of another modal, since this can create usability issues and confusion.

Best practices

Use Modal when a response is required from the user. Clearly communicate what response is expected and make the action simple and straight forward, such as clicking a button to confirm. The most common responses will be related to confirming or canceling.

Limit the number of actions in a Modal. A primary and secondary action should be used for Modals. The rarely used tertiary actions are often destructive, such as “Delete”.

In the few cases where Modals are being used within the Pinner product, aim to prevent the content from needing to scroll at a reasonable screen size.

Don't

Use Modal for content that should have a dedicated surface, like login flows. Think about the core areas of your product that could appear in navigation. If a dedicated URL would be beneficial, use a full page instead. If the user interaction is an optional sub-task, consider using a Sheet.

Don't

Use Modal for long and complex tasks. Don’t keep the user in a Modal that takes multiple steps to exit. If multiple tasks are required, take the user to a separate page instead.

Don't

Add additional task-based Modals to the Pinner product. While these are currently used in some Pinner surfaces for editing, consider using a full page, Sheet, Flyout or inline editing for a better user experience.

Accessibility

Labels

We want to make sure Modals have a clear purpose when being read by a screen reader. accessibilityModalLabel allows us to update the spoken text for the heading prop and give it more context.

Edits made below will not be reflected in the example above, open the sandbox instead.

function AccessibilityExample(props) {
  const [showModal, setShowModal] = React.useState(false);

  const HEADER_ZINDEX = new FixedZIndex(10);
  const zIndex = new CompositeZIndex([HEADER_ZINDEX]);

  return (
    <Layer zIndex={zIndex}>
      <Modal
        accessibilityModalLabel="Delete board 60s Furniture"
        heading="Are you sure?"
        onDismiss={() => { setShowModal(!showModal) }}
        footer={
          <Flex justifyContent="end" gap={2}>
            <Button color="gray" text="Cancel"/>
            <Button color="red" text="Delete forever"/>
          </Flex>
        }
        size="sm"
      >
        <Box padding={8}>
          <Text align="center" size="lg">Once you delete a board and all its Pins, you can't undo it!</Text>
        </Box>
      </Modal>
    </Layer>
  );
}

function AccessibilityExample(props) {
  const [showModal, setShowModal] = React.useState(false);
  const HEADER_ZINDEX = new FixedZIndex(10);
  const zIndex = new CompositeZIndex([HEADER_ZINDEX]);
  return (
    <Layer zIndex={zIndex}>
      <Modal
        accessibilityModalLabel="Delete board 60s Furniture"
        heading="Are you sure?"
        onDismiss={() => { setShowModal(!showModal) }}
        footer={
          <Flex justifyContent="end" gap={2}>
            <Button color="gray" text="Cancel"/>
            <Button color="red" text="Delete forever"/>
          </Flex>
        }
        size="sm"
      >
        <Box padding={8}>
          <Text align="center" size="lg">Once you delete a board and all its Pins, you can't undo it!</Text>
        </Box>
      </Modal>
    </Layer>
  );
}

Role

Use the alertdialog role when the Modal requires the user’s immediate attention, such as an error or warning. For instance, navigating away from a page with active edits may trigger an alertdialog Modal that asks the user to confirm if they want to lose their changes. Learn more about the alertdialog role.

role="alertdialog"

Edits made below will not be reflected in the example above, open the sandbox instead.

function AlertDialogAccessibilityExample(props) {
  const [showModal, setShowModal] = React.useState(false);

  const HEADER_ZINDEX = new FixedZIndex(10);
  const zIndex = new CompositeZIndex([HEADER_ZINDEX]);

  return (
  <Layer zIndex={zIndex}>
    <Modal
      accessibilityModalLabel="Delete board 60s Furniture"
      heading="Are you sure?"
      role="alertdialog"
      onDismiss={() => { setShowModal(!showModal) }}
      footer={
        <Flex justifyContent="end" gap={2}>
          <Button color="gray" text="Cancel"/>
          <Button color="red" text="Delete forever"/>
        </Flex>
      }
      size="sm"
    >
      <Box padding={8}>
        <Text align="center" size="lg">Once you delete a board and all its Pins, you can't undo it!</Text>
      </Box>
    </Modal>
  </Layer>
  );
}

function AlertDialogAccessibilityExample(props) {
  const [showModal, setShowModal] = React.useState(false);
  const HEADER_ZINDEX = new FixedZIndex(10);
  const zIndex = new CompositeZIndex([HEADER_ZINDEX]);
  return (
  <Layer zIndex={zIndex}>
    <Modal
      accessibilityModalLabel="Delete board 60s Furniture"
      heading="Are you sure?"
      role="alertdialog"
      onDismiss={() => { setShowModal(!showModal) }}
      footer={
        <Flex justifyContent="end" gap={2}>
          <Button color="gray" text="Cancel"/>
          <Button color="red" text="Delete forever"/>
        </Flex>
      }
      size="sm"
    >
      <Box padding={8}>
        <Text align="center" size="lg">Once you delete a board and all its Pins, you can't undo it!</Text>
      </Box>
    </Modal>
  </Layer>
  );
}

role="dialog" (default)

Edits made below will not be reflected in the example above, open the sandbox instead.

function DialogExample(props) {
  const ModalWithHeading = ({
    onDismiss,
  }) => {

    return (
      <Modal
        accessibilityModalLabel="Create new board"
        heading="Create board"
        onDismiss={onDismiss}
        footer={
          <Flex alignItems="center" justifyContent="end">
            <Button color="red" text="Create"/>
          </Flex>
        }
        size="sm"
      >
        <Box paddingX={8}>
          <Box marginBottom={8}>
            <TextField
              id="name"
              onChange={({ value }) => console.log(value)}
              placeholder='Like "Places to go" or "Recipes to Make"'
              label="Name"
              type="text"
            />
          </Box>
          <Checkbox
            checked={false}
            id="secret"
            label="Keep this board secret"
            subtext="So only you and collaborators can see it."
            name="languages"
            onChange={({ checked }) => {
              console.log(checked);
            }}
          />
        </Box>
      </Modal>
    );
  };

  const [shouldShow, setShouldShow] = React.useState(true);
  const HEADER_ZINDEX = new FixedZIndex(10);
  const modalZIndex = new CompositeZIndex([HEADER_ZINDEX]);

  return (
    <React.Fragment>
      <Button
        text="View Modal"
        onClick={() => setShouldShow(true)}
      />
      {shouldShow && (
        <Layer zIndex={modalZIndex}>
          <ModalWithHeading onDismiss={() => setShouldShow(false)} />
        </Layer>
      )}
    </React.Fragment>
  );
}

function DialogExample(props) {
  const ModalWithHeading = ({
    onDismiss,
  }) => {
    return (
      <Modal
        accessibilityModalLabel="Create new board"
        heading="Create board"
        onDismiss={onDismiss}
        footer={
          <Flex alignItems="center" justifyContent="end">
            <Button color="red" text="Create"/>
          </Flex>
        }
        size="sm"
      >
        <Box paddingX={8}>
          <Box marginBottom={8}>
            <TextField
              id="name"
              onChange={({ value }) => console.log(value)}
              placeholder='Like "Places to go" or "Recipes to Make"'
              label="Name"
              type="text"
            />
          </Box>
          <Checkbox
            checked={false}
            id="secret"
            label="Keep this board secret"
            subtext="So only you and collaborators can see it."
            name="languages"
            onChange={({ checked }) => {
              console.log(checked);
            }}
          />
        </Box>
      </Modal>
    );
  };
  const [shouldShow, setShouldShow] = React.useState(true);
  const HEADER_ZINDEX = new FixedZIndex(10);
  const modalZIndex = new CompositeZIndex([HEADER_ZINDEX]);
  return (
    <React.Fragment>
      <Button
        text="View Modal"
        onClick={() => setShouldShow(true)}
      />
      {shouldShow && (
        <Layer zIndex={modalZIndex}>
          <ModalWithHeading onDismiss={() => setShouldShow(false)} />
        </Layer>
      )}
    </React.Fragment>
  );
}

Localization

Be sure to localize the heading, subheading and accessibilityModalLabel props, as well as any other text elements within Modal. Note that localization can lengthen text by 20 to 30 percent.

Variants

Heading

The heading will render an H1 when a string is passed in and supports multiple alignment options with the align prop.

Start
start aligned text is the primary alignment for our Business products. It will be left-aligned in left-to-right languages and right-aligned in right-to-left languages.
Center
center aligned text is the primary alignment for our Pinner products.
Custom
If you need more control over the Modal heading, you can pass a custom React node as the heading prop and the Modal will render that instead. This feature should be used sparingly as most customization should be added to the content area. Please contact the Gestalt team if this is needed for your product.

Edits made below will not be reflected in the example above, open the sandbox instead.

function HeadingExample(props) {
  const ModalWithHeading = ({
    onDismiss,
  }) => {

    return (
      <Modal
        accessibilityModalLabel="Create new board"
        heading="Create board"
        onDismiss={onDismiss}
        footer={
          <Flex alignItems="center" justifyContent="end">
            <Button color="red" text="Create"/>
          </Flex>
        }
        size="sm"
      >
        <Box paddingX={8}>
          <Box marginBottom={8}>
            <TextField
              id="name"
              onChange={({ value }) => console.log(value)}
              placeholder='Like "Places to go" or "Recipes to Make"'
              label="Name"
              type="text"
            />
          </Box>
          <Checkbox
            checked={false}
            id="secret"
            label="Keep this board secret"
            subtext="So only you and collaborators can see it."
            name="languages"
            onChange={({ checked }) => {
              console.log(checked);
            }}
          />
        </Box>
      </Modal>
    );
  };

  const [shouldShow, setShouldShow] = React.useState(true);
  const HEADER_ZINDEX = new FixedZIndex(10);
  const modalZIndex = new CompositeZIndex([HEADER_ZINDEX]);

  return (
    <React.Fragment>
      <Button
        text="View Modal"
        onClick={() => setShouldShow(true)}
      />
      {shouldShow && (
        <Layer zIndex={modalZIndex}>
          <ModalWithHeading onDismiss={() => setShouldShow(false)} />
        </Layer>
      )}
    </React.Fragment>
  );
}

function HeadingExample(props) {
  const ModalWithHeading = ({
    onDismiss,
  }) => {
    return (
      <Modal
        accessibilityModalLabel="Create new board"
        heading="Create board"
        onDismiss={onDismiss}
        footer={
          <Flex alignItems="center" justifyContent="end">
            <Button color="red" text="Create"/>
          </Flex>
        }
        size="sm"
      >
        <Box paddingX={8}>
          <Box marginBottom={8}>
            <TextField
              id="name"
              onChange={({ value }) => console.log(value)}
              placeholder='Like "Places to go" or "Recipes to Make"'
              label="Name"
              type="text"
            />
          </Box>
          <Checkbox
            checked={false}
            id="secret"
            label="Keep this board secret"
            subtext="So only you and collaborators can see it."
            name="languages"
            onChange={({ checked }) => {
              console.log(checked);
            }}
          />
        </Box>
      </Modal>
    );
  };
  const [shouldShow, setShouldShow] = React.useState(true);
  const HEADER_ZINDEX = new FixedZIndex(10);
  const modalZIndex = new CompositeZIndex([HEADER_ZINDEX]);
  return (
    <React.Fragment>
      <Button
        text="View Modal"
        onClick={() => setShouldShow(true)}
      />
      {shouldShow && (
        <Layer zIndex={modalZIndex}>
          <ModalWithHeading onDismiss={() => setShouldShow(false)} />
        </Layer>
      )}
    </React.Fragment>
  );
}

Sub-heading

The subHeading is a container that can be used for subtext that provides additional context for the Modal. The sub-heading locks to the top under the heading.

Edits made below will not be reflected in the example above, open the sandbox instead.

function SubHeadingExample(props) {
  const ModalWithSubHeading = ({
    onDismiss,
  }) => {

    return (
      <Modal
        accessibilityModalLabel="Resume account creation"
        heading="Resume your work?"
        subHeading="Welcome back to the business account creation process!"
        align="start"
        onDismiss={onDismiss}
        footer={
          <Flex alignItems="center" justifyContent="end" gap={2}>
            <Button text="Cancel"/>
            <Button color="red" text="Resume"/>
          </Flex>
        }
        size="sm"
      >
        <Box paddingX={8}>
          <Text>Want to continue where you left off? Click "Resume" to continue creating your account or "Cancel" to start over.</Text>
        </Box>
      </Modal>
    );
  };

  const [shouldShow, setShouldShow] = React.useState(true);
  const HEADER_ZINDEX = new FixedZIndex(10);
  const modalZIndex = new CompositeZIndex([HEADER_ZINDEX]);

  return (
    <React.Fragment>
      <Button
        text="View Modal"
        onClick={() => setShouldShow(true)}
      />
      {shouldShow && (
        <Layer zIndex={modalZIndex}>
          <ModalWithSubHeading onDismiss={() => setShouldShow(false)} />
        </Layer>
      )}
    </React.Fragment>
  );
}

function SubHeadingExample(props) {
  const ModalWithSubHeading = ({
    onDismiss,
  }) => {
    return (
      <Modal
        accessibilityModalLabel="Resume account creation"
        heading="Resume your work?"
        subHeading="Welcome back to the business account creation process!"
        align="start"
        onDismiss={onDismiss}
        footer={
          <Flex alignItems="center" justifyContent="end" gap={2}>
            <Button text="Cancel"/>
            <Button color="red" text="Resume"/>
          </Flex>
        }
        size="sm"
      >
        <Box paddingX={8}>
          <Text>Want to continue where you left off? Click "Resume" to continue creating your account or "Cancel" to start over.</Text>
        </Box>
      </Modal>
    );
  };
  const [shouldShow, setShouldShow] = React.useState(true);
  const HEADER_ZINDEX = new FixedZIndex(10);
  const modalZIndex = new CompositeZIndex([HEADER_ZINDEX]);
  return (
    <React.Fragment>
      <Button
        text="View Modal"
        onClick={() => setShouldShow(true)}
      />
      {shouldShow && (
        <Layer zIndex={modalZIndex}>
          <ModalWithSubHeading onDismiss={() => setShouldShow(false)} />
        </Layer>
      )}
    </React.Fragment>
  );
}

Sizes

Modal has 3 size options: small (sm - 540px), medium (md - 720px) and large (lg - 900px). If absolutely necessary, a number representing a custom width can be provided instead, but we recommend using one of the standard sizes.
All Modals have a max-width of 100%.

function SizesExample(props) {
  function reducer(state, action) {
    switch (action.type) {
      case 'small':
        return {modal: 'small'};
      case 'medium':
        return {modal: 'medium'};
      case 'large':
        return {modal: 'large'};
      case 'none':
        return {modal: 'none'};
      default:
        throw new Error();
    }
  }

  const initialState = {modal: 'none'};
  const [state, dispatch] = React.useReducer(reducer, initialState);
  const HEADER_ZINDEX = new FixedZIndex(10);
  const zIndex = new CompositeZIndex([HEADER_ZINDEX]);

  return (
    <Box marginStart={-1} marginEnd={-1}>
      <Box padding={1}>
        <Button
          text="Small Modal"
          onClick={() => { dispatch({type: 'small'}) }}
        />
        {state.modal === 'small' && (
          <Layer zIndex={zIndex}>
            <Modal
              accessibilityModalLabel="View default padding and styling"
              heading="Small modal"
              onDismiss={() => { dispatch({type: 'none'}) }}
              footer={<Heading size="md">Footer</Heading>}
              size="sm"
            >
              <Box padding={8}>
                <Heading size="md">Children</Heading>
              </Box>
            </Modal>
          </Layer>
        )}
      </Box>
      <Box padding={1}>
        <Button
          text="Medium Modal"
          onClick={() => { dispatch({type: 'medium'}) }}
        />
        {state.modal === 'medium' && (
          <Layer zIndex={zIndex}>
            <Modal
              accessibilityModalLabel="View default padding and styling"
              heading="Medium modal"
              onDismiss={() => { dispatch({type: 'none'}) }}
              footer={<Heading size="md">Footer</Heading>}
              size="md"
            >
              <Box padding={8}>
                <Heading size="md">Children</Heading>
              </Box>
            </Modal>
          </Layer>
        )}
      </Box>
      <Box padding={1}>
        <Button
          text="Large Modal"
          onClick={() => { dispatch({type: 'large'}) }}
        />
        {state.modal === 'large' && (
          <Layer zIndex={zIndex}>
            <Modal
              accessibilityModalLabel="View default padding and styling"
              heading="Large modal"
              onDismiss={() => { dispatch({type: 'none'}) }}
              footer={<Heading size="md">Footer</Heading>}
              size="lg"
            >
              <Box padding={8}>
                <Heading size="md">Children</Heading>
              </Box>
            </Modal>
          </Layer>
        )}
      </Box>
    </Box>
  );
}

function SizesExample(props) {
  function reducer(state, action) {
    switch (action.type) {
      case 'small':
        return {modal: 'small'};
      case 'medium':
        return {modal: 'medium'};
      case 'large':
        return {modal: 'large'};
      case 'none':
        return {modal: 'none'};
      default:
        throw new Error();
    }
  }
  const initialState = {modal: 'none'};
  const [state, dispatch] = React.useReducer(reducer, initialState);
  const HEADER_ZINDEX = new FixedZIndex(10);
  const zIndex = new CompositeZIndex([HEADER_ZINDEX]);
  return (
    <Box marginStart={-1} marginEnd={-1}>
      <Box padding={1}>
        <Button
          text="Small Modal"
          onClick={() => { dispatch({type: 'small'}) }}
        />
        {state.modal === 'small' && (
          <Layer zIndex={zIndex}>
            <Modal
              accessibilityModalLabel="View default padding and styling"
              heading="Small modal"
              onDismiss={() => { dispatch({type: 'none'}) }}
              footer={<Heading size="md">Footer</Heading>}
              size="sm"
            >
              <Box padding={8}>
                <Heading size="md">Children</Heading>
              </Box>
            </Modal>
          </Layer>
        )}
      </Box>
      <Box padding={1}>
        <Button
          text="Medium Modal"
          onClick={() => { dispatch({type: 'medium'}) }}
        />
        {state.modal === 'medium' && (
          <Layer zIndex={zIndex}>
            <Modal
              accessibilityModalLabel="View default padding and styling"
              heading="Medium modal"
              onDismiss={() => { dispatch({type: 'none'}) }}
              footer={<Heading size="md">Footer</Heading>}
              size="md"
            >
              <Box padding={8}>
                <Heading size="md">Children</Heading>
              </Box>
            </Modal>
          </Layer>
        )}
      </Box>
      <Box padding={1}>
        <Button
          text="Large Modal"
          onClick={() => { dispatch({type: 'large'}) }}
        />
        {state.modal === 'large' && (
          <Layer zIndex={zIndex}>
            <Modal
              accessibilityModalLabel="View default padding and styling"
              heading="Large modal"
              onDismiss={() => { dispatch({type: 'none'}) }}
              footer={<Heading size="md">Footer</Heading>}
              size="lg"
            >
              <Box padding={8}>
                <Heading size="md">Children</Heading>
              </Box>
            </Modal>
          </Layer>
        )}
      </Box>
    </Box>
  );
}

Preventing close on outside click

By default, users can click outside the Modal (on the overlay) to close it. This can be disabled by setting closeOnOutsideClick to false. In most cases, the user should be prevented from closing the Modal if the action is required.

function PreventCloseExample(props) {
  const [showModal, setShowModal] = React.useState(false);
  return (
    <React.Fragment>
      <Button
        text="Open Modal"
        onClick={() => { setShowModal(!showModal) }}
      />
      {showModal && (
        <Layer>
          <Modal
            accessibilityModalLabel="Non closable modal"
            closeOnOutsideClick={false}
            heading="Heading"
            onDismiss={() => { setShowModal(!showModal) }}
          >
            <Box padding={8}>
              <Text align="center">Click on the button to close the modal</Text>
              <Box marginTop={4}>
                <Button color="red" text="Close" onClick={() => { setShowModal(!showModal) }} />
              </Box>
            </Box>
          </Modal>
        </Layer>
      )}
    </React.Fragment>
  );
}

function PreventCloseExample(props) {
  const [showModal, setShowModal] = React.useState(false);
  return (
    <React.Fragment>
      <Button
        text="Open Modal"
        onClick={() => { setShowModal(!showModal) }}
      />
      {showModal && (
        <Layer>
          <Modal
            accessibilityModalLabel="Non closable modal"
            closeOnOutsideClick={false}
            heading="Heading"
            onDismiss={() => { setShowModal(!showModal) }}
          >
            <Box padding={8}>
              <Text align="center">Click on the button to close the modal</Text>
              <Box marginTop={4}>
                <Button color="red" text="Close" onClick={() => { setShowModal(!showModal) }} />
              </Box>
            </Box>
          </Modal>
        </Layer>
      )}
    </React.Fragment>
  );
}

Sheet
To allow users to view optional information or complete sub-tasks in a workflow while keeping the context of the current page, use Sheet.

Toast
Toast provides temporary feedback on an interaction. Toasts appear at the bottom of a desktop screen or top of a mobile screen, instead of blocking the entire page.

Edit page on GitHub

Modal

Props

Usage guidelines

Best practices

Accessibility

Labels

Role

Localization

Variants

Heading

Sub-heading

Sizes

Preventing close on outside click

Related