1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
---
title: Tooltip
summary: >-
  Dark mono tooltip on hover, positioned above the child. Pure CSS — shown on
  hover and keyboard focus, no JavaScript required.
---

## Basic

`role="tooltip"` is the correct ARIA role for the bubble itself, so it
doubles as the styling hook — no class on the bubble. The wrapping `<span>`
has no attribute of its own, but it does not need one: `:has()` selects "a
span that contains a `[role=tooltip]` bubble" precisely, so the wrapper stays
bare too. Pair the trigger's `aria-describedby` with the bubble's `id` so the
tooltip is announced, not just shown.

Hover or tab to the button below.

<figure class="example">
<figcaption>Tooltip</figcaption>
<div>
<span>
  <button class="icon-button" aria-label="Delete" aria-describedby="tooltip-basic" style="--gl-icon: var(--gl-icon-trash)"></button>
  <span role="tooltip" id="tooltip-basic">Delete</span>
</span>
</div>
<details open><summary>Markup</summary>
<pre><code>&lt;span&gt;
  &lt;button class=&quot;icon-button&quot; aria-label=&quot;Delete&quot; aria-describedby=&quot;tooltip-basic&quot; style=&quot;--gl-icon: var(--gl-icon-trash)&quot;&gt;&lt;/button&gt;
  &lt;span role=&quot;tooltip&quot; id=&quot;tooltip-basic&quot;&gt;Delete&lt;/span&gt;
&lt;/span&gt;</code></pre>
</details>
</figure>

## On any element

A Tooltip wraps whatever it labels — most often an [IconButton](<%= relative_url('/components/icon-button/') %>), since that is the control with no visible text of its own.

<figure class="example">
<figcaption>On a badge</figcaption>
<div>
<span>
  <span class="badge" data-tone="danger" tabindex="0" aria-describedby="tooltip-badge">3d overdue</span>
  <span role="tooltip" id="tooltip-badge">Due Tuesday, was Saturday</span>
</span>
</div>
<details><summary>Markup</summary>
<pre><code>&lt;span&gt;
  &lt;span class=&quot;badge&quot; data-tone=&quot;danger&quot; tabindex=&quot;0&quot; aria-describedby=&quot;tooltip-badge&quot;&gt;3d overdue&lt;/span&gt;
  &lt;span role=&quot;tooltip&quot; id=&quot;tooltip-badge&quot;&gt;Due Tuesday, was Saturday&lt;/span&gt;
&lt;/span&gt;</code></pre>
</details>
</figure>

## API

<table>
  <thead><tr><th scope="col">Element / attribute</th><th scope="col">Values</th><th scope="col">Notes</th></tr></thead>
  <tbody>
    <tr><td><code>span</code></td><td></td><td>Required wrapper around the trigger and the bubble. Bare — matched structurally via <code>:has()</code>, no class.</td></tr>
    <tr><td><code>[role="tooltip"]</code></td><td>string content</td><td>Required — the bubble. Give it an <code>id</code>.</td></tr>
    <tr><td><code>aria-describedby</code></td><td>the bubble's <code>id</code></td><td>Put it on the trigger element, which needs a real accessible name of its own — a tooltip is not one.</td></tr>
  </tbody>
</table>