Modal Dialog

A dialog is a window overlaid on either the primary window or another dialog window

A dialog is a window overlaid on either the primary window or another dialog window. Content behind a modal dialog is inert, meaning that users cannot interact with it.

Import#

Nature UI exports 7 components to help you create any modal dialog.

Modal: This comprises of NatureModal, ModalOverlay, ModalContent, ModalHeader, ModalFooter, ModalBody, ModalCloseButton with matching prop values.
NatureModal: 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 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,
  ModalFooter,
  ModalBody,
  ModalCloseButton,
} from "@nature-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 elements, focus is set on ModalContent.

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

  return (
    <>
      <Button className="bg-purple-500" onClick={onOpen}>
        Open
      </Button>

      <Modal
        variant="blur"
        isOpen={isOpen}
        onClose={onClose}
        title={"Welcome Home"}
        isCentered
        footer={
          <>
            <Button onClick={onClose} className="mr-3">
              Cancel
            </Button>
            <Button className="text-purple-500 hover:bg-purple-100">
              Save
            </Button>
          </>
        }
      >
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed suscipit,
        ligula sit amet pharetra accumsan, nulla augue fermentum dui, eget
        finibus diam sapien eget nisi. Fusce posuere tempus cursus. Nulla cursus
        dapibus ligula, sit amet facilisis libero
      </Modal>
    </>
  );
}

Composition#

function Composition() {
  const { isOpen, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button className="bg-purple-500" onClick={onOpen}>
        Open Modal
      </Button>
      <NatureModal isOpen={isOpen} onClose={onClose}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>Modal Title</ModalHeader>
          <ModalCloseButton />
          <ModalBody>
            <Lorem count={2} />
          </ModalBody>

          <ModalFooter>
            <Button className="bg-purple-500" mr={3} onClick={onClose}>
              Close
            </Button>
            <Button className="text-purple-500">Secondary Action</Button>
          </ModalFooter>
        </ModalContent>
      </NatureModal>
    </>
  );
}

Remove background blur#

Set variant prop to normal on the Modal component to remove background blur.

function BasicUsage() {
  const { isOpen, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button className="bg-purple-500" onClick={onOpen}>
        Open Modal
      </Button>

      <Modal
        variant="normal"
        isOpen={isOpen}
        onClose={onClose}
        title={"Welcome Home"}
        isCentered
        footer={
          <>
            <Button onClick={onClose} className="mr-3 bg-purple-500">
              Cancel
            </Button>
            <Button className="text-purple-500">Save</Button>
          </>
        }
      >
        Hey there!
      </Modal>
    </>
  );
}

With Sizes#

The size prop accepts one of xs, sm, md, lg, xl or full.

function DrawerExample() {
  const sizes = ["xs", "sm", "md", "lg", "full"];
  const { isOpen, onOpen, onClose } = useDisclosure();
  const [size, setSize] = React.useState(sizes[0]);

  const btnRef = React.useRef();

  return (
    <>
      <Button ref={btnRef} className="bg-purple-500" onClick={onOpen}>
        Open
      </Button>

      <RadioGroup defaultValue={size} onChange={setSize}>
        <Stack row className="mt-4">
          {sizes.map((size) => (
            <Radio key={size} value={size}>
              {size}
            </Radio>
          ))}
        </Stack>
      </RadioGroup>
      <Modal
        variant="blur"
        scrollBehavior="outside"
        isOpen={isOpen}
        size={size}
        onClose={onClose}
        footer={
          <>
            <Button onClick={onClose} className="mr-3 text-purple-500">
              Cancel
            </Button>
            <Button className="bg-red-500">Save</Button>
          </>
        }
        title="Welcome Home"
      >
        Sit nulla est ex deserunt exercitation anim occaecat. Nostrud ullamco
        deserunt aute id consequat veniam incididunt duis in sint irure nisi.
        Mollit officia cillum Lorem ullamco minim nostrud elit officia tempor
        esse quis. Sit nulla est ex deserunt exercitation anim occaecat. Nostrud
        ullamco deserunt aute id consequat veniam incididunt duis in sint irure
        nisi. Mollit officia cillum Lorem ullamco minim nostrud elit officia
        tempor esse quis. Sit nulla est ex deserunt exercitation anim occaecat.
        Nostrud ullamco deserunt aute id consequat veniam incididunt duis in
        sint irure nisi. Mollit officia cillum Lorem ullamco minim nostrud elit
        officia
      </Modal>
    </>
  );
}

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

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

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

      <Button mt={4} className="bg-purple-500" onClick={onOpen}>
        Open Modal
      </Button>
      <Modal
        title="Modal Title"
        variant="normal"
        finalFocusRef={finalRef}
        isOpen={isOpen}
        onClose={onClose}
        footer={
          <>
            <Button onClick={onClose} className="mr-3 bg-red-500">
              Close
            </Button>
            <Button className="text-purple-500">Secondary Action</Button>
          </>
        }
      >
        <Lorem size={5} />
      </Modal>
    </>
  );
}

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

