diff --git a/docs/docs/accessibility.mdx b/docs/docs/accessibility.mdx new file mode 100644 index 00000000..455f0676 --- /dev/null +++ b/docs/docs/accessibility.mdx @@ -0,0 +1,157 @@ +--- +sidebar_position: 5 +--- + +# Accessibility + +How to make sure your tooltips are usable by everyone, including keyboard and screen reader users. + +import { Tooltip } from 'react-tooltip' + +export const ButtonAnchor = ({ children, ...rest }) => ( + +) + +Tooltips are covered by several [WCAG](https://www.w3.org/TR/WCAG22/) success criteria. The most relevant ones are: + +- [**1.4.13 Content on Hover or Focus**](https://www.w3.org/TR/WCAG22/#content-on-hover-or-focus) — content shown on hover or focus must be **dismissible** (can be closed without moving the pointer or focus), **hoverable** (the pointer can move onto the content without it disappearing), and **persistent** (it stays visible until dismissed or no longer relevant). +- [**2.1.1 Keyboard**](https://www.w3.org/TR/WCAG22/#keyboard) — the tooltip must be reachable and triggerable with a keyboard alone, not only with a pointer. +- [**1.3.1 Info and Relationships**](https://www.w3.org/TR/WCAG22/#info-and-relationships) — the relationship between the anchor and its tooltip must be conveyed programmatically, so assistive technologies can announce it. + +The rest of this page shows how each of these maps to ReactTooltip props and markup. The [full example](#putting-it-all-together) at the end combines them. + +:::info + +ReactTooltip already opens the tooltip when the anchor receives keyboard focus (not just on hover), so most of the work is making sure your anchor is focusable and correctly associated with the tooltip. + +::: + +## Hoverable content (1.4.13) + +By default the tooltip disappears when the pointer leaves the anchor element — which means the pointer can't be moved onto the tooltip, and any buttons or links inside it are unreachable. + +Use the `clickable` prop so the pointer can move onto the tooltip content without it closing. See the [Clickable tooltip example](./getting-started#clickable-tooltip) in the Getting Started section. + +## Dismissible with `Esc` (1.4.13) + +Users must be able to close the tooltip without moving the pointer or focus. Enable the `escape` global close event so pressing the Esc key dismisses it. + +```jsx + +``` + +:::info + +`globalCloseEvents` accepts other options too (`scroll`, `resize`, `clickOutsideAnchor`). See the [options page](./options#available-props) for the full list. + +::: + +## Keyboard-accessible anchor (2.1.1) + +ReactTooltip opens the tooltip when the anchor receives focus, but only focusable elements can receive keyboard focus. Interactive elements such as ``, ` + +// ✅ made focusable +Help +``` + +:::caution + +Prefer a natively interactive element when the anchor is meant to be interacted with. Adding `tabIndex={0}` to a `` makes it focusable but does not give it a button's role or behavior. + +::: + +## Associating the anchor and tooltip (1.3.1) + +So screen readers announce the tooltip content when the anchor is focused, add an `aria-describedby` attribute to the anchor referencing the tooltip's `id`. + +```jsx + + +``` + +:::info + +ReactTooltip renders the tooltip element with `role="tooltip"`, so pairing it with `aria-describedby` gives assistive technologies the expected semantics. + +::: + +## Putting it all together + +This example combines all of the above: a keyboard-focusable anchor, associated with the tooltip via `aria-describedby`, whose content is reachable (`clickable`) and can be dismissed with Esc (`globalCloseEvents`). + +```jsx +import { Tooltip } from 'react-tooltip' + + + + + Read the docs + + +``` + +
+ ◕‿‿◕ + + Read the docs + +
+ +:::tip + +Try it with the keyboard: Tab to the anchor to open the tooltip, Tab again to move into the link, and Esc to dismiss it. + +::: diff --git a/docs/docs/getting-started.mdx b/docs/docs/getting-started.mdx index fd0d3b47..7d953f35 100644 --- a/docs/docs/getting-started.mdx +++ b/docs/docs/getting-started.mdx @@ -187,12 +187,18 @@ import { Tooltip } from 'react-tooltip' Hello world! -### Clickable tooltip/accessibility +### Clickable tooltip -By default the tooltip disappears when the pointer leaves the tooltip anchor element - which means you can't interact with elements inside the tooltip and that it won't meet the 'hoverable' requirement of [WCAG Success Criterion 1.4.13 Content on Hover or Focus](https://www.w3.org/TR/WCAG22/#content-on-hover-or-focus). +By default the tooltip disappears when the pointer leaves the tooltip anchor element, which means you can't interact with elements inside the tooltip. To allow for proper usage of elements such as buttons and inputs - or to ensure the pointer can be moved over the tooltip content without it disappearing - use the `clickable` prop. +:::info + +This is also required to meet the 'hoverable' requirement for accessible tooltips. See the [Accessibility page](./accessibility) for how to make your tooltips fully accessible. + +::: + ```jsx ◕‿‿◕ diff --git a/docs/docs/troubleshooting.mdx b/docs/docs/troubleshooting.mdx index 4e7c30a3..ad693559 100644 --- a/docs/docs/troubleshooting.mdx +++ b/docs/docs/troubleshooting.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 6 --- # Troubleshooting