Tooltip widgets (or: screen tip, balloon)

Tooltips present information about a specific element in a small container on top of all other content. It is typically only displayed upon interacting with the related element in some way. Depending on the richness of its content, it is shown upon hovering or focusing the related element, or by manually toggling its visibility.

Tooltips are well known as native controls in many operating systems, for example for unobtrusively displaying warnings or alerts.

Tooltip

General requirements

The following requirements are based on well established best practices and WAI-ARIA Authoring Practices: Tooltip Widget (W3.org).

Besides many other requirements, we want to stress out explicitly the following:

The meaning and usage of the tooltip must be clear.
The tooltip must be operable using both keyboard only and screen readers (with a reasonable interplay of default keys like Tab, Enter/Space, Esc, Arrow keys), as well as mobile screen readers:
- Simple tooltips should be displayed automatically.
- Simple tooltips should be displayed manually.
The tooltip content must be accessible:
- Interactive elements must be reachable using keyboard.
- Complex content must be browsable line by line using screen readers.
If tooltips are separately focusable elements, they must come before any element they describe (or they have to be referred to beforehand).

Proofs of concept

Before you go on, please read What is a "Proof of concept"?.

Some tooltips appear automatically on hovering and/or focusing the described element. Their contents are announced immediately by screen readers; as such, screen reader users usually do not even have to know about the existence of such a tooltip.

Displaying a tooltip on hover

This tooltip offers simple content that is just short, non-structured plain text.

Use cases:

A tooltip attached to a text input, describing it as "required", or giving details about what to enter specifically.
A tooltip attached to a link "Read more…", describing it as "Read more about the topic X".

Automatically displayed tooltip

Show HTML code

Show CSS code

Show JS code

✔ (pass) ,

✔ (pass)

<svg id="definition" version="1.1" xmlns="http://www.w3.org/2000/svg"><defs><symbol id="tooltip" viewbox="0 0 442.762 442.762"><g><path d="M237.082,31.617c-113.596,0-205.68,84.96-205.68,189.764c0,28.473,6.809,55.473,18.986,79.711L1.736,389.064 		c-2.705,4.887-2.215,10.916,1.238,15.307c2.672,3.396,6.721,5.299,10.912,5.299c1.223,0,2.457-0.162,3.674-0.498l106.506-29.232 c32.432,19.719,71.266,31.205,113.016,31.205c113.594,0,205.68-84.959,205.68-189.764 		C442.762,116.577,350.676,31.617,237.082,31.617z M236.737,318.873c-11.227,0-20.356-9.132-20.356-20.357 		c0-11.225,9.131-20.357,20.356-20.357c11.227,0,20.357,9.133,20.357,20.357C257.096,309.74,247.965,318.873,236.737,318.873z 	M258.064,222.034c-2.674,1.828-4.522,3.175-5.522,4.021v21.272c0,8.712-7.091,15.8-15.802,15.8c-8.715,0-15.802-7.088-15.802-15.8 		v-22.918c0-15.281,11.152-22.903,19.296-28.467c8.789-6.005,14.595-9.972,14.595-22.361c0-9.975-8.113-18.09-18.089-18.09 		c-9.977,0-18.089,8.115-18.089,18.09c0,8.713-7.09,15.801-15.803,15.801c-8.713,0-15.803-7.088-15.803-15.801 		c0-27.4,22.293-49.692,49.694-49.692c27.398,0,49.691,22.292,49.691,49.692C286.432,202.653,268.674,214.787,258.064,222.034z"></path></g></symbol></defs></svg>
<p>
  <label for="name">Name: </label><input data-adg-tooltip-simple="Please enter both your first and last name" id="name" type="text" />
</p>
<p>
  <label for="about">About: </label><textarea data-adg-tooltip-simple="Tell a little something about yourself" id="about"></textarea>
</p>
<p>
  <label for="like-cheese">Do you like cheese?</label><input data-adg-tooltip-simple="Especially swiss cheese" id="like-cheese" type="checkbox" />
</p>
<p>
  <label for="language">Prefered language: </label><select data-adg-tooltip-simple="Usually your mother tongue" id="language" type="checkbox">
    <option>
      English
    </option>
    <option>
      French
    </option>
    <option>
      German
    </option>
  </select>
</p>
<p>
  If you like, please visit this: <a data-adg-tooltip-simple="Yes, it&#39;s really great!" href="https://www.example.com">example.com is great</a>.
</p>

*:focus {
  outline: 2px dotted #000;
}

.adg-visually-hidden {
  position: absolute;
  left: -10000px;
  top: auto;
  width: 1px;
  height: 1px;
  overflow: hidden;
}

.adg-tooltip-simple {
  position: relative;
}

.adg-tooltip-simple-icon {
  padding: 0 4px;
}
.adg-tooltip-simple-icon:hover {
  cursor: default;
}