function BasicUsage() {
  const { isOpen, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button className="bg-purple-500" onClick={onOpen}>
        Open Modal
      </Button>

      <NatureModal onClose={onClose} isOpen={isOpen} blockScrollOnMount={false}>
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>Modal Title</ModalHeader>
          <ModalCloseButton />
          <ModalBody>
            <Lorem size={5} />
          </ModalBody>
          <ModalFooter>
            <Button onClick={onClose} className="bg-purple-500 text-white">
              Close
            </Button>
          </ModalFooter>
        </ModalContent>
      </NatureModal>
    </>
  );
}

Focus on specific element#

Nature UI automatically sets focus on the first tabbable element in the modal. However, there might be scenarios where you need to manually control where focus goes.

Nature UI provides 2 props for this use case:

initialFocusRef: The ref of the component that receives focus when the modal opens.
finalFocusRef: The ref of the component that receives focus when the modal closes.

If you set finalFocusRef, internally we set returnFocusOnClose to false so it doesn't return focus to the element that triggered it.

function InitialFocus() {
  const { isOpen, onOpen, onClose } = useDisclosure();

  const initialRef = React.useRef();
  const finalRef = React.useRef();

  return (
    <>
      <Button onClick={onOpen} className="bg-purple-500">
        Open Modal
      </Button>
      <Button className={"ml-4 text-purple-500"} ref={finalRef}>
        I'll receive focus on close
      </Button>

      <NatureModal
        initialFocusRef={initialRef}
        finalFocusRef={finalRef}
        isOpen={isOpen}
        onClose={onClose}
      >
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>Create your account</ModalHeader>
          <ModalCloseButton />
          <ModalBody className="pb-6">
            <FormControl>
              <FormLabel>First name</FormLabel>
              <Input ref={initialRef} placeholder="First name" />
            </FormControl>

            <FormControl className={"mt-4"}>
              <FormLabel>Last name</FormLabel>
              <Input placeholder="Last name" />
            </FormControl>
          </ModalBody>

          <ModalFooter>
            <Button className="bg-purple-500" mr={3}>
              Save
            </Button>
            <Button onClick={onClose} className="text-purple-500">
              Cancel
            </Button>
          </ModalFooter>
        </ModalContent>
      </NatureModal>
    </>
  );
}

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

function BasicUsage() {
  const { isOpen, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button onClick={onOpen} className="bg-purple-500">
        Open Modal
      </Button>

      <NatureModal
        closeOnOverlayClick={false}
        isOpen={isOpen}
        onClose={onClose}
      >
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>Modal Title</ModalHeader>
          <ModalCloseButton />
          <ModalBody>
            <h3 className="font-bold mb-4">
              Close on overlay click is disabled.
            </h3>
            <Lorem count={2} />
          </ModalBody>

          <ModalFooter>
            <Button className="bg-purple-500 mr-3" onClick={onClose}>
              Close
            </Button>
            <Button className="bg-purple-500">Secondary Action</Button>
          </ModalFooter>
        </ModalContent>
      </NatureModal>
    </>
  );
}

By default the modal has a vertical offset of 3.75rem which you can change by passing top to the ModalContent. If you need to vertically center the modal, pass the isCentered prop.

If the content within the modal overflows beyond the viewport, don't use this prop. Try setting the overflow behavior instead.

function VerticallyCentered() {
  const { isOpen, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button onClick={onOpen} className="bg-purple-500">
        Open Modal
      </Button>

      <Modal
        isCentered
        isOpen={isOpen}
        onClose={onClose}
        title="Modal Title"
        footer={
          <>
            <Button className="mr-3 text-purple-500" onClick={onClose}>
              Close
            </Button>
            <Button className="bg-purple-500">Secondary Action</Button>
          </>
        }
      >
        <h3 className="font-bold mb-4">Close on overlay click is disabled.</h3>
        <Lorem count={2} />
      </Modal>
    </>
  );
}

Changing the transition#

The Modal comes with a scale transition by default but you can change it by passing a motionPreset prop, and set its value to either slideInBottom, slideInRight, scale or none.

function TransitionExample() {
  const { isOpen, onOpen, onClose } = useDisclosure();

  return (
    <>
      <Button onClick={onOpen} className="bg-purple-500">
        Trigger modal
      </Button>
      <NatureModal
        isOpen={isOpen}
        onClose={onClose}
        motionPreset="slideInBottom"
        isCentered
      >
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>Create your account</ModalHeader>
          <ModalCloseButton />
          <ModalBody className="pb-6">
            <Lorem count={2} />
          </ModalBody>

          <ModalFooter>
            <Button className="bg-purple-500" mr={3}>
              Save
            </Button>
            <Button className="text-purple-500" onClick={onClose}>
              Cancel
            </Button>
          </ModalFooter>
        </ModalContent>
      </NatureModal>
    </>
  );
}

If the content within the modal overflows beyond the viewport, you can use the scrollBehavior to control how scrolling should happen.

If set to inside, scroll only occurs within the ModalBody.
If set to outside, the entire ModalContent will scroll within the viewport.

function ScrollingExample() {
  const { isOpen, onOpen, onClose } = useDisclosure();
  const [scrollBehavior, setScrollBehavior] = React.useState("inside");

  const btnRef = React.useRef();
  return (
    <>
      <RadioGroup value={scrollBehavior} onChange={setScrollBehavior}>
        <Stack row>
          <Radio value="inside">inside</Radio>
          <Radio value="outside">outside</Radio>
        </Stack>
      </RadioGroup>

      <Button className={"mt-3 bg-purple-500"} ref={btnRef} onClick={onOpen}>
        Trigger modal
      </Button>

      <NatureModal
        onClose={onClose}
        finalFocusRef={btnRef}
        isOpen={isOpen}
        scrollBehavior={scrollBehavior}
      >
        <ModalOverlay />
        <ModalContent>
          <ModalHeader>Modal Title</ModalHeader>
          <ModalCloseButton />
          <ModalBody>
            <Lorem size={5} />
            <Lorem size={5} />
          </ModalBody>
          <ModalFooter>
            <Button onClick={onClose} className="bg-purple-500">
              Close
            </Button>
          </ModalFooter>
        </ModalContent>
      </NatureModal>
    </>
  );
}

Making other elements Inert#

When the modal is open, it's rendered within a portal and all its 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.

Prevent focus trapping#

By default the modal, alert dialog and drawer locks the focus inside them. Normally this is what you want to maintain accessibility standards.

While strongly discourage this use case due to it's accessibility impacts, there are certain situations where you might not want the modal to trap focus.

To prevent focus trapping, pass trapFocus and set it's value to false.

Accessibility#

Keyboard and Focus Management#

When the modal opens, focus is trapped within it.
When the modal opens, focus is automatically set to the first enabled element, 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.
The modal is rendered in a portal attached 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 ModalHeader
The ModalContent has aria-describedby set to the id of the ModalBody

Props#

Name	Type	Default	Description
isOpen	`boolean`		If `true`, the modal will open
size	`xs`	`xs`, `sm`, `md`, `lg`, `xl`, `full`
onClose	`(event, reason) => void`		Callback invoked to close the modal.
isCentered	`boolean`		If `true`, the `Modal` will be centered on screen
initialFocusRef	`React.Ref`		The least destructive action to get focus when dialog is open
finalFocusRef	`React.Ref`		The least destructive action to get focus when dialog is open
blockScrollOnMount	`boolean`	`true`	If `true`, scrolling will be disabled on the `body` when the modal opens.
useInert	`boolean`	`true`	A11y: If `true`, the siblings of 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.
scrollBehavior	`inside`, `outside`	`outside`	Where scroll behaviour should originate.
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 top-level `id` to use for the modal and it's sub-components
motionPreset	`MotionPreset`	`scale`	The transition that should be used for the modal

Other components#

ModalCloseButton composes CloseButton