Tooltip

A tooltip is in-app messaging used to identify elements on a page with short, clarifying text.

Accessibility

To implement an accessible PatternFly tooltip:

Avoid using tooltips on static elements such as a div or span, 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-v5-c-tooltip pf-m-top" role="tooltip">
  <div class="pf-v5-c-tooltip__arrow"></div>
  <div class="pf-v5-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-v5-c-tooltip pf-m-top" role="tooltip">
  <div class="pf-v5-c-tooltip__arrow"></div>
  <div class="pf-v5-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 minimum, a tooltip should meet the following criteria:

Unless it is a case of truncation, the tooltip is not placed on a static element.
The tooltip component has the role="tooltip" attribute.
If the tooltip is meant to act as a primary label, the trigger has the aria-labelledby attribute linked to the tooltip contents.One use case for this is when a button contains only an icon and no visible text label.
If the tooltip is meant to act as supplementary information, the trigger has the aria-describedby attribute linked to the tooltip contents.
Using a mouse to hover over the triggering element causes the tooltip to trigger, and the tooltip persists while hovering over the trigger or the tooltip itself.The exit delay for a tooltip should typically be greater than 0 so that users have enough time to hover the tooltip with their mouse. Too short of an exit delay can make it difficult for users with motor control issues to hover the tooltip before it transitions out.
The triggering element can receive focus via keyboard in order to trigger the tooltip, and the tooltip persists as long as the triggering element has focus.
Users navigating via screen reader have the contents of the tooltip announced to them when it is triggered.This is best achieved by wrapping the tooltip component around the trigger. This is best checked by using a screen reader.
The tooltip can be dismissed without having to move the mouse pointer or remove focus from the trigger.This is commonly done by pressing Escape.
If the tooltip content is no longer valid, the tooltip automatically gets dismissed.

React customization

The following React props have been provided for more fine-tuned control over accessibility.

Prop	Applied to	Reason
`aria-live="polite"`	`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="[describedby, labelledby, or none]"`	`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.
`entryDelay={[number in milliseconds]}`	`Tooltip`	Creates a delay in the specified number of milliseconds for when the tooltip appears. Avoid making the entry delay too long as it can cause users to navigate away before the tooltip appears.
`exitDelay={[number in milliseconds]}`	`Tooltip`	Creates a delay in the specified number of milliseconds for when the tooltip disappears. Avoid making the exit delay `0` or too short, as users must be given enough time to move their mouse pointer into the tooltip or enough time to read it if they are unable to keep their mouse steady.
`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={[an HTML element or React ref]}`	`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

The following 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-v5-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-v5-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-v5-c-tooltip`	Adds a tooltip role to the component. Required.
`aria-describedby="[id of the element that describes this element]"`	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="[id of the element that labels this element]"`	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 the disabled attribute.