# 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. ## Guidance **Theme: medicare only** - All help drawer links will include a help icon with the link to indicate the link is a help option. ### 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. - To present information that may be too lengthy or too specific to be included on the page by default. - 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. ### Guidelines `Drawer` - A Drawer is a component that provides a space for displaying medium to long-form content. - 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. - The `Drawer` content area should include a close button clearly at the top. `Help Drawer` - The `HelpDrawer` extends the `Drawer` by adding analytics capabilities, which can help track user interactions. - (Medicare only) All `HelpDrawer` links will include a help icon with the link to indicate the link is a help option. ### 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](/storybook/?path=/docs/components-drawermanager--docs). ### When to Consider Alternatives - When the information is timely, urgent, or critical to the action being taken, use an Alert; 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, such as in-line errors. - When the information needs to be immediately visible to clarify or support a primary task, use an Alert. 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. ### Display & behavior - On larger screens, the Drawer is fixed to the side of the screen, whereas on smaller screens, it overlays the entire screen. - Content within the Drawer can include a mix of text, HTML elements, or other components, allowing for flexibility in displaying information such as forms, images, links, or lists. ### 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 `

`, the heading level of the `Drawer` would most likely be an `

`. #### 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 example, if the user is completing a form, the Drawer may contain a reference guide defining specific requirements on the page. - 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. ```js const helpDrawerTriggerText = "Get help with costs"; {}} triggerButtonText={helpDrawerTriggerText} > {/* Drawer content goes here */} ```