If true
, the modal will be open.
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.
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><DrawerisOpen={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><DrawerisOpen={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><Inputref={firstField}id='username'placeholder='Please enter user name'/></Box><Box><FormLabel htmlFor='url'>Url</FormLabel><InputGroup><InputLeftAddon>http://</InputLeftAddon><Inputtype='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('md')const { isOpen, onOpen, onClose } = useDisclosure()const handleClick = (newSize) => {setSize(newSize)onOpen()}const sizes = ['xs', 'sm', 'md', 'lg', 'xl', 'full']return (<>{sizes.map((size) => (<ButtononClick={() => handleClick(size)}key={size}m={4}>{`Open ${size} Drawer`}</Button>))}<Drawer onClose={onClose} isOpen={isOpen} size={size}><DrawerOverlay /><DrawerContent><DrawerHeader>{`${size} drawer contents`}</DrawerHeader><DrawerBody>{size === 'full'? `You're trapped 😆 , refresh the page to leave or press 'Esc' key.`: null}</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 theid
of theform
.
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><formid='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 assignedref
. - 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:
isOpen
required
isOpen
required
boolean
onClose
required
onClose
required
Callback invoked to close the modal.
() => void
allowPinchZoom
allowPinchZoom
Handle zoom/pinch gestures on iOS devices when scroll locking is enabled.
Defaults to false
.
boolean
autoFocus
autoFocus
If true
, the modal will autofocus the first enabled and interactive
element within the ModalContent
boolean
true
blockScrollOnMount
blockScrollOnMount
If true
, scrolling will be disabled on the body
when the modal opens.
boolean
true
closeOnEsc
closeOnEsc
If true
, the modal will close when the Esc
key is pressed
boolean
true
closeOnOverlayClick
closeOnOverlayClick
If true
, the modal will close when the overlay is clicked
boolean
true
colorScheme
colorScheme
Color Schemes for Drawer
are not implemented in the default theme. You can extend the theme to implement them.
string
finalFocusRef
finalFocusRef
The ref
of element to receive focus when the modal closes.
RefObject<FocusableElement>
id
id
The id
of the modal
string
initialFocusRef
initialFocusRef
The ref
of element to receive focus when the modal opens.
RefObject<FocusableElement>
isFullHeight
isFullHeight
If true
and drawer's placement is top
or bottom
,
the drawer will occupy the viewport height (100vh)
boolean
lockFocusAcrossFrames
lockFocusAcrossFrames
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
boolean
onEsc
onEsc
Callback fired when the escape key is pressed and focus is within modal
(() => void)
onOverlayClick
onOverlayClick
Callback fired when the overlay is clicked.
(() => void)
placement
placement
The placement of the drawer
DrawerPlacement
portalProps
portalProps
Props to be forwarded to the portal component
Pick<PortalProps, "appendToParentPortal" | "containerRef">
preserveScrollBarGap
preserveScrollBarGap
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
boolean
returnFocusOnClose
returnFocusOnClose
If true
, the modal will return focus to the element that triggered it when it closes.
boolean
true
size
size
string
"xs"
trapFocus
trapFocus
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.
boolean
true
useInert
useInert
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**
boolean
true
variant
variant
string
Other components#
DrawerOverlay
,DrawerFooter
,DrawerHeader
andDrawerBody
composesBox
componentDrawerCloseButton
composesCloseButton