Skip to main content

An official website of the United States government

Here's how you know

An official website of the United States government

Here's how you know

Theme:

Design system switcher

Version:

Design system switcher

Theme:

Design system switcher

Version:

Design system switcher

Drawer & Help Drawer

A drawer provides a space for medium to long-form help content — content that's too long or not common enough to warrant being on the page by default.

On large screens it's fixed to the side of the screen, and on smaller screens it overlays the entire screen.

Render the drawer below the toggle button that triggers it. This way the markup remains semantically sound and screen reader friendly.

Examples

Loading

Layout Alternatives

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

  • isHeaderSticky
  • isFooterSticky
Loading

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.

Style customization

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

CSS variables for drawer
VariableDefault Core Theme Value
--drawer__animation-timing0.3s
--drawer__background-colorhex value: #ffffff--color-white
--drawer__border-colorhex value: #d9d9d9--color-border
--drawer-close__colorhex value: #000000--color-black
--drawer-header__background-colorhex value: #f2f2f2--color-gray-lightest
--drawer-footer__background-colorhex value: #e6f9fd--color-info-lightest
--drawer-toggle__background-color--hoverhex value: #02bfe7--color-info
--drawer-toggle__color--hoverhex value: #ffffff--color-white
--drawer-toggle__background-color--hover--inversehex value: #ffffff--color-white
--drawer-toggle__color--hover--inversehex value: #404040--color-gray-darker

Analytics

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

Guidance

When to use

  • When users need content to remain viewable while also allowing the user to view and/or interact with the main page.
  • When the content is longer than 2 sentences.
  • When the content needs to be available at a particular point in the process, but doesn't need to be included on the main page.
  • When the content just needs to be available at the user's discretion, to provide additional details or context.
  • When users may need additional information to complete the task than can be supplied on the main page without overwhelming the primary content.

When to consider alternatives

  • When the content is timely/urgent, or critical to the action being taken.
  • When the content is intended to clarify or call attention to other content on the page.
  • When the content must be displayed without being initiated by a user action.
  • When additional information is necessary to the primary information the user is interacting with.

Usage

  • Link text used to trigger the help 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.

Accessibility

  • Drawer should have an aria-labelledby attribute that references the id of heading in the Drawer.
  • 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

For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.

Accessibility

  • Color

    Meets AA color contrast standards for accessibility and color blindness.
    Complete
  • Forced Colors Mode (FCM)

    While using FCM the components text is legible and improves readability.
    Complete
  • WCAG 2.1 Level AA Conformance

    All Axe checks for WCAG AA compliance have passed.
    Complete
  • Screen readers

    VoiceOver, NVDA, and JAWS screen readers provide concise communication and interaction.
    Complete
  • Keyboard navigation

    Component is fully navigable with a keyboard.
    Complete

Code

  • Storybook

    Component has stories to cover all defined props.
    Complete
  • Responsive

    Component designed to work in all responsive breakpoints.
    Complete
  • Spanish translations

    Includes Spanish translations for default text content.
    Complete

Tokens

  • Code

    Tokens implemented in code.
    Complete
  • Design

    Tokens implemented in the Sketch.
    Complete