Drawer
A drawer is a panel that slides in from the right side of the screen. The Drawer is overlayed on top of the main area of the page to capture the users attention while keeping the context of the current task.
import { ... } from '@ag.ds-next/react/drawer';
() => { const [isDrawerOpen, openDrawer, closeDrawer] = useTernaryState(false); return ( <React.Fragment> <Button onClick={openDrawer}>Open Drawer</Button> <Drawer isOpen={isDrawerOpen} onDismiss={closeDrawer} title="Drawer title" actions={ <ButtonGroup> <Button onClick={closeDrawer}>Primary</Button> <Button variant="secondary" onClick={closeDrawer}> Secondary </Button> <Button variant="tertiary" onClick={closeDrawer}> Tertiary </Button> </ButtonGroup> } > <Text as="p">Drawer body area.</Text> </Drawer> </React.Fragment> ); };
Do
- read the Search filters pattern
- use a Button group to display actions
- include a "Close" button in the top right
- include a meaningful title - e.g. "Filter by"
- optionally close the Drawer when an action button is pressed
Don't
- remove the "Close" button
- remove the overlay
- change default behaviour
Opening the Drawer
The Drawer can be opened by pressing a button or a link. For example, pressing a 'Show filter' button opens a medium Drawer containing filters.
When the Drawer is opened, an overlay is displayed over the main area of the page. This prevents the main area of the page from being interacted with, while still allowing users to maintain their context.
Closing the Drawer
The Drawer can be closed by either:
- Pressing the "Close" button
- Pressing the "Escape" key
- Pressing the overlay
- Pressing a button in the actions area (optional)
When closing the Drawer, focus should be returned to the button that opened the Drawer.
Drawer widths
The Drawer comes in the following 2 widths:
- Medium
md
(512px) - generally used to display form fields like filters. This width is the minimum required to stack form fields, including date range fields. - Large
lg
(720px) - generally used to display body text like help or guidance content. This width accommodates the Prose component, which has an optimal line length to aid readability.
() => { const [isDrawerOpen, openDrawer, closeDrawer] = useTernaryState(false); return ( <React.Fragment> <Button onClick={openDrawer}>Open Medium Drawer</Button> <Drawer isOpen={isDrawerOpen} onDismiss={closeDrawer} title="Medium Drawer" actions={ <ButtonGroup> <Button onClick={closeDrawer}>Primary</Button> <Button variant="secondary" onClick={closeDrawer}> Secondary </Button> <Button variant="tertiary" onClick={closeDrawer}> Tertiary </Button> </ButtonGroup> } > <Select label="Example filter" placeholder="Please select" options={[ { value: 'a', label: 'Option A' }, { value: 'b', label: 'Option B' }, { value: 'c', label: 'Option C' }, ]} hideOptionalLabel block /> </Drawer> </React.Fragment> ); };
() => { const [isDrawerOpen, openDrawer, closeDrawer] = useTernaryState(false); return ( <React.Fragment> <Button onClick={openDrawer}>Open Large Drawer</Button> <Drawer isOpen={isDrawerOpen} onDismiss={closeDrawer} title="Large Drawer" width="lg" actions={ <ButtonGroup> <Button onClick={closeDrawer}>Primary</Button> <Button variant="secondary" onClick={closeDrawer}> Secondary </Button> <Button variant="tertiary" onClick={closeDrawer}> Tertiary </Button> </ButtonGroup> } > <Prose> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas cursus risus nec velit imperdiet, sit amet blandit libero ullamcorper. Maecenas vel fermentum sapien. Aenean mollis tincidunt imperdiet. Morbi efficitur consectetur quam nec aliquam. Quisque id consequat arcu, hendrerit vulputate libero. Morbi et libero placerat, ultrices lacus pulvinar, maximus massa. Nam tempor eu nisl dignissim malesuada. Quisque blandit turpis vel egestas posuere. </p> <p> Integer nec ex massa. Integer at semper enim. Vestibulum elit tortor, ultricies quis lectus elementum, tempor pharetra ex. In ut nulla vitae neque vehicula venenatis. Pellentesque faucibus eget tortor ac venenatis. Proin et vulputate nunc. Etiam vitae dui pellentesque, sollicitudin dolor congue, imperdiet mauris. Aliquam a massa magna. Suspendisse condimentum sapien id nisi luctus accumsan. Cras maximus sapien et lorem malesuada, et euismod mauris tincidunt. Nulla facilisi. Donec ultricies eros eget lobortis aliquam. Sed cursus ipsum et mauris sodales semper eget vel diam. Nulla tincidunt rutrum ipsum in molestie. In hac habitasse platea dictumst. </p> </Prose> </Drawer> </React.Fragment> ); };
Related components
- Modal – A modal is a dialog box that appears above the parent page and provides advance notice of a destructive action and consequence. They tell users a decision is needed.
Related patterns
- Search filters – Search filters help users find what they're looking for by displaying options that meet specified criteria.