Skip to main content
U.S. Flag

An official website of the United States government

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

Code

React

React Properties Documentation
NameTypeDefaultDescription
ariaLabelstringGives more context to screen readers on the Drawer close button.
closeButtonTextReactNode
closeButtonVariationButtonVariation
classNamestring
footerBodyReactNode
footerTitlestring
hasFocusTrapbooleanfalseEnables focus trap functionality within Drawer.
headingrequiredReactNodeText for the Drawer heading. Required because the heading will be focused on mount.
headingIdstringA unique id to be used on heading element to label multiple instances of Drawer.
headingLevel"1" | "2" | "3" | "4" | "5"3Heading type to override default <h3>
headingRefMutableRefObject<any>Ref to heading element
isHeaderStickybooleanEnables "sticky" position of Drawer header element.
isFooterStickybooleanEnables "sticky" position of Drawer footer element.
onCloseClickrequired(event: MouseEvent<Element, MouseEvent> | KeyboardEvent<Element>) => void

<DrawerToggle>

React Properties Documentation
NameTypeDefaultDescription
childrenrequiredReactNodeLabel text or HTML DrawerToggle content.
classNamestringAdditional classes to be added to the root button element. Additional classes for the toggle button anchor element.
disabledboolean
hrefstringWhen provided, the root component will render as an <a> element rather than button.
inputRefButtonRefAccess a reference to the button or a element
isAlternatebooleanApplies the alternate color to a Button. By default, Button uses the main color.
onClick(...args: any[]) => anyReturns the SyntheticEvent. Not called when the Button is disabled.
onDarkbooleanDefines a color palette best used when Button is placed on a dark background-color. By default, Button uses a light color palette.
sizeButtonSize
type"button" | "submit" | "reset"Button type attribute
variationButtonVariationA string corresponding to Button variation classes.
analyticsbooleanAnalytics events tracking is enabled by default. Set this value to false to disable tracking for this component instance.
analyticsLabelOverridestringAn override for the dynamic content sent to analytics services. By default this content comes from the heading. In cases where this component’s heading may contain sensitive information, use this prop to override what is sent to analytics.
analyticsEventTypeOverridestringIf you need the event_type to be overridden for your use case, you can provide an alternate string here. Suggested values can be found in the EventType enum.
onAnalyticsEvent(event: AnalyticsEvent) => voidOptional callback that will intercept analytics events for this component. If none is specified, the design system will use the default analytics function, which can be overwritten globally with setDefaultAnalyticsFunction.
analyticsParentHeadingstringIf needed for analytics, pass heading text of parent component of button.
analyticsParentTypestringIf needed for analytics, pass type of parent component of button.
drawerOpenrequiredbooleanDetermines if Drawer is open or closed. This value is used to re-focus the toggle that opened the drawer when the drawer closes.
inlinebooleanAdds display: inline to the DrawerToggle.
showDrawerrequired(string: any) => anyThis function is called with an id that the toggle generates. It can be used in implementing the Drawer for keeping track of which drawer the toggle controls.

<HelpDrawer>

This component is an enhanced <Drawer> component, providing the same properties as <Drawer> in addition to Google Analytics properties.

React Properties Documentation
NameTypeDefaultDescription
ariaLabelstringGives more context to screen readers on the Drawer close button.
closeButtonTextReactNode
closeButtonVariationButtonVariation
classNamestring
footerBodyReactNode
footerTitlestring
hasFocusTrapbooleanEnables focus trap functionality within Drawer.
headingrequiredReactNodeText for the Drawer heading. Required because the heading will be focused on mount.
headingIdstringA unique id to be used on heading element to label multiple instances of Drawer.
headingLevel"1" | "2" | "3" | "4" | "5"Heading type to override default <h3>
headingRefMutableRefObject<any>Ref to heading element
isHeaderStickybooleanEnables "sticky" position of Drawer header element.
isFooterStickybooleanEnables "sticky" position of Drawer footer element.
onCloseClickrequired(event: MouseEvent<Element, MouseEvent> | KeyboardEvent<Element>) => void
analyticsbooleanAnalytics events tracking is enabled by default. Set this value to false to disable tracking for this component instance.
analyticsLabelOverridestringAn override for the dynamic content sent to analytics services. By default this content comes from the heading. In cases where this component’s heading may contain sensitive information, use this prop to override what is sent to analytics.
analyticsEventTypeOverridestringIf you need the event_type to be overridden for your use case, you can provide an alternate string here. Suggested values can be found in the EventType enum.
onAnalyticsEvent(event: AnalyticsEvent) => voidOptional callback that will intercept analytics events for this component. If none is specified, the design system will use the default analytics function, which can be overwritten globally with setDefaultAnalyticsFunction.

Focus Trap

A focus trap can be set on a drawer if the property hasFocusTrap is enabled. A user can escape the focus trap by pressing the ESC key.

Styles

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-primary-alt-lightest
--drawer-toggle__background-color--hoverhex value: #02bfe7--color-focus-inverse
--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-dark

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 views/interacts 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

  • Focus should move to the content in the help drawer after the user has opened it.
  • Drawer should support keyboard navigation.
    • Enter and Space to select the highlighted item.
    • Tab to move the focus sequentially through the list of focusable items
    • Shift + Tab to move the focus sequentially through the list of focusable items in reversed order

Focus Management

The property hasFocusTrap is an available option that will prevent keyboard focus from leaving the confines of the HelpDrawer when enabled.

When the property hasFocusTrap is enabled...

  • Keyboard focus is trapped within the HelpDrawer component.
  • Pressing the escape key 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.

However, there are times when it makes sense to trap focus within the Drawer. One occassion where it can benefit the user is when the Drawer is anticipated to fill the viewport of a screen, i.e., mobile layout.

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