ModalProvider

Notes

An accessible modal component manager. ModalProvider does not create any UI of its own; it is intended to work with the modal UI components in this library such as Overlay. ModalProvider will handle opening and closing your UI component and manages focus, close on Escape, mask animation, and key accessible attributes.

There are four main steps to leverage ModalProvider:

The main export, ModalProvider, should be wrapped around your entire React application as near to the application root as possible. ModalProvider leverages React Context to expose the openModal and closeModal methods to your entire app.

In your html, create a sibling div to your React app's root div. Set a unique id attribute on that div, and pass that id as the targetElementId prop of the ModalProvider created in step one. ModalProvider uses a React Portal, and this targetElementId tells the provider where to render your modals. Using a sibling div to the react app makes z-index handling much easier.

For accessiblity, we want to mark the main React app hidden from screenreaders when a modal is open. For this reason, pass the id of the element to which your React app is mounted as the appElementId prop of the ModalProvider.

In your application, wherever you need to launch a modal, import ModalContext from this component, and access it using the React.useContext hook. This will give you access to the openModal method; now you simply pass the component you want to render to openModal via its 'component' property. See example to the right.

Also check out our Overlay docs for an example using Overlays.

Props

appElementIdstring
String id attribute which is set on the root of your React application. Modal provider will mark this element as aria-hidden while any modal is open.
childrenany
The portion of the React application that will have access to the ModalProvider 'openModal' and 'closeModal' methods. Generally, the ModalProvider should be near the root of your React app.
targetElementIdstring
String id attribute on the element to which modals will be attached.

Example: Launching a custom modal

const CustomDialog = ({ headingText }) => {
  const { closeModal } = React.useContext(ModalContext);
  return (
    <div aria-labelledby="dialog-heading" className="bg-white absoluteCenter" role="dialog" style={{ width: '50vw', height: '50vh', position: 'fixed'}}>
      <div className="text-right">
        <CloseButton onClick={closeModal} ariaLabel="Close" />
      </div>
      <div className="sb-global-gutters py5">
        <Heading id="dialog-heading" tagName="h2" size="md" className="text-semibold pb4">{headingText}</Heading>
        <p className="pb3">Attach the close modal function to any buttons if you expect them to close the dialog.</p>
        <Button visualStyle="positive" onClick={closeModal}>Close dialog</Button>
      </div>
    </div>
  );
};

const SampleApp = () => {
  const { openModal } = React.useContext(ModalContext);

  const openCustomModal = () => {
    openModal({
      component: CustomDialog,
      // If your component's props can't be determined until runtime, you can pass them in
      // when opening the overlay.
      componentProps: {
        headingText: 'Sample dialog',
      },
      modalRootProps: {
        'aria-label': 'Sample custom dialog'
      }
    });
  };

  return (
    <div className="p3">
      <p className="pb3">Note that ModalProvider is intended to work with the modal UI components in this library, however, you can certainly create a custom modal as exemplified below.</p>
      <Button onClick={openCustomModal}>Open a modal</Button>
    </div>
  )
}

const ModalExample = () => (
  <ModalProvider appElementId="js-content" targetElementId="modal-target">
    <SampleApp />
  </ModalProvider>
);

render(<ModalExample />);

const CustomDialog = ({ headingText }) => {
  const { closeModal } = React.useContext(ModalContext);
  return (
    <div aria-labelledby="dialog-heading" className="bg-white absoluteCenter" role="dialog" style={{ width: '50vw', height: '50vh', position: 'fixed'}}>
      <div className="text-right">
        <CloseButton onClick={closeModal} ariaLabel="Close" />
      </div>
      <div className="sb-global-gutters py5">
        <Heading id="dialog-heading" tagName="h2" size="md" className="text-semibold pb4">{headingText}</Heading>
        <p className="pb3">Attach the close modal function to any buttons if you expect them to close the dialog.</p>
        <Button visualStyle="positive" onClick={closeModal}>Close dialog</Button>
      </div>
    </div>
  );
};

const SampleApp = () => {
  const { openModal } = React.useContext(ModalContext);

  const openCustomModal = () => {
    openModal({
      component: CustomDialog,
      // If your component's props can't be determined until runtime, you can pass them in
      // when opening the overlay.
      componentProps: {
        headingText: 'Sample dialog',
      },
      modalRootProps: {
        'aria-label': 'Sample custom dialog'
      }
    });
  };

  return (
    <div className="p3">
      <p className="pb3">Note that ModalProvider is intended to work with the modal UI components in this library, however, you can certainly create a custom modal as exemplified below.</p>
      <Button onClick={openCustomModal}>Open a modal</Button>
    </div>
  )
}

const ModalExample = () => (
  <ModalProvider appElementId="js-content" targetElementId="modal-target">
    <SampleApp />
  </ModalProvider>
);

render(<ModalExample />);