.adg-tooltip-simple-balloon {
  background-color: #fff;
  font-weight: normal;
  border: 1px solid;
  border-radius: 3px;
  padding: 2px 6px;
  position: absolute;
  z-index: 1;
  left: 100%;
  top: -5px;
  white-space: nowrap;
  background-color: lightyellow;
}

svg#definition {
  display: none;
}

.icon {
  width: 16px;
  height: 16px;
  fill: #000;
}

;(function () {
  var AdgTooltipSimple

  AdgTooltipSimple = class AdgTooltipSimple {
    constructor(el) {
      this.$el = $(el)
      this.value = this.$el.attr('data-adg-tooltip-simple')
      this.$el.attr('data-adg-tooltip-simple', null)
      this.initContainer()
      this.attachContentToEl()
      this.initElEvents()
      this.initContainerEvents()
    }

    initContainer() {
      this.$container = $(
        "<span class='adg-tooltip-simple' aria-hidden='true'></span>"
      )
      this.$el.after(this.$container)
      this.initIcon()
      return this.initBalloon()
    }

    initIcon() {
      // Set focusable="false" for IE, see https://stackoverflow.com/questions/18646111/disable-onfocus-event-for-svg-element
      this.$icon = $(
        "<span class='adg-tooltip-simple-icon'><svg class='icon' focusable='false'><use xlink:href='#tooltip' /></svg></span>"
      )
      return this.$container.append(this.$icon)
    }

    initBalloon() {
      this.$balloon = $(
        `<span class='adg-tooltip-simple-balloon' hidden>${this.value}</span>`
      )
      this.$balloon.attr('id', `${this.$el.attr('id')}-balloon`)
      return this.$container.append(this.$balloon)
    }

    attachContentToEl() {
      var valueElement
      valueElement = $(
        `<span class='adg-visually-hidden'> (${this.value})</span>`
      )
      if (this.$el.is('input, textarea, select')) {
        return $(`label[for='${this.$el.attr('id')}'`).append(valueElement)
      } else {
        return this.$el.append(valueElement)
      }
    }

    initElEvents() {
      this.$el.focusin(() => {
        return this.show()
      })
      this.$el.focusout(() => {
        if (!this.$container.is(':hover')) {
          return this.hide()
        }
      })
      this.$el.mouseenter(() => {
        return this.show()
      })
      this.$el.mouseleave(() => {
        if (!this.$el.is(':focus')) {
          return this.hide()
        }
      })
      return this.$el.keyup(e => {
        if (e.keyCode === 27) {
          // Esc
          if (this.$balloon.is(':visible')) {
            return this.hide()
          } else {
            return this.show()
          }
        }
      })
    }

    initContainerEvents() {
      this.$container.mouseenter(() => {
        return this.show()
      })
      return this.$container.mouseleave(() => {
        if (!this.$el.is(':focus')) {
          return this.hide()
        }
      })
    }

    show() {
      return this.$balloon.attr('hidden', false)
    }

    hide() {
      return this.$balloon.attr('hidden', true)
    }
  }

  $(document).ready(function () {
    return $('[data-adg-tooltip-simple]').each(function () {
      return new AdgTooltipSimple(this)
    })
  })
}).call(this)

Category	Result	Comments	Date
Keyboard only	✔ (pass) pass	-	2018-5-29
NVDA 2023.1 + FF 115	✔ (pass) pass	-	2023-8-3
NVDA 2021.2 + Chrome	✔ (pass) pass	-	2021-2-10
NVDA 2023.1 + Edge	✔ (pass) pass	-	2023-7-13
JAWS 2018.3 + FF ESR 52.7.3	✔ (pass) pass	-	2018-5-22
JAWS 2021.2 + Chrome	✔ (pass) pass	-	2021-2-10
JAWS 2023.23 + Edge	✔ (pass) pass	-	2023-7-13

Implementation details

Some interesting peculiarities:

The tooltip's content is toggled using the hidden attribute (see Hiding elements from all devices).
By duplicating the tooltip's content to each label as visually hidden text (see Hiding elements visually by moving them off-screen), screen reader users will find it in both browse and focus mode.
- This is more robust than aria-describedby (see Adding descriptions to elements using aria-describedby).
- To prevent redundant announcements in screen readers, we hide the tooltip from them using aria-hidden (see Hiding elements from screen readers using aria-hidden).
Visibility of the tooltip can be toggled by pressing Esc (when the described element is focused).
- This is useful if the tooltip overlaps some important information.

Some tooltips require manual activation to appear. For this, they need their own focusable toggle button: upon activation, the tooltip's content can be browsed manually by screen reader users.

Displaying a tooltip manually

This tooltip usually offers rich content, for example links, lists, images, etc.

