Tooltip

Tooltip only appears on mouse hover or keyboard focus and contain a label or description text. Use tooltips sparingly and as a last resort. Use tooltips as a last resort. Please consider Tooltips alternatives.

When using a tooltip, follow the provided guidelines to avoid accessibility issues:

• Tooltips should contain only non-essential text. Tooltips can easily be missed and are not accessible on touch devices so never use tooltips to convey critical information.
• Tooltip should be rendered through the API of Button, Link, or IconButton. Avoid using Tooltip a standalone component unless absolutely necessary (and only on interactive elements).

Accessibility

• Tooltip text must be brief and concise whether it is a label or a description.
• Tooltip can only hold string content.
• Never set tooltips on static, non-interactive elements like span or div. Tooltips should only be used on interactive elements like buttons or links to avoid excluding keyboard-only users and screen reader users. Use of tooltip through Button, Link, or IconButton will guarantee this.
• If you must use Tooltip as a standalone component, place it adjacent after the trigger element in the DOM. This allows screen reader users to navigate to and copy the tooltip content.

Which type should I set?

Semantically, a tooltip will either act an accessible name or an accessible description for the element that it is associated with resulting in either a aria-labelledby or an aria-describedby association. The type drastically changes semantics and screen reader behavior so follow these guidelines carefully:

• When there is already a visible label text on the trigger element, the tooltip is likely intended be supplementary, so set type: :description. The majority of tooltips will fall under this category.
• When there is no visible text on the trigger element and the tooltip content is appropriate as a label for the element, set type: :label. label type is usually only appropriate for an icon-only control.

Arguments

Examples

As a supplementary description for a button

In this example, the button has a visible label text, "Save". type: :description is set because the tooltip content is supplementary. A screen reader user who encounters this button will hear the accessible name, "Save" followed by the accessible description, "This will immediately impact all organization members".

<%= render(Primer::ButtonComponent.new(id: "save-button")) do |c| %>
  <% c.with_tooltip(text: "This will immediately impact all organization members", type: :description, direction: :ne) %>
  Save
<% end %>

As a label for an IconButton

An IconButton of tag: :button and tag: :a will render a tooltip using the aria-label content by default. While tooltips should generally be avoided, a tooltip on an IconButton has usability benefits because it provides a textual label for sighted users. A screen reader user who encounters the following button will hear the accessible name, "Bold".

<%= render(Primer::IconButton.new(id: "bold-button-0", icon: :bold, "aria-label": "Bold")) %>

As a supplementary description for an IconButton

If you want to provide a description for the IconButton, set both aria-label and aria-description text. The tooltip will use the aria-description text. A screen reader user who encounters the following button will hear the accessible name "Search", followed by the accessible description "Use keywords like 'repo:' and 'org:' in your query".

<%= render(Primer::IconButton.new(id: "search-button", icon: :search, "aria-label": "Search", "aria-description": "Use keywords like 'repo:' and 'org:' in your query")) %>

With direction

Set direction of tooltip with direction. The tooltip is responsive and will automatically adjust direction to avoid cutting off.

<%= render(Primer::ButtonComponent.new(id: "North", m: 2)) do |c| %>
  <% c.with_tooltip(text: "This is a North-facing tooltip, and is responsive.", type: :description, direction: :n) %>
  North
<% end %>
<%= render(Primer::ButtonComponent.new(id: "South", m: 2)) do |c| %>
  <% c.with_tooltip(text: "This is a South-facing tooltip, and is responsive.", type: :description, direction: :s) %>
  South
<% end %>
<%= render(Primer::ButtonComponent.new(id: "East", m: 2)) do |c| %>
  <% c.with_tooltip(text: "This is a East-facing tooltip, and is responsive.", type: :description, direction: :e) %>
  East
<% end %>
<%= render(Primer::ButtonComponent.new(id: "West", m: 2)) do |c| %>
  <% c.with_tooltip(text: "This is a West-facing tooltip, and is responsive.", type: :description, direction: :w) %>
  West
<% end %>
<%= render(Primer::ButtonComponent.new(id: "Northwest", m: 2)) do |c| %>
  <% c.with_tooltip(text: "This is a Northwest-facing tooltip, and is responsive.", type: :description, direction: :nw) %>
  Northwest
<% end %>
<%= render(Primer::ButtonComponent.new(id: "Southwest", m: 2)) do |c| %>
  <% c.with_tooltip(text: "This is a Southwest-facing tooltip, and is responsive.", type: :description, direction: :sw) %>
  Southwest
<% end %>
<%= render(Primer::ButtonComponent.new(id: "Northeast", m: 2)) do |c| %>
  <% c.with_tooltip(text: "This is a Northeast-facing tooltip, and is responsive.", type: :description, direction: :ne) %>
  Northeast
<% end %>
<%= render(Primer::ButtonComponent.new(id: "Southeast", m: 2)) do |c| %>
  <% c.with_tooltip(text: "This is a Southeast-facing tooltip, and is responsive.", type: :description, direction: :se) %>
  Southeast
<% end %>

Directly using Tooltip

When you have a valid tooltip usecase for an interactive element that is not one of the supported components, you may need to use the Tooltip component directly. The tooltip should be placed directly adjacent after the element you are associating it with. The tooltip is absolutely positioned so ensure there is a wrapper with position: relative to avoid positioning issues.

<div style="position: relative;">
  <button type="button" id="test-button">Test</button>
  <%= render(Primer::Alpha::Tooltip.new(for_id: "test-button", type: :description, text: "This tooltip should take up the full width", direction: :ne)) %>
</div>