How to build an accessible Toggletip in React

The trigger is a real <button> with aria-expanded reflecting open state and aria-controls pointing at the bubble; an icon-only trigger gets an accessible name from labels.label or the built-in i18n catalog. The bubble is role="status" so its content is announced when it opens, and unlike a hover tooltip the content remains visible and reachable for selection and links. DismissableLayer provides Escape and outside-pointer dismissal, and high-contrast and reduced-motion preferences are honored in CSS.

When to use a Toggletip

• Revealing brief supplementary information on demand when the user clicks an info affordance
• Content that must be selectable or contain a link, where a hover Tooltip would be unreachable
• Touch-friendly hint surfaces where hover is unavailable

When not to use it

• A passive label that should appear on hover/focus without a click — use Tooltip
• A blocking, focus-trapping dialog for a task — use Modal
• Rich forms or pickers anchored to a trigger — use Popover
• A list of one-shot actions behind a button — use MenuButton

Keyboard interactions

Role status, verified at WCAG 2.2-AA.

• Enter
• Space
• Escape

Common mistakes

Avoid: Using a hover Tooltip to hold a link or text the user needs to read or copy

Prefer: Use a Toggletip so the content stays open on click and remains reachable and selectable

Hover tooltips disappear on pointer-out and are not keyboard- or touch-reachable for interaction, so interactive or copyable content needs a click-toggled bubble

Avoid: Giving the trigger an icon with no text and no labels.label override

Prefer: Provide labels.label or rely on the built-in i18n accessible name

An icon-only button with no accessible name cannot be operated by screen-reader or voice users

Example

<Toggletip trigger={<InfoIcon />}>
  Your password must contain at least 12 characters.
</Toggletip>

See the full Toggletip reference →