Modal

<Modal> allows you to use its bespoke set of contents. children prop maps to the modal body content. You can also use modalLabel, modalHeading, secondaryButtonText and primaryButtonText props to change the corresponding text:

CodeSandbox React Angular Vue Vanilla

<>
  {/*
    <ModalStateManager> is something application writes to implement a launcher button with its state.
    See "Opening/closing modal" section for more details.
  */}
  <ModalStateManager
    renderLauncher={({ open, setOpen }) => (
      <Button onClick={() => setOpen(true)}>Launch modal</Button>
    )}
  >
    {({ open, setOpen }) => (
      <Modal
        buttonTriggerText="Launch modal"
        modalHeading="Modal heading"
        modalLabel="Label"
        primaryButtonText="OK"
        secondaryButtonText="Cancel"
        open={open}
        onRequestClose={() => setOpen(false)}
      >
        <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse cursus fermentum risus, sit amet fringilla nunc pellentesque quis. Duis quis odio ultrices, cursus lacus ac, posuere felis. Donec dignissim libero in augue mattis, a molestie metus vestibulum. Aliquam placerat felis ultrices lorem condimentum, nec ullamcorper felis porttitor. </p>
      </Modal>
    )}
  </ModalStateManager>
</>

<>
  {/*
    <ModalStateManager> is something application writes to implement a launcher button with its state.
    See "Opening/closing modal" section for more details.
  */}
  <ModalStateManager
    renderLauncher={({ open, setOpen }) => (
      <Button onClick={() => setOpen(true)}>Launch modal</Button>
    )}
  >
    {({ open, setOpen }) => (
      <Modal
        buttonTriggerText="Launch modal"
        modalHeading="Modal heading"
        modalLabel="Label"
        primaryButtonText="OK"
        secondaryButtonText="Cancel"
        open={open}
        onRequestClose={() => setOpen(false)}
      >
        <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse cursus fermentum risus, sit amet fringilla nunc pellentesque quis. Duis quis odio ultrices, cursus lacus ac, posuere felis. Donec dignissim libero in augue mattis, a molestie metus vestibulum. Aliquam placerat felis ultrices lorem condimentum, nec ullamcorper felis porttitor. </p>
      </Modal>
    )}
  </ModalStateManager>
</>

ComposedModal

<ComposedModal> provides you with more flexibility in the contents. You can provide the contents via <ModalHeader>, <ModalBody> and <ModalFooter> with your contents in them:

CodeSandbox React

<>
  {/*
    <ModalStateManager> is something application writes to implement a launcher button with its state.
    See "Opening/closing modal" section for more details.
  */}
  <ModalStateManager
    renderLauncher={({ open, setOpen }) => (
      <Button onClick={() => setOpen(true)}>Launch modal</Button>
    )}
  >
    {({ open, setOpen }) => (
      <ComposedModal open={open} onClose={() => setOpen(false)}>
        <ModalHeader label="Modal label">
          <h1>Modal heading</h1>
        </ModalHeader>
        <ModalBody>
          <p className=".bx--modal-content__text">
            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse cursus fermentum risus, sit amet fringilla nunc pellentesque quis. Duis quis odio ultrices, cursus lacus ac, posuere felis. Donec dignissim libero in augue mattis, a molestie metus vestibulum. Aliquam placerat felis ultrices lorem condimentum, nec ullamcorper felis porttitor.
          </p>
        </ModalBody>
        <ModalFooter primaryButtonText="OK" secondaryButtonText="Cancel" />
      </ComposedModal>
    )}
  </ModalStateManager>
</>

<>
  {/*
    <ModalStateManager> is something application writes to implement a launcher button with its state.
    See "Opening/closing modal" section for more details.
  */}
  <ModalStateManager
    renderLauncher={({ open, setOpen }) => (
      <Button onClick={() => setOpen(true)}>Launch modal</Button>
    )}
  >
    {({ open, setOpen }) => (
      <ComposedModal open={open} onClose={() => setOpen(false)}>
        <ModalHeader label="Modal label">
          <h1>Modal heading</h1>
        </ModalHeader>
        <ModalBody>
          <p className=".bx--modal-content__text">
            Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse cursus fermentum risus, sit amet fringilla nunc pellentesque quis. Duis quis odio ultrices, cursus lacus ac, posuere felis. Donec dignissim libero in augue mattis, a molestie metus vestibulum. Aliquam placerat felis ultrices lorem condimentum, nec ullamcorper felis porttitor.
          </p>
        </ModalBody>
        <ModalFooter primaryButtonText="OK" secondaryButtonText="Cancel" />
      </ComposedModal>
    )}
  </ModalStateManager>
</>

Installation

To use styles:

@import "carbon-components/scss/components/modal/modal";

To import React components:

// For using `<Modal>`
import { Modal } from "carbon-components-react";
// For using `<ComposedModal>`
import {
  ComposedModal,
  ModalHeder,
  ModalBody,
  ModalFooter,

Usage

This section explains usage with our React variant. For usage with other frameworks, please follow a link in component live demo above.

For both modal variants, you can open/close the modal by changing the open prop. For example, you can implement a launcher button with a React state and a <Button> that changes the state:

function ModalStateManager() {
  const [open, setOpen] = useState(false);
  return (
    <>
      {typeof document === "undefined"
        ? null
        : ReactDOM.createPortal(
            <ComposedModal open={open} onClose={() => setOpen(false)}>
              ...

You can create an abstract version of such state manager, like:

const ModalStateManager = ({
  renderLauncher: LauncherContent,
  children: ModalContent,
}) => {
  const [open, setOpen] = useState(false);
  return (
    <>
      {!ModalContent || typeof document === "undefined"
        ? null

<Modal>/<ComposedModal> has to be put at the top-level in a React tree. The easiest way to ensure that is using React portal as shown in above example.

There are four responsive modal sizes: xs, small, default, and large. You can set it via size prop:

<ComposedModal size="lg">
  <ModalHeader />
  <ModalBody>
    <p className="bx--modal-content__text">
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
      cursus fermentum risus, sit amet fringilla nunc pellentesque quis. Duis
      quis odio ultrices, cursus lacus ac, posuere felis. Donec dignissim libero
      in augue mattis, a molestie metus vestibulum. Aliquam placerat felis
      ultrices lorem condimentum, nec ullamcorper felis porttitor.

Form elements in modal body

Depending on the modal size of your choice and the viewport size, <Modal>/<ComposedModal> adds 20% padding at the right of the modal body content. Carbon design specifies that such 20% padding shouldn't be applied to form elements. You can set hasFormprop to <Modal>/<ModalBody> to remove the padding, and use bx--modal-content__regular-content class to apply the 20% padding to non-form contents, like below:

<ComposedModal>
  <ModalHeader />
  <ModalBody hasForm>
    <TextInput data-modal-primary-focus labelText="Enter something" />
    <p className="bx--modal-content__text bx--modal-content__regular-content">
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse
      cursus fermentum risus, sit amet fringilla nunc pellentesque quis. Duis
      quis odio ultrices, cursus lacus ac, posuere felis. Donec dignissim libero
      in augue mattis, a molestie metus vestibulum. Aliquam placerat felis

Scrolling behavior

In case where the largest modal size cannot fit your modal body content in, Carbon design specifies to have a "visual fade" look at the end of the modal body area to indicate there is additional content out of view. You can sethasScrollingContent prop to <Modal>/<ModalBody>to do that, like below:

<ComposedModal size="large">
  <ModalHeader />
  <ModalBody hasScrollingContent>
    <p className=".bx--modal-content__text">Some very large contents...</p>
  </ModalBody>
</ComposedModal>

With <Modal>, you have limited control over the set of buttons. Supported patterns are the following:

No button (passive modal): With passiveModal prop in <Modal>
Transactional modals: Only supports two buttons variant. For others, use <ComposedModal>
Danger modal: With danger prop in <Modal> (like below)

<Modal danger>
  <ModalHeader />
  <p className="bx--modal-content__text">The modal body content</p>
</Modal>

With <ComposedModal>, you can control the buttons with the following:

No button (passive modal): By not putting <ModalFooter>
Transactional modals:
- One button (acknowledgement modal): By setting primaryButtonText prop to <ModalFooter>
- Two buttons: By setting secondaryButtonText prop to <ModalFooter> in addition to primaryButtonText prop
- Three buttons: Put three buttons as children of <ModalFooter>, instead of using primaryButtonText or secondaryButtonText. Using this option requires style adjustment defined in application-level CSS for <ModalFooter>, e.g. .bx--modal-footer { padding: 25%; }.
Danger modal: By setting danger prop in <ModalFooter> (like below)

<ComposedModal>
  ...
  <ModalFooter danger primaryButtonText="OK" secondaryButtonText="Cancel" />
</ComposedModal>

As the instruction for the three buttons implies, <ModalFooter> is flexible on the buttons as you render <Button> s by yourself, like below. In this case, application code needs to care of running action upon those buttons, e.g. closing the modal:

<ComposedModal>
  ...
  <ModalFooter>
    <Button
      kind="secondary"
      onClick={() => { (Run some action...) setOpen(false); }}>
      Another button
    </Buttton>
    <Button

For short, direct messages the title can include the whole message to add visual clarity to an otherwise repetitive title and body message.

To use this pattern with <Modal>, you can omit children prop:

const modalHeadding =
  'Are you sure you want to add the "Speech to Text" service ' +
  'to the node-test app?';
...
<Modal
  modalHeading={modalHeading}
  secondaryButtonText="Cancel"
  primaryButtonText="Add"
/>

To use this pattern with <ComposedModal>, you can omit <ModalBody>:

<ComposedModal>
  <ModalHeader label="Modla label">
    <h1>
      Are you sure you want to add the "Speech to Text" service to the node-test
      app?
    </h1>
  </ModalHeader>
  <ModalFooter primaryButtonText="OK" secondaryButtonText="Cancel" />
</ComposedModal>

Focus management

For both modal variants, once modal gets open, keyboard focus will be restricted inside modal. It means:

If you hit tab key at the last keyboard-focusable element in modal, the first keyboard-focusable element in modal will get focus.
If you hit shift-tab key at the first keyboard-focusable element in modal, the last keyboard-focusable element in modal will get focus.

We take extra step here to ensure such behavior works with floating menus, given floating menu is placed outside of modal in DOM. If you use any non-Carbon floating menus in your application, set

selectorsFloatingMenus=.bx--overflow-menu-options.bx--tooltip.flatpickr-calendar.your-floating-menu-foo.your-floating-menu-bar`

to <Modal>/<ComposedModal>.

Also for both modal variants, you can set the DOM element that gets focus when the modal gets open, by either of the following ways:

Setting `data-modal-primary-focus` attribute to the target element

<ComposedModal>
  <ModalBody hasForm>
    <TextInput data-modal-primary-focus labelText="Enter something" />
  </ModalBody>
</ComposedModal>

Specifying a query selector to the target element

{
  /* `.bx--text-input` selects the `<input>` in `<TextInput>` */
}
<ComposedModal selectorPrimaryFocus=".bx--text-input">
  <ModalBody hasForm>
    <TextInput labelText="Enter something" />
  </ModalBody>
</ComposedModal>;