A drawer presents context-specific information and/or actions without leaving the current page.
- Container: Wraps the content.
- Header: Contains the title, close button, and actions.
- Title: Conveys the purpose of the drawer.
- Close button: Closes the drawer.
- Top-level actions (optional): Buttons or links used to provide explicit action(s) the user can take related to the entire drawer content.
- Content: Contains a wide variety of content types and controls depending on the purpose, related content, and contextual user tasks.
- Contextual actions (optional): Buttons or links used to provide contextual action(s) in relation to the content within the drawer.
When to use
- Display additional or supplemental information to the user about an element or item.
- Make simple, contextual tasks available, for example adding or editing items within forms that would create scrolling or other usability issues if presented inline or in a modal.
When not to use
- If supplemental content isn't suited for small areas or is part of a flow, consider loading a new page or revealing content with an accordion instead.
- A drawer provides contextual information while also keeping the main object in view. If you need to view specific content while only maintaining underlying context, consider using a modal instead.
- To confirm an action, consider using a toast or modal instead.
- The drawer follows the motion guidelines and slides in from the right side of the viewport.
200mswith an ease-in animation.
- By default, the drawer is above all page content.
- If full-width elements exist on the page and you do not want the drawer to cover them then you may specify the drawer to be embedded in the page and push some or all of the content rather than covering it.
- Only one drawer can be open on a page at a time.
- A drawer should never take the user by surprise — let a user’s action open it.
- A drawer can be closed with the close button or the Esc key.
- When content overflows the drawer height, it scrolls vertically under the header.
- If the content is likely to scroll, consider placing contextual action in a fixed footer. Otherwise, contextual actions should always flow inline with the content.
- If the content within the drawer container exceeds the height, then a scrim (gradient overlay) appears at the bottom of the container as an overflow affordance. The scrim is removed when a user has scrolled to the end of the content.
- The drawer maintains its behavior down to the smallest breakpoint, at which point it takes up the full viewport width.
- The drawer should have a width of
- All copy within a drawer should be short, actionable, and use clear language.
- The drawer should utilize the skeleton loader pattern when possible to represent loading content.
- If an empty state is required, please follow the empty-state guidelines.
- If a form is added to the drawer, follow form guidelines when deciding the layout of components, including buttons.
- Left aligned, except in right-to-left languages where the content is right aligned.
- For drawers that show documentation, the content is stored in a markdown file in the
gitlabrepo. For details, see the contribution documentation.
- Be brief and keep it to a single line by utilizing a sentence fragment.
- Avoid using punctuation such as periods, commas, or semicolons.
- Use a full stop only when it's a full sentence.
- Title should use a level 2 (
- Left aligned, except in right-to-left languages where they are right aligned and the order is the same. See button alignment and order for more details.
- Drawer states (expanded/collapsed) should be announced by a screen reader.
- The focus should move to the drawer once opened. An intentional keyboard trap keeps tab order (looped) within the drawer until it is closed. This is so a user cannot focus on anything outside or under the drawer.
- The Esc key should close the drawer along with activating the close icon button.
Last updated at: