A Drawer is a component that provides a space for displaying medium to long-form content. It is designed to present information that may be too lengthy or too specific to be included on the page by default. The content can include a mix of text, HTML elements, or other components, allowing for flexibility in displaying information such as forms, images, links, or lists.

The HelpDrawer extends the Drawer by adding analytics capabilities, which can help track user interactions, making it a great choice for situations where gathering insights on how users engage with help content is important.

Examples

Layout Alternatives

A header and/or footer can have a "sticky" position if the following properties are applied to their respective elements:

• isHeaderSticky
• isFooterSticky

Managing multiple drawers

What do you do when there are multiple drawers on a page? The simplest behavior—which may not be appropriate for all use cases—is that when one drawer opens, any open drawers get closes. While this logic can be written into your application, we have a React component to manage simple drawer behavior.

Code

React

See Storybook "Drawer" page and Storybook "Help Drawer" page for React documentation.

Web Component

See Storybook "Drawer" page for Web Component documentation.

Style customization

The following CSS variables can be overridden to customize Drawer components:

Analytics

This component has analytics tracking available. Please see our developer documentation about using analytics in the design system.

Guidance

When to use

Drawer

• When users need additional information that should remain viewable while they interact with the main page, such as detailed explanations, guidelines, or interactive elements like forms.
• When supplementary, non-time-sensitive information is helpful at a specific point in the user’s journey but does not need to be displayed on the main page. This allows users to access helpful context or additional details at their discretion without interrupting the flow of the main task.
• When optional information is needed to complete a task without overwhelming the primary content on the page.

HelpDrawer

• When you need to track how users interact with the content, such as monitoring how often the drawer is opened or engaged with.

When to Consider Alternatives

• When the information is timely, urgent, or critical to the action being taken. Drawers are intended for supplementary details that users can access at their discretion. For time-sensitive or essential information, consider using more prominent inline elements to ensure users don’t miss it.
• When the information needs to be immediately visible to clarify or support a primary task. Since Drawers require an extra step to open, they are not ideal for essential information that users must see to complete a task or understand other content.
• When the information must be displayed automatically without user initiation. Drawers rely on users selecting a link or button to open them. If content needs to appear automatically, such as onboarding tips or error messages, consider inline options that don’t require user action.

Usage

• Link text used to trigger the Drawer should be specific and descriptive.
  • Avoid using only "Learn more" to link to help Drawer content.
  • Limit the amount of link text.
• Drawer content area should include a close button clearly at the top.
• On larger screens, the Drawer is fixed to the side of the screen, whereas on smaller screens, it overlays the entire screen.

Accessibility

• The Drawer should have an aria-labelledby attribute that references the id of the heading in the Drawer.
• The Drawer markup should be placed after the toggle element that triggers it in the HTML structure. This keeps the markup semantically sound and improves accessibility for screen readers.
• The heading level used within the Drawer should fit semantically with the heading levels of the rest of the page. For instance, if the heading level before the Drawer toggle link is an <h2>, the heading level of the Drawer would most likely be an <h3>.

Focus Management

• Focus should move to the content in the Drawer after the user has opened it.
• The property hasFocusTrap is an available option that will prevent keyboard focus from leaving the confines of the Drawer when enabled.

When hasFocusTrap is enabled...

• Keyboard focus is trapped within the Drawer component.
• Pressing Escape will close the Drawer.

A focus trap should not be used when it's anticipated that the user will rely on the Drawer as a reference resource for doing something outside of the Drawer. For instance, if the user is completing a form, Drawer may contain a reference guide defining specific requirements on the page.However, there are times when it makes sense to trap focus within the Drawer. One occasion where it can benefit the user is when the Drawer is anticipated to fill the viewport of a screen, e.g., in a mobile layout.

Accessibility testing

Keyboard

• I can use Tab to move focus to the Drawer toggle button.
• I can use Enter or Space to toggle the Drawer open or closed.
• When the Drawer is open, I can use Tab to move focus to the close button, then sequentially through the list of focusable items.
• There's a visible focus ring as I move through interactive content in the Drawer, first to the close button, then sequentially through the list of focusable items.
• If hasFocusTrap is enabled, then...
  • ...pressing Escape will close the Drawer.
  • ...I can't move focus outside of the Drawer.
• If hasFocusTrap is not set, then...
  • ...I can move focus outside of the Drawer.

Screen reader

• The Drawer toggle indicates the purpose of the Drawer and mirrors the first heading inside the Drawer.
• When the Drawer is open:
  • Focus is sent to the Drawer.
  • The Drawer's role of dialog is read.
  • The Drawer's first heading element is announced.

Mobile

• Double-tapping the Drawer toggle...
  • ...sends focus to the Drawer.
  • ...reads the Drawer's role of dialog.
  • ...announces the Drawer's first heading element.
• Double-tapping the Drawer's close button sends focus back to the Drawer toggle and the toggle label is read.

Component maturity