Dismiss button component for accessible modal dismissal
npm install @bento/dismissimport {
Meta,
Story,
ArgTypes,
Controls,
Source,
} from '@storybook/addon-docs/blocks';
The @bento/dismiss package provides an accessible, visually hidden dismissal
control for overlays and popup content. It ensures users, especially those using
screen readers, can reliably dismiss modal dialogs, drawers, and popovers
through linear keyboard navigation. This component complements ESC key handling
and outside-click behaviors, filling a critical accessibility gap when sighted
users have a visible close button but screen reader users navigating linearly
encounter no dismissal affordance.
This primitive aligns with React Aria's DismissButton pattern and should be
positioned at both the start and end of dismissible overlay content. When a
screen reader user navigates forward or backward through an overlay, they will
encounter these controls, giving them a clear way to exit the overlay without
relying solely on the ESC key or outside-click patterns that may not be
discoverable through linear navigation.
``shell`
npm install --save @bento/dismiss
The @bento/dismiss package exports the Dismiss component:
`jsx
import { Dismiss } from '@bento/dismiss';
`
The following properties are available to be used on the Dismiss component:
| Prop | Type | Required | Description |
|------|------|----------|------------|
| onDismiss | () => void | No | Called when the dismiss button is activated. |ariaLabel
| | string | No | Accessible label for the dismiss button. Should be localized. |children
| | ReactNode | No | The content to render inside the container. |slots
| | { hidden?: ((args: { props: Record | No | Optional slot to customize the VisuallyHidden wrapper.slot
An object that contains the customizations for the slots.
The main way you interact with the slot system as a consumer. |
| | string | No | A named part of a component that can be customized. This is implemented by the consuming component.
The exposed slot names of a component are available in the components documentation. |
For all other properties specified on the Dismiss component, the componentid
will pass them down to the underlying button element. This includes properties
such as , data-* attributes, or additional ARIA attributes that you might
need for specialized use cases.
The most common pattern for the Dismiss component is to place it at both the
start and end of dismissible overlay content. This ensures screen reader users
navigating forward encounter a dismissal control at the beginning, and users
navigating backward from content below the overlay encounter a dismissal control
at the end.
In this example, when a screen reader user navigates into the dialog, they
immediately encounter the first dismiss button. If they navigate through all the
content and continue forward, they encounter the second dismiss button before
exiting the overlay's focus boundary. Both buttons invoke the same onDismiss
callback to close the dialog.
The default accessible label is "Dismiss". For localization or context-specific
labeling, use the ariaLabel prop to provide a custom label that makes sense in
your application's language and terminology.
Providing clear, localized labels helps screen reader users understand what will
happen when they activate the dismiss button. Use labels that match the
terminology of your application, such as "Close dialog", "Exit menu", or
"Dismiss notification".
Understanding when and where to use the Dismiss component is critical for
creating accessible overlay patterns. The following guidance is based on React
Aria patterns and WCAG accessibility standards.
The Dismiss component is required in the following contexts:
Modal Dialogs and Overlays
When creating modal dialogs that block interaction with the rest of the page,
place a Dismiss control at the start and end of the dialog content. This
provides screen reader users with a reliable dismissal mechanism regardless of
whether they navigate forward or backward through the content. While sighted
users can click a visible close button, screen reader users navigating linearly
need an equivalent affordance at both boundaries.
Modal Drawers and Sheets
Side panels and bottom sheets that use modal behavior should follow the same
pattern as modal dialogs. Position dismiss controls at the boundaries of the
drawer content to ensure users can exit through linear navigation.
The Dismiss component is recommended but not strictly required in these
contexts:
Dismissible Popovers and Menus
When popovers or dropdown menus can be dismissed but lack a visible close
button, include start and end dismiss controls. This ensures screen reader users
can exit the popup even when ESC key handling might not be discoverable.
Coachmarks and Tour Steps
Product tours and onboarding flows that can be dismissed should include dismiss
controls. If the tour requires explicit action buttons to proceed, consider
whether a generic dismiss is appropriate or whether users should be guided
through specific actions.
Combobox and Select Popovers
While combobox popovers typically manage focus automatically, adding dismiss
controls can help screen reader users who want to exit the popup without making
a selection.
Do not use the Dismiss component in these contexts:
Tooltips
Tooltips are non-interactive content that appear on hover or focus and do not
trap focus. They do not need dismiss controls as users can simply navigate away
from the trigger element.
Toasts and Notifications
Toast notifications and growl-style messages typically do not trap focus and
should not use the Dismiss component. If dismissal is needed, provide a
visible close button instead.
Non-Dismissible Content
Legal consent dialogs, age gates, or other content that requires explicit user
action should use specific action buttons rather than a generic dismiss control.
Follow these guidelines for correct placement:
Position the first dismiss control immediately after the opening tag of your
overlay content container, before any other focusable elements. Position the
second dismiss control immediately before the closing tag of your overlay
content container, after all other focusable elements. This ensures linear
navigation always encounters a dismiss affordance at the boundaries.
Always maintain a visible close button for sighted users. The Dismiss
component is a screen reader affordance, not a replacement for visible UI
controls. Sighted keyboard users and mouse users need their own clear way to
close overlays.
Use meaningful, localized labels through the ariaLabel prop. The default
"Dismiss" may not be appropriate for all contexts or languages. Consider labels
like "Close dialog", "Exit menu", or region-specific translations that match
your application's terminology.
The Dismiss component is designed with accessibility as its primary purpose.
It fills a specific gap in overlay accessibility by providing a dismissal
affordance for users navigating with screen readers using linear navigation
patterns.
Screen Reader Compatibility
The component uses the @bento/visually-hidden primitive to ensure the buttondisplay: none
remains completely accessible to assistive technologies while being visually
hidden from sighted users. This technique uses CSS to position content
off-screen rather than using or visibility: hidden, which
would make the content unavailable to screen readers.
Keyboard Navigation
The dismiss button is fully keyboard accessible. Screen reader users can
activate it using Enter or Space when focused on the element. The component uses
tabIndex={-1} which removes the button from the standard tab order but allows
screen readers to navigate to it through virtual cursor navigation. This is the
standard pattern for this type of control and aligns with React Aria's
DismissButton implementation.
ARIA Labeling
The component applies aria-label to provide context about what the buttonariaLabel
does. The default label is "Dismiss", but you should customize this through the prop to match your application's terminology and language. Clear,
descriptive labels help screen reader users understand the button's purpose
without requiring additional context.
Semantic HTML
The component renders as a native HTML button element with type="button" to
prevent accidental form submission. Using semantic HTML ensures compatibility
with assistive technologies and provides the expected button semantics and
keyboard behavior automatically.
Integration with Overlay Patterns
The Dismiss component is designed to work alongside other accessibilityOverlayTrigger
features in overlay patterns. It complements ESC key handling from React Aria's
overlay hooks, outside-click dismissal through , and focusDismiss
containment from focus management utilities. While these features provide
dismissal mechanisms for some users, the component specifically
addresses the needs of screen reader users navigating linearly through content.
Position the component inside your overlay's focus boundary, within the same
container as your overlay content. It should be rendered before and after your
overlay's main content to ensure users encounter it when navigating in either
direction.
The Dismiss component is built using the @bento/slots package, allowing you
to customize specific parts of the component through slot-based composition.
While the component is intentionally visually hidden, understanding its
customization options can be useful for specialized use cases or debugging.
The component is registered as BentoDismiss and introduces the following slots:
- hidden: Assigned to the @bento/visually-hidden component that wraps the dismiss button.
You can use the slots prop to override the default behavior of the visually hidden wrapper:
In this example, we override the hidden slot to provide custom styling to the
visually hidden wrapper. While this is possible, it is rarely necessary in
practice since the component is designed to be visually hidden by default.
See the @bento/slots package for more information on how to use the slot andslots properties.
While the dismiss button is visually hidden by default and styling is typically
not necessary, you can customize the underlying button element using className
or props. These props will be applied to the button element itself, not
the visually hidden wrapper.
`jsx
import { Dismiss } from '@bento/dismiss';
`
When you assign a className to the component, you take full responsibility for
styling. The component will pass this className to the button element, allowing
you to target it with CSS selectors. However, keep in mind that because the
button is wrapped in a visually hidden container, visual styles will not be
visible to sighted users.
The following data attributes are automatically applied to the component:
| Attribute | Description | Example Values |
| ------------- | ---------------------------------------------------------------------------- | -------------- |
| data-hidden | Applied to the visually hidden wrapper, indicating content is accessible to screen readers | "true" |
These attributes are provided by the underlying @bento/visually-hidden
component and can be used for debugging or specialized styling scenarios:
`css`
[data-hidden="true"] button[type="button"] {
/ Target all visually hidden buttons /
}
The component renders a native button element with the following attributes:
- type="button": Prevents the button from submitting forms when used insidetabIndex={-1}
form elements.
- : Removes the button from the standard tab order while keepingaria-label
it accessible to screen readers through virtual cursor navigation.
- : Provides an accessible label for screen readers. Defaults toariaLabel
"Dismiss" but can be customized via the prop.style={{ width: 1, height: 1 }}`: A defensive fallback that ensures the button
-
has minimal dimensions even when visually hidden, which can help with screen
reader detection in certain scenarios.