Accessibility
To implement an accessible PatternFly tooltip:
- Avoid using tooltips on static elements such as a
div
orspan
, except in cases of truncation.
For the PatternFly React library:
- Pass in
aria="labelledby"
to the tooltip component when the tooltip should act as the primary label for its trigger:<Tooltip content="Copy to clipboard" aria="labelledby"> <button> <CopyIcon /> </button> </Tooltip>
For the HTML/CSS library:
Pass in
role="tooltip"
to the element acting as the tooltip component.Pass in the
aria-labelledby
attribute to the trigger when the tooltip should act as the primary label for its trigger:<div class="pf-c-tooltip pf-m-top" role="tooltip"> <div class="pf-c-tooltip__arrow"></div> <div class="pf-c-tooltip__content" id="tooltip-label-content"> Copy to clipboard </div> </div> <button aria-labelledby="tooltip-label-content"> <CopyIcon /> </button>
Pass in the
aria-describedby
attribute to the trigger when the tooltip should act as supplementary information:<div class="pf-c-tooltip pf-m-top" role="tooltip"> <div class="pf-c-tooltip__arrow"></div> <div class="pf-c-tooltip__content" id="tooltip-description-content"> Supplementary information within a tooltip </div> </div> <button aria-describedby="tooltip-description-content"> Button text label </button>
Testing
At a minimumm, a tooltip should meet the following criteria:
- One use-case for this is when a button contains only an icon and no visible text label.
- This is best achieved by wrapping the tooltip component around the trigger. This is best checked by using a screen reader.
- This is commonly done by pressing Escape.
React customization
Various React props have been provided for more fine-tuned control over accessibility.
Prop | Applied to | Reason |
---|---|---|
aria-live | Tooltip | When a value of "polite" is passed in, allows assistive technologies to announce the tooltip contents when it is expected or intended to dynamically update, such as in response to a user action. This should only be passed in when the children prop is also used on the tooltip. aria-live="polite" is set by default when using the reference prop in order to allow assistive technologies to correctly announce tooltip contents regardless if it will dynamically update or not. |
aria | Tooltip | When a value of "describedby" (default behavior) or "labelledby" is passed in, allows assistive technologies to announce the tooltip contents when it is triggered. A value of "describedby" sets the trigger's aria-describedby attribute and should be used when the tooltip should act as supplementary information. A value of "labelledby" sets the trigger's aria-labelledby attribute and should be used when the tooltip should act as a primary label. When a value of "none" is passed in, prevents aria-labelledby and aria-describedby from being set on the trigger. Only pass in a value of "none" when either aria-labelledby or aria-describedby is manually set on the trigger and the id prop is manually passed into the tooltip. This prop should only be passed in when the children prop is also used on the tooltip. |
id | Tooltip | Sets the id attribute on the tooltip, which can be passed in as the value to a trigger's aria-labelledby or aria-describedby attribute. Required when either aria-labelledby or aria-describedby is manually set on the trigger or when the reference prop is passed into the tooltip. |
reference | Tooltip | Links the tooltip to a trigger when the children prop cannot be used. When passing in this prop, the id prop must also be passed in, and either aria-labelledby or aria-describedby must be set on the trigger with a value of the tooltip's id . |
Aria-live
The following code block shows how you should generally use the aria-live
prop when the tooltip contents is intended or expected to dynamically update.
const [tooltipContent, setTooltipContent] = React.useState("Copy to clipboard");
const onClick = () => {
setTooltipContent('Successfully copied to clipboard!")
}
<Tooltip aria-live="polite" content={tooltipContent}>
<button onClick={onClick}>
<CopyIcon />
</button>
</Tooltip>
Aria
When passing in aria="none"
in the following code block, the id
is passed into the tooltip and aria-labelledby
is passed into the trigger with a value of the tooltip's id
.
<Tooltip id="tooltip-without-aria" aria="none" content="Copy to clipboard">
<button aria-labelledby="tooltip-without-aria">
<CopyIcon />
</button>
</Tooltip>
Reference
When using the reference
prop in the following code block, a React ref is created and passed into the tooltip and the trigger as the reference
and ref
props, respectively. Additionally, the id
is passed into the tooltip and aria-labelledby
is passed into the trigger with a value of the tooltip's id
.
const tooltipRef = React.useRef();
<Tooltip id="tooltip-with-reference" content="Copy to clipboard" reference={tooltipRef} />
<button ref={tooltipRef} aria-labelledby="tooltip-with-reference">
<CopyIcon />
</button>
HTML/CSS customization
Various HTML attributes and PatternFly classes can be used for more fine-tuned control over accessibility.
Attribute or class | Applied to | Reason |
---|---|---|
aria-live="polite" | .pf-c-tooltip | Allows assistive technologies to announce the tooltip contents when it is expected or intended to dynamically update, such as in response to a user action. |
id | .pf-c-tooltip | Used to link the tooltip to a trigger by passing in the tooltip's id as the value to the trigger's aria-describedby or aria-labelledby attribute. Required. |
role="tooltip" | .pf-c-tooltip | Adds a tooltip role to the component. Required. |
aria-describedby | element that triggers the tooltip | Allows assistive technologies to announce the tooltip contents when it is triggered. Required when the tooltip should act as supplementary information. |
aria-labelledby | element that triggers the tooltip | Allows assistive technologies to announce the tooltip contents when it is triggered. Required when the tooltip should act as the primarly label of the trigger. |
Additional considerations
Consumers must ensure they take any additional considerations when customizing a tooltip, using it in a way not described or recommended by PatternFly, or in various other specific use-cases not outlined elsewhere on this page.
- If a tooltip is added to a trigger that is disabled, the trigger must still be able to receive focus. This can often be achieved by using the
aria-disabled
attribute instead of thedisabled
attribute.
Further reading
To read more about accessibility with tooltips, refer to the following resources:
View source on GitHub