As such, the content cannot be digested "in one go" by screen reader users, so there is the need to browse the content line by line (or even to interact with certain interactive elements).

Use cases:

A tooltip attached to a password input, describing complex requirements for appropriate password strength, structured as a list containing an item for each individual requirement.
A tooltip attached to an avatar thumbnail image, describing its file characteristics (width, height, size), showing a bigger version of the image, and offering a link to the "Avatar options" page.

Manually displayed tooltip

Show HTML code

Show CSS code

Show JS code

✔ (pass) ,

✔ (pass)

<svg id="definition" version="1.1" xmlns="http://www.w3.org/2000/svg"><defs><symbol id="tooltip" viewbox="0 0 442.762 442.762"><g><path d="M237.082,31.617c-113.596,0-205.68,84.96-205.68,189.764c0,28.473,6.809,55.473,18.986,79.711L1.736,389.064 		c-2.705,4.887-2.215,10.916,1.238,15.307c2.672,3.396,6.721,5.299,10.912,5.299c1.223,0,2.457-0.162,3.674-0.498l106.506-29.232 c32.432,19.719,71.266,31.205,113.016,31.205c113.594,0,205.68-84.959,205.68-189.764 		C442.762,116.577,350.676,31.617,237.082,31.617z M236.737,318.873c-11.227,0-20.356-9.132-20.356-20.357 		c0-11.225,9.131-20.357,20.356-20.357c11.227,0,20.357,9.133,20.357,20.357C257.096,309.74,247.965,318.873,236.737,318.873z 	M258.064,222.034c-2.674,1.828-4.522,3.175-5.522,4.021v21.272c0,8.712-7.091,15.8-15.802,15.8c-8.715,0-15.802-7.088-15.802-15.8 		v-22.918c0-15.281,11.152-22.903,19.296-28.467c8.789-6.005,14.595-9.972,14.595-22.361c0-9.975-8.113-18.09-18.089-18.09 		c-9.977,0-18.089,8.115-18.089,18.09c0,8.713-7.09,15.801-15.803,15.801c-8.713,0-15.803-7.088-15.803-15.801 		c0-27.4,22.293-49.692,49.694-49.692c27.398,0,49.691,22.292,49.691,49.692C286.432,202.653,268.674,214.787,258.064,222.034z"></path></g></symbol></defs></svg>
<p>
  <label for="password">Password: </label><input data-adg-tooltip-complex="&lt;ul&gt;&lt;li&gt;At least 8 characters&lt;/li&gt;&lt;li&gt;At least 8 characters&lt;/li&gt;&lt;li&gt;Upper and lower case&lt;/li&gt;&lt;li&gt;At least 1 special character&lt;/li&gt;&lt;li&gt;Read more about &lt;a href=&#39;https://en.wikipedia.org/wiki/Password_strength&#39;&gt;Password Strength (Wikipedia.org)&lt;/a&gt;&lt;/li&gt;&lt;/ul&gt;" id="password" type="password" />
</p>
<p>
  <label for="about">About: </label><textarea data-adg-tooltip-complex="&lt;p&gt;Tell a little something about yourself, for example where you were born, what hobbies you have, what food you like, etc.&lt;/p&gt;&lt;p&gt;You can even tell us some details about your bank accounts, like your balance, secret logins, passwords, and anything that could be of interest to us.&lt;/p&gt;&lt;p&gt;Thank you so much for your open-mindedness!&lt;/p&gt;" id="about"></textarea>
</p>
<p>
  <label for="like-cheese">Do you like cheese?</label><input data-adg-tooltip-complex="&lt;p&gt;Mmmh, what do you think about this?&lt;/p&gt;&lt;p&gt;&lt;img src=&#39;https://www.emmentaler.ch/files/content/chde/sortiment/sortiment_03lower_06gotthelf.png&#39; alt=&#39;Cave-agend Emmentaler, yummy!&#39; /&gt;&lt;/p&gt;" id="like-cheese" type="checkbox" />
</p>
<p>
  If you like, please visit this: <a data-adg-tooltip-complex="&lt;p&gt;This is really a great link. But we have alternatives:&lt;/p&gt;&lt;ul&gt;&lt;li&gt;&lt;a href=&#39;https://www.asdf.com&#39;&gt;Asdf.com&lt;/a&gt;&lt;/li&gt;&lt;li&gt;&lt;a href=&#39;https://gifdanceparty.giphy.com/&#39;&gt;GIF Dance Party (Giphy.com)&lt;/a&gt;&lt;/li&gt;&lt;/ul&gt;" href="https://www.example.com">Example.com is great</a>.
</p>

*:focus {
  outline: 2px dotted #000;
}

.adg-visually-hidden {
  position: absolute;
  left: -10000px;
  top: auto;
  width: 1px;
  height: 1px;
  overflow: hidden;
}

