Sajari UI

A dialog is a window overlaid on either the primary window or another dialog window. Contents behind a modal dialog are inert meaning that users cannot interact with content behind the dialog.

Import

Sajari exports 8 components to help you create any modal dialog.

Modal: The wrapper that provides context for its children
ModalOverlay: The dimmed overlay behind the modal dialog
ModalContent: The container for the modal dialog's content
ModalHeader: The header houses the title and close button
ModalTitle: The title that labels the modal dialog
ModalFooter: The footer that houses the modal actions
ModalBody: The wrapper that houses the modal's main content
ModalCloseButton: The button that closes the modal

import {
  Modal,
  ModalOverlay,
  ModalContent,
  ModalHeader,
  ModalTitle,
  ModalFooter,
  ModalBody,
  ModalCloseButton,
} from '@sajari-ui/core';

import {
  Modal,
  ModalOverlay,
  ModalContent,
  ModalHeader,
  ModalTitle,
  ModalFooter,
  ModalBody,
  ModalCloseButton,
} from '@sajari-ui/core';

Usage

When the modal opens, focus is sent into the modal and set to the first tabbable element. If there are no tabbled element, focus is set on the ModalContent.

Editable Example

function BasicUsage() {
  const { open, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button onClick={onOpen}>Open Modal</Button>

      <Modal open={open} onClose={onClose}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>
            <ModalTitle>Modal Title</ModalTitle>
            <ModalCloseButton />
          </ModalHeader>

          <ModalBody>
            <LoremIpsum p={2} />
          </ModalBody>

          <ModalFooter>
            <Button appearance="primary">Action</Button>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

function BasicUsage() {
  const { open, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button onClick={onOpen}>Open Modal</Button>
      <Modal open={open} onClose={onClose}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>
            <ModalTitle>Modal Title</ModalTitle>
            <ModalCloseButton />
          </ModalHeader>
          <ModalBody>
            <LoremIpsum p={2} />
          </ModalBody>
          <ModalFooter>
            <Button appearance="primary">Action</Button>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

When the dialog closes, it returns focus to the element that triggered. Set finalFocusRef to element that should receive focus when the modal closes.

Editable Example

Some other content that'll receive focus on close.

function ReturnFocus() {
  const { open, onOpen, onClose } = useDisclosure();
  const finalRef = React.useRef();

  return (
    <>
      <Box ref={finalRef} tabIndex={-1} aria-label="Focus moved to this box">
        Some other content that'll receive focus on close.
      </Box>

      <Button mt={4} onClick={onOpen}>
        Open Modal
      </Button>
      <Modal finalFocusRef={finalRef} open={open} onClose={onClose}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>
            <ModalTitle>Modal Title</ModalTitle>
            <ModalCloseButton />
          </ModalHeader>

          <ModalBody>
            <LoremIpsum p={2} />
          </ModalBody>

          <ModalFooter>
            <Button appearance="primary">Action</Button>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

function ReturnFocus() {
  const { open, onOpen, onClose } = useDisclosure();
  const finalRef = React.useRef();
  return (
    <>
      <Box ref={finalRef} tabIndex={-1} aria-label="Focus moved to this box">
        Some other content that'll receive focus on close.
      </Box>
      <Button mt={4} onClick={onOpen}>
        Open Modal
      </Button>
      <Modal finalFocusRef={finalRef} open={open} onClose={onClose}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>
            <ModalTitle>Modal Title</ModalTitle>
            <ModalCloseButton />
          </ModalHeader>
          <ModalBody>
            <LoremIpsum p={2} />
          </ModalBody>
          <ModalFooter>
            <Button appearance="primary">Action</Button>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

For accessibility, it's recommended to block scrolling on the main document behind the modal. Sajari does this by default but you can set blockScrollOnMount to false to allow scrolling behind modal.

Editable Example

function BasicUsage() {
  const { open, onOpen, onClose } = useDisclosure();

  return (
    <>
      <Button onClick={onOpen}>Open Modal</Button>

      <Modal blockScrollOnMount={false} open={open} onClose={onClose}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>
            <ModalTitle>Modal Title</ModalTitle>
            <ModalCloseButton />
          </ModalHeader>

          <ModalBody>
            <Text fontWeight="bold" mb="1rem">
              You can scroll the content behind the modal
            </Text>
            <LoremIpsum p={2} />
          </ModalBody>

          <ModalFooter>
            <Button appearance="primary">Action</Button>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

function BasicUsage() {
  const { open, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button onClick={onOpen}>Open Modal</Button>
      <Modal blockScrollOnMount={false} open={open} onClose={onClose}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>
            <ModalTitle>Modal Title</ModalTitle>
            <ModalCloseButton />
          </ModalHeader>
          <ModalBody>
            <Text fontWeight="bold" mb="1rem">
              You can scroll the content behind the modal
            </Text>
            <LoremIpsum p={2} />
          </ModalBody>
          <ModalFooter>
            <Button appearance="primary">Action</Button>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

By default, the modal closes when you click it's overlay. You can set closeOnOverlayClick to false if you want the modal to stay visible.

Editable Example

function ManualClose() {
  const { open, onOpen, onClose } = useDisclosure();

  return (
    <>
      <Button onClick={onOpen}>Open Modal</Button>

      <Modal closeOnOverlayClick={false} open={open} onClose={onClose}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>
            <ModalTitle>Modal Title</ModalTitle>
            <ModalCloseButton />
          </ModalHeader>

          <ModalBody pb={6}>
            <LoremIpsum p={2} />
          </ModalBody>

          <ModalFooter>
            <Button appearance="primary">Save</Button>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

function ManualClose() {
  const { open, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button onClick={onOpen}>Open Modal</Button>
      <Modal closeOnOverlayClick={false} open={open} onClose={onClose}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>
            <ModalTitle>Modal Title</ModalTitle>
            <ModalCloseButton />
          </ModalHeader>
          <ModalBody pb={6}>
            <LoremIpsum p={2} />
          </ModalBody>
          <ModalFooter>
            <Button appearance="primary">Save</Button>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

Pass the size prop if you need to adjust the size of the modal. Values can be any of the maxWidth prop values.

Editable Example

function SizeExample() {
  const { open, onOpen, onClose } = useDisclosure();
  const [size, setSize] = React.useState('md');

  const handleSizeClick = (newSize) => {
    setSize(newSize);
    onOpen();
  };

  const sizes = ['max-w-xs', 'max-w-sm', 'max-w-md', 'max-w-lg', 'max-w-xl', 'max-w-2xl', 'max-w-3xl'];

  return (
    <>
      <ButtonGroup flexWrap="flex-wrap">
        {sizes.map((size) => (
          <Button onClick={() => handleSizeClick(size)} key={size}>
            {size}
          </Button>
        ))}
      </ButtonGroup>

      <Modal onClose={onClose} size={size} open={open}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>
            <ModalTitle>Modal Title</ModalTitle>
            <ModalCloseButton />
          </ModalHeader>

          <ModalBody>
            <LoremIpsum p={2} />
          </ModalBody>

          <ModalFooter>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

function SizeExample() {
  const { open, onOpen, onClose } = useDisclosure();
  const [size, setSize] = React.useState('md');
  const handleSizeClick = (newSize) => {
    setSize(newSize);
    onOpen();
  };
  const sizes = ['max-w-xs', 'max-w-sm', 'max-w-md', 'max-w-lg', 'max-w-xl', 'max-w-2xl', 'max-w-3xl'];
  return (
    <>
      <ButtonGroup flexWrap="flex-wrap">
        {sizes.map((size) => (
          <Button onClick={() => handleSizeClick(size)} key={size}>
            {size}
          </Button>
        ))}
      </ButtonGroup>
      <Modal onClose={onClose} size={size} open={open}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>
            <ModalTitle>Modal Title</ModalTitle>
            <ModalCloseButton />
          </ModalHeader>
          <ModalBody>
            <LoremIpsum p={2} />
          </ModalBody>
          <ModalFooter>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

Preserving the scrollbar gap

By default, scrolling is blocked when the modal opens. This can lead to unpleasant content shift.

To prevent this, pass the preserveScrollBarGap prop. It applies a padding-right to the body element that's equal to the width of the browser's scrollbar.

Editable Example

function PreserveScrollBar() {
  const { open, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button onClick={onOpen}>Open Modal</Button>

      <Modal preserveScrollBarGap open={open} onClose={onClose}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>Modal Title</ModalHeader>
          <ModalCloseButton />
          <ModalBody>
            <LoremIpsum p={2} />
          </ModalBody>

          <ModalFooter>
            <Button appearance="primary">Action</Button>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

function PreserveScrollBar() {
  const { open, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button onClick={onOpen}>Open Modal</Button>
      <Modal preserveScrollBarGap open={open} onClose={onClose}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>Modal Title</ModalHeader>
          <ModalCloseButton />
          <ModalBody>
            <LoremIpsum p={2} />
          </ModalBody>
          <ModalFooter>
            <Button appearance="primary">Action</Button>
            <Button onClick={onClose}>Close</Button>
          </ModalFooter>
        </ModalContent>
      </Modal>
    </>
  );
}

Making other elements Inert

When the modal is open, it's rendered within a portal and all it's siblings have aria-hidden set to true so the only thing screen readers see is the modal. To disable this behavior, set useInert to false.

Accessibility

Keyboard and Focus Management

When the modal opens, focus is trapped within it.
When the dialog opens, focus is automatically set to the first enabled element, or the element with the initialFocusRef.
When the modal closes, focus returns to the element that was focused just before the modal activated, or the element with the finalFocusRef
Clicking on the overlay closes the Modal.
Pressing Esc closes the Modal.
Scrolling is blocked on the elements behind the modal.
The modal is portalled to the end of document.body to break it out of the source order and make it easy to add aria-hidden to its siblings.

ARIA

The ModalContent has aria-modal set to true.
The ModalContent has aria-labelledby set to the id of the ModalTitle
The ModalContent has aria-describedby set to the id of the ModalBody

Props

Name	Type	Default	Description
open	`boolean`		If `true`, the modal will open
onClose	`(event, reason) => void`		Callback invoked to close the modal.
initialFocusRef	`React.Ref`		The `ref` of the element to receive focus when the dialog opens
finalFocusRef	`React.Ref`		The `ref` of element to receive focus when the dialog closes
blockScrollOnMount	`boolean`	`true`	If `true`, scrolling will be disabled on the `body` when the modal opens.
preserveScrollBarGap	`boolean`		If `true`, a `padding-right` will be applied to the body element to preserve the scrollbar gap.
useInert	`boolean`	`true`	A11y: If `true`, all elements behing the `Modal` will have `aria-hidden` set to `true` so that screen readers can only see the `Modal`.
children	`React.ReactNode`		The content of the modal.
size	`BoxProps["maxWidth"]`	`max-w-md`	The size (`maxWidth`) of the modal.
closeOnOverlayClick	`boolean`	`true`	If `true`, the modal will close when the overlay is clicked
returnFocusOnClose	`boolean`	`true`	If `true`, the modal will return focus to the element that triggered it when it closes.
closeOnEsc	`boolean`	`true`	If `true`, the modal will close when the `Esc` key is pressed
id	`string`		The `id` of the modal

Other components

ModalOverlay, ModalHeader and ModalBody compose the Box component
ModalTitle composes the Text component
ModalCloseButton composes the CloseButton component
ModalFooter composes the ButtonGroup component

Modal (Dialog)

Import

Usage

Editable Example

Control Focus when Modal closes

Editable Example

Block Scrolling when Modal opens

Editable Example

Close Modal on Overlay Click

Editable Example

Modal Sizes

Editable Example

Preserving the scrollbar gap

Editable Example

Making other elements Inert

Accessibility

Keyboard and Focus Management

ARIA

Props

Modal Props

Other components