Drawer

The Drawer component is a panel that slides out from the edge of the screen. It can be useful when you need users to complete a task or view some details without leaving the current page.

View sourceView theme source@chakra-ui/modal

Import

import {
  Drawer,
  DrawerBody,
  DrawerFooter,
  DrawerHeader,
  DrawerOverlay,
  DrawerContent,
  DrawerCloseButton,
} from "@chakra-ui/react";

Usage

Basic Drawer

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

  return (
    <>
      <Button ref={btnRef} colorScheme="teal" onClick={onOpen}>
        Open
      </Button>
      <Drawer
        isOpen={isOpen}
        placement="right"
        onClose={onClose}
        finalFocusRef={btnRef}
      >
        <DrawerOverlay />
        <DrawerContent>
          <DrawerCloseButton />
          <DrawerHeader>Create your account</DrawerHeader>

          <DrawerBody>
            <Input placeholder="Type here..." />
          </DrawerBody>

          <DrawerFooter>
            <Button variant="outline" mr={3} onClick={onClose}>
              Cancel
            </Button>
            <Button colorScheme="blue">Save</Button>
          </DrawerFooter>
        </DrawerContent>
      </Drawer>
    </>
  );
}

Drawer placement

The Drawer can appear from any edge of the screen. Pass the placement prop and set it to top, right, bottom, or left.

function PlacementExample() {
  const { isOpen, onOpen, onClose } = useDisclosure();
  const [placement, setPlacement] = React.useState("right");

  return (
    <>
      <RadioGroup defaultValue={placement} onChange={setPlacement}>
        <Stack direction="row" mb="4">
          <Radio value="top">Top</Radio>
          <Radio value="right">Right</Radio>
          <Radio value="bottom">Bottom</Radio>
          <Radio value="left">Left</Radio>
        </Stack>
      </RadioGroup>
      <Button colorScheme="blue" onClick={onOpen}>
        Open
      </Button>
      <Drawer placement={placement} onClose={onClose} isOpen={isOpen}>
        <DrawerOverlay />
        <DrawerContent>
          <DrawerHeader borderBottomWidth="1px">Basic Drawer</DrawerHeader>
          <DrawerBody>
            <p>Some contents...</p>
            <p>Some contents...</p>
            <p>Some contents...</p>
          </DrawerBody>
        </DrawerContent>
      </Drawer>
    </>
  );
}

Focus on specific element

When a form is in the drawer, you might need to set focus on a specific element when the drawer opens. Pass the initialFocusRef prop.

Without the initialFocusRef prop, the drawer will set focus on the first focusable element when it opens.

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

  return (
    <>
      <Button leftIcon={<AddIcon />} colorScheme="teal" onClick={onOpen}>
        Create user
      </Button>
      <Drawer
        isOpen={isOpen}
        placement="right"
        initialFocusRef={firstField}
        onClose={onClose}
      >
        <DrawerOverlay />
        <DrawerContent>
          <DrawerCloseButton />
          <DrawerHeader borderBottomWidth="1px">
            Create a new account
          </DrawerHeader>

          <DrawerBody>
            <Stack spacing="24px">
              <Box>
                <FormLabel htmlFor="username">Name</FormLabel>
                <Input
                  ref={firstField}
                  id="username"
                  placeholder="Please enter user name"
                />
              </Box>

              <Box>
                <FormLabel htmlFor="url">Url</FormLabel>
                <InputGroup>
                  <InputLeftAddon>http://</InputLeftAddon>
                  <Input
                    type="url"
                    id="url"
                    placeholder="Please enter domain"
                  />
                  <InputRightAddon>.com</InputRightAddon>
                </InputGroup>
              </Box>

              <Box>
                <FormLabel htmlFor="owner">Select Owner</FormLabel>
                <Select id="owner" defaultValue="segun">
                  <option value="segun">Segun Adebayo</option>
                  <option value="kola">Kola Tioluwani</option>
                </Select>
              </Box>

              <Box>
                <FormLabel htmlFor="desc">Description</FormLabel>
                <Textarea id="desc" />
              </Box>
            </Stack>
          </DrawerBody>

          <DrawerFooter borderTopWidth="1px">
            <Button variant="outline" mr={3} onClick={onClose}>
              Cancel
            </Button>
            <Button colorScheme="blue">Submit</Button>
          </DrawerFooter>
        </DrawerContent>
      </Drawer>
    </>
  );
}

Drawer Widths

Pass the size prop if you need to adjust the size of the drawer. Values can be xs, sm, md, lg, xl, or full.

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

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

  const sizes = ["xs", "sm", "md", "lg", "xl", "full"];

  return (
    <>
      {sizes.map((size) => (
        <Button
          onClick={() => handleClick(size)}
          key={size}
          m={4}
        >{`Open ${size} Drawer`}</Button>
      ))}

      <Drawer onClose={onClose} isOpen={isOpen} size={size}>
        <DrawerOverlay />
        <DrawerContent>
          <DrawerCloseButton />
          <DrawerHeader>{`${size} drawer contents`}</DrawerHeader>
          <DrawerBody>
            <p>
              Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
              eiusmod tempor incididunt ut labore et dolore magna aliqua.
              Consequat nisl vel pretium lectus quam id. Semper quis lectus
              nulla at volutpat diam ut venenatis. Dolor morbi non arcu risus
              quis varius quam quisque. Massa ultricies mi quis hendrerit dolor
              magna eget est lorem. Erat imperdiet sed euismod nisi porta.
              Lectus vestibulum mattis ullamcorper velit.
            </p>
          </DrawerBody>
        </DrawerContent>
      </Drawer>
    </>
  );
}

Using a form in a Drawer

If you need to put a form within the Drawer, you might need to use to form validation library like react-hook-form or formik. Here's the recommended way to do it:

Because the button is located outside the form, you can leverage its native HTML form attribute and refer to the id of the form.

export const App = () => { const { isOpen, onOpen, onClose } = useDisclosure(); return ( <> <Button onClick={onOpen}>Open</Button> <Drawer isOpen={isOpen} onClose={onClose}> <DrawerOverlay /> <DrawerContent> <DrawerCloseButton /> <DrawerHeader>Create your account</DrawerHeader> <DrawerBody> <form id="my-form" onSubmit={(e) => { e.preventDefault(); console.log("submitted"); }} > <Input name="nickname" placeholder="Type here..." /> </form> </DrawerBody> <DrawerFooter> <Button type="submit" form="my-form"> Save </Button> </DrawerFooter> </DrawerContent> </Drawer> </> ); };

export const App = () => {
  const { isOpen, onOpen, onClose } = useDisclosure();
  return (
    <>
      <Button onClick={onOpen}>Open</Button>
      <Drawer isOpen={isOpen} onClose={onClose}>
        <DrawerOverlay />
        <DrawerContent>
          <DrawerCloseButton />
          <DrawerHeader>Create your account</DrawerHeader>

          <DrawerBody>
            <form
              id="my-form"
              onSubmit={(e) => {
                e.preventDefault();
                console.log("submitted");
              }}
            >
              <Input name="nickname" placeholder="Type here..." />
            </form>
          </DrawerBody>

          <DrawerFooter>
            <Button type="submit" form="my-form">
              Save
            </Button>
          </DrawerFooter>
        </DrawerContent>
      </Drawer>
    </>
  );
};

Accessibility

• When opening the Drawer, focus is trapped inside the Drawer.
• By default, the drawer sets focus on the first focusable element. If the initialFocusRef prop is passed, the drawer sets focus on the element with the assigned ref.
• After the drawer closes, it'll return focus to the element that triggered it.

Props

Drawer Props

Drawer composes the Modal component with these extra props:

isOpenrequired

Description

If true, the modal will be open.

Type

boolean

onCloserequired

Description

Callback invoked to close the modal.

Type

() => void

allowPinchZoom

Description

Handle zoom/pinch gestures on iOS devices when scroll locking is enabled.

Type

boolean

Default

false.

autoFocus

Description

If true, the modal will autofocus the first enabled and interactive element within the ModalContent

Type

boolean

Default

true

blockScrollOnMount

Description

If true, scrolling will be disabled on the body when the modal opens.

Type

boolean

Default

true

closeOnEsc

Description

If true, the modal will close when the Esc key is pressed

Type

boolean

Default

true

closeOnOverlayClick

Description

If true, the modal will close when the overlay is clicked

Type

boolean

Default

true

colorScheme

Description

Color Schemes for Drawer are not implemented in the default theme. You can extend the theme to implement them.

Type

string

finalFocusRef

Description

The ref of element to receive focus when the modal closes.

Type

RefObject<FocusableElement>

id

Description

The id of the modal

Type

string

initialFocusRef

Description

The ref of element to receive focus when the modal opens.

Type

RefObject<FocusableElement>

isFullHeight

Description

If true and drawer's placement is top or bottom, the drawer will occupy the viewport height (100vh)

Type

boolean

lockFocusAcrossFrames

Description

Enables aggressive focus capturing within iframes. - If true: keep focus in the lock, no matter where lock is active - If false: allows focus to move outside of iframe

Type

boolean

onCloseComplete

Description

Fires when all exiting nodes have completed animating out

Type

(() => void)

onEsc

Description

Callback fired when the escape key is pressed and focus is within modal

Type

(() => void)

onOverlayClick

Description

Callback fired when the overlay is clicked.

Type

(() => void)

placement

Description

The placement of the drawer

Type

DrawerPlacement

Default

"right"

portalProps

Description

Props to be forwarded to the portal component

Type

Pick<PortalProps, "appendToParentPortal" | "containerRef">

preserveScrollBarGap

Description

If true, a `padding-right` will be applied to the body element that's equal to the width of the scrollbar. This can help prevent some unpleasant flickering effect and content adjustment when the modal opens

Type

boolean

returnFocusOnClose

Description

If true, the modal will return focus to the element that triggered it when it closes.

Type

boolean

Default

true

size

Type

"xs" | "sm" | "md" | "lg" | "xl" | "full"

Default

"xs"

trapFocus

Description

If false, focus lock will be disabled completely. This is useful in situations where you still need to interact with other surrounding elements. 🚨Warning: We don't recommend doing this because it hurts the accessibility of the modal, based on WAI-ARIA specifications.

Type

boolean

Default

true

useInert

Description

A11y: If true, the siblings of the modal will have `aria-hidden` set to true so that screen readers can only see the modal. This is commonly known as making the other elements **inert**

Type

boolean

Default

true

variant

Description

Variants for Drawer are not implemented in the default theme. You can extend the theme to implement them.

Type

string

Other components

• DrawerOverlay, DrawerFooter, DrawerHeader and DrawerBody composes Box component
• DrawerCloseButton composes CloseButton