.adg-tooltip-complex {
  position: relative;
}

.adg-tooltip-complex-icon {
  border: 0;
  padding: 0 4px;
}
.adg-tooltip-complex-icon:hover {
  cursor: pointer;
}

.adg-tooltip-complex-balloon {
  background-color: #fff;
  font-weight: normal;
  border: 1px solid;
  border-radius: 3px;
  padding: 2px 6px;
  position: absolute;
  z-index: 1;
  left: 100%;
  top: -5px;
  background-color: lightyellow;
  width: 300px;
}
.adg-tooltip-complex-balloon img {
  max-width: 100%;
}

svg#definition {
  display: none;
}

.icon {
  width: 16px;
  height: 16px;
  fill: #000;
}

;(function () {
  var AdgTooltipComplex

  AdgTooltipComplex = class AdgTooltipComplex {
    constructor(el) {
      this.$el = $(el)
      this.value = this.$el.attr('data-adg-tooltip-complex')
      this.$el.attr('data-adg-tooltip-complex', null)
      this.initContainer()
      this.attachContentToEl()
      this.initIconEvents()
    }

    initContainer() {
      this.$container = $("<span class='adg-tooltip-complex'></span>")
      this.$el.after(this.$container)
      this.initIcon()
      return this.initBalloon()
    }

    initIcon() {
      // Set focusable="false" for IE, see https://stackoverflow.com/questions/18646111/disable-onfocus-event-for-svg-element
      this.$icon = $(
        "<button class='adg-tooltip-complex-icon' aria-expanded='false'><span class='adg-visually-hidden'>Toggle tooltip</span><svg class='icon' focusable='false'><use xlink:href='#tooltip' /></svg></button>"
      )
      return this.$container.append(this.$icon)
    }

    initBalloon() {
      this.$balloon = $(
        `<div class='adg-tooltip-complex-balloon' hidden>${this.value}</div>`
      )
      this.$balloon.attr('id', `${this.$el.attr('id')}-balloon`)
      return this.$container.append(this.$balloon)
    }

    attachContentToEl() {
      var valueElement
      valueElement = $(
        "<span class='adg-visually-hidden'> (for more details, consult adjacent tooltip)</span>"
      )
      if (this.$el.is('input, textarea, select')) {
        return $(`label[for='${this.$el.attr('id')}'`).append(valueElement)
      } else {
        return this.$el.append(valueElement)
      }
    }

    initIconEvents() {
      return this.$icon.click(() => {
        if (this.$balloon.is(':visible')) {
          return this.hide()
        } else {
          return this.show()
        }
      })
    }

    show() {
      this.$balloon.attr('hidden', false)
      return this.$icon.attr('aria-expanded', true)
    }

    hide() {
      this.$balloon.attr('hidden', true)
      return this.$icon.attr('aria-expanded', false)
    }
  }

  $(document).ready(function () {
    return $('[data-adg-tooltip-complex]').each(function () {
      return new AdgTooltipComplex(this)
    })
  })
}).call(this)

Category	Result	Comments	Date
Keyboard only	✔ (pass) pass	-	2018-5-29
NVDA 2018.1 + FF Quantum 59.0.2	✔ (pass) pass	-	2018-5-2
NVDA 2021.2 + Chrome	✔ (pass) pass	-	2021-2-10
NVDA 2023.1 + Edge	✔ (pass) pass	-	2023-7-13
JAWS 2018.3 + FF ESR 52.7.3	✔ (pass) pass	-	2018-5-22
JAWS 2021.2 + Chrome	✔ (pass) pass	-	2021-2-10
JAWS 2023.23 + Edge	✔ (pass) pass	-	2023-7-13

By the way, complex tooltips are very similar to:

Non-modal dialogs, see Dialog widget (or: modal, popup, lightbox, alert)
Dropdowns, see Dropdown widget (or: menu, pulldown)

Implementation details

Some interesting peculiarities:

Each form control's label gives a hint about the existence of a tooltip. This enables screen reader users to know about it in advance, so they can consult its contents before interacting with the form control (if wished).
- Alternatively, the tooltip could be placed before the form control.
The toggle button has a visually hidden label to provide a proper name, while the visible SVG icon is ignored by screen readers.
- To prevent Internet Explorer from making the SVGs focusable, the focusable="false" attribute is used.
- Instead of an SVG icon, also a traditional image with empty alternative text would work: <img src="..." alt="" />.
The toggle button has an aria-expanded attribute to announce its expandability status (see Marking elements expandable using aria-expanded).

You are here:

Tooltip widgets (or: screen tip, balloon)

General requirements

Proofs of concept

Automatically displayed tooltip

Implementation details

Manually displayed tooltip

Implementation details

Previous/next navigation