Tooltip only appears on mouse hover or keyboard focus and contain a label or description text.
Use tooltips sparingly and as a last resort.
When using a tooltip, follow the provided guidelines to avoid accessibility issues.
Tooltip adjacent after its trigger element in the DOM. This allows screen reader users to navigate to and copy the tooltip
content.type should I set?Setting :description establishes an aria-describedby relationship, while :label establishes an aria-labelledby relationship between the trigger element and the tooltip,
The type drastically changes semantics and screen reader behavior so follow these guidelines carefully:
type: :description.
The majority of tooltips will fall under this category.type: :label.
This type is usually only appropriate for an icon-only control.| Name | Type | Default | Description |
|---|---|---|---|
for_id | String | N/A | The ID of the element that the tooltip should be attached to. |
type | Symbol | N/A | One of :description and :label. |
direction | Symbol | :s | One of :e, :n, :ne, :nw, :s, :se, :sw, or :w. |
text | String | N/A | The text content of the tooltip. This should be brief and no longer than a sentence. |
system_arguments | Hash | N/A | System arguments |
If the tooltip content provides supplementary description, set type: :description to establish an aria-describedby relationship. The trigger element should also have a concise accessible label via aria-label.
<%= render(Primer::IconButton.new(id: "bold-button-0", icon: :bold, "aria-label": "Bold")) %><%= render(Primer::Alpha::Tooltip.new(for_id: "bold-button-0", type: :description, text: "Add bold text", direction: :ne)) %>
If the tooltip labels the icon-only button, set type: :label. This tooltip content becomes the accessible name for the button.
<%= render(Primer::ButtonComponent.new(id: "like-button")) { "👍" } %><%= render(Primer::Alpha::Tooltip.new(for_id: "like-button", type: :label, text: "Like", direction: :n)) %>
If the button already has visible label text, the tooltip content is likely supplementary so set type: :description.
<%= render(Primer::ButtonComponent.new(id: "save-button", scheme: :primary)) { "Save" } %><%= render(Primer::Alpha::Tooltip.new(for_id: "save-button", type: :description, text: "This will immediately impact all organization members", direction: :ne)) %>
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)) { "North" } %><%= render(Primer::Alpha::Tooltip.new(for_id: "North", type: :description, text: "This is a North-facing tooltip, and is responsive.", direction: :n)) %><%= render(Primer::ButtonComponent.new(id: "South", m: 2)) { "South" } %><%= render(Primer::Alpha::Tooltip.new(for_id: "South", type: :description, text: "This is a South-facing tooltip and is responsive.", direction: :s)) %><%= render(Primer::ButtonComponent.new(id: "East", m: 2)) { "East" } %><%= render(Primer::Alpha::Tooltip.new(for_id: "East", type: :description, text: "This is a East-facing tooltip and is responsive.", direction: :e)) %><%= render(Primer::ButtonComponent.new(id: "West", m: 2)) { "West" } %><%= render(Primer::Alpha::Tooltip.new(for_id: "West", type: :description, text: "This is a West-facing tooltip and is responsive.", direction: :w)) %><%= render(Primer::ButtonComponent.new(id: "Northeast", m: 2)) { "Northeast" } %><%= render(Primer::Alpha::Tooltip.new(for_id: "Northeast", type: :description, text: "This is a Northeast-facing tooltip and is responsive.", direction: :ne)) %><%= render(Primer::ButtonComponent.new(id: "Southeast", m: 2)) { "Southeast" } %><%= render(Primer::Alpha::Tooltip.new(for_id: "Southeast", type: :description, text: "This is a Southeast-facing tooltip and is responsive.", direction: :se)) %><%= render(Primer::ButtonComponent.new(id: "Northwest", m: 2)) { "Northwest" } %><%= render(Primer::Alpha::Tooltip.new(for_id: "Northwest", type: :description, text: "This is a Northwest-facing tooltip and is responsive.", direction: :nw)) %><%= render(Primer::ButtonComponent.new(id: "Southwest", m: 2)) { "Southwest" } %><%= render(Primer::Alpha::Tooltip.new(for_id: "Southwest", type: :description, text: "This is a Southwest-facing tooltip and is responsive.", direction: :sw)) %>
When the tooltip and trigger element have a parent container with relative: position, it should not affect width of the tooltip.
<span style="position: relative;"><%= render(Primer::ButtonComponent.new(id: "test-button", scheme: :primary)) { "Test" } %><%= render(Primer::Alpha::Tooltip.new(for_id: "test-button", type: :description, text: "This tooltip should take up the full width", direction: :ne)) %></span>