APG: Tooltip

HTML

              
                <header class="experimental-code">
  <span>Experimental code: please refer to the <a href="https://w3c.github.io/aria-practices/#tooltip">APG tooltip design pattern</a>.</span>
</header>
<main>
  <h1>Tooltips</h1>
  <p>Two different implementations of the tooltip design pattern.</p>
  <p class="warning">Warning: this <a href="https://github.com/ZoeBijl/apg-tooltip">project is moved to GitHub</a>.</p>
  <section>
      <h2 id="todos">Todo:</h2>
      <ul>
          <li>
              <input type="checkbox" id="td1" checked>
              <label for="td1"> Comply with <a href="https://www.w3.org/TR/WCAG21/#content-on-hover-or-focus">WCAG 2.1 SC 1.4.13 Content on Hover or Focus</a></label>
          </li>
          <li>
              <input type="checkbox" id="td2" checked>
              <label for="td2"> Do some bounding box calculations</label>
          </li>
          <li>
              <input type="checkbox" id="td3" checked>
              <label for="td3"> Clean up <code>addEventListener</code> code</label>
          </li>
          <li>
              <input type="checkbox" id="td4" checked>
              <label for="td4"> Rerun tests</label>
          </li>
      </ul>
  </section>
  <section>
      <h2 id="tooltip-additional">Tooltip with additional information</h2>
      <p>This implementation follows the <a href="https://w3c.github.io/aria-practices/#tooltip">guidance of the ARIA Authoring Practices Guide</a>.</p>
      <div class="tooltip-container">
          <button type="button" aria-describedby="description">
              Settings
          </button>
          <p id="description" role="tooltip" class="hidden">View and manage settings</p>
      </div>
      <h3>Source</h3>
      <pre><code>&lt;div class="tooltip-container"&gt;
&lt;button type="button" aria-describedby="description"&gt;
  Settings
&lt;/button&gt;
&lt;p id="description" role="tooltip" class="hidden"&gt;View and manage settings&lt;/p&gt;
&lt;/div&gt;
</code></pre>
  </section>
  <section>
      <h2 id="tooltip-main-label">Tooltip as main label</h2>
      <p>In this version the label for the button is privded via a <code>aria-labelledby</code> attribute that points to tooltip text.</p>
      <div class="tooltip-container" data-tooltip-position="top">
          <button type="button" aria-labelledby="tooltip">
              <span aria-hidden="true">💛</span>
          </button>
          <p id="tooltip" role="tooltip" class="hidden">Like</p>
      </div>
      <section class="warning">
          <p>Warning: this pattern isn’t a valid/supported usecase in <a href="https://www.w3.org/TR/wai-aria-1.2/#tooltip">ARIA 1.2</a>.</p>
          <h3>Related GitHub issues</h3>
          <ul>
              <li><a href="https://github.com/w3c/aria-practices/issues/1034">Tooltip pattern should allow for aria-labelledby</a></li>
              <li><a href="https://github.com/w3c/aria/issues/979">Clarify the use of role=tooltip</a></li>
          </ul>
      </section>
      <p class="note">Note: the default position of this tooltip is set to be above the control. This is changed via the <code>data-tooltip-position</code> attribute on the <code>&lt;div&gt;</code> with the <code>tooltip-container</code> class.</p>
      <h3>Source</h3>
      <pre><code>&lt;div class="tooltip-container" data-tooltip-position="top"&gt;
&lt;button type="button" aria-labelledby="tooltip" data-tooltip-position="top"&gt;
  &lt;span aria-hidden="true"&gt;💛&lt;/span&gt;
&lt;/button&gt;
&lt;p id="tooltip" role="tooltip" class="hidden"&gt;Like&lt;/p&gt;
&lt;/div&gt;
</code></pre>
  </section>
  <section>
      <h2 id="keyboard-support">Keyboard support</h2>
      <p>Pressing <kbd>Escape</kbd> will close the tooltip.</p>
  </section>
  <section>
      <h2 id="touch-support">Touch support</h2>
      <p>Tapping anywhere outside the tooltip or button will close the tooltip.</p>
  </section>
  <section>
      <h2 id="development-notes">Development notes</h2>
      <ul>
          <li>Played around with <code>pointerover</code> and related pointer events; cool but a bit overkill here.</li>
      </ul>
  </section>
  <section>
      <h2 id="test-results">Test results</h2>
      <h3 id="tests-2022">Sometime in 2022</h3>
      <p>Tested to work with these browsers:</p>
      <ul>
          <li>Chrome 98.0.4758.80 on macOS 11.6.2 and Windows 10</li>
          <li>Firefox 96.0.3 on macOS 11.6.2 and Windows 10</li>
          <li>Safari 15.2 on macOS 11.6.2</li>
          <li>Chrome 97 on Android 9</li>
          <li>Firefox 96 on Android 9</li>
          <li>Safari on iOS 15.2.1</li>
      </ul>
      <p>Tested to work with these browser/assistive technology combinations:</p>
      <ul>
          <li>VoiceOver and Chrome 98.0.4758.80 on macOS 11.6.2</li>
          <li>VoiceOver and Safari 15.2 on macOS 11.6.2</li>
          <li>VoiceOver and Safari on iOS 15.2.1</li>
          <li>JAWS 2022.2112.24 and Chrome  98.0.4758.82 on Windows 10</li>
          <li>JAWS 2022.2112.24 and Firefox 96.0.3 on Windows 10<a href="#fn5">5</a></li>
          <li>NVIDA 2021.3.1 and Chrome 98.0.4758.82 on Windows 10</li>
          <li>NVIDA 2021.3.1 and Firefox 96.0.3 on Windows 10</li>
      </ul>
      <h4>Notes</h4>
      <ol class="footnotes" start="5">
          <li id="fn5">The description is read twice</li>
      </ol>
      <h3 id="tests-2019">Sometime in 2019</h3>
      <p>Note: these results are from 2019. While there were no major failures in these results; it’ll be well worth running these again!</p>
      <p>The ARIA bits of this work in Safari with VoiceOver on iOS. But the tooltips themselves aren’t visible before you trigger the action. This is a limitation of the design pattern.</p>
      <p>Tested to work in these browsers:</p>
      <ul>
          <li>Chrome 71.0.3578.98 on macOS 10.14.3 / Windows 10</li>
          <li>Safari 12.0.3 on macOS 10.14.3</li>
          <li>Firefox 65 on macOS 10.14.3 / Windows 10</li>
          <li>Edge 41.16299.820.0 / EdgeHTML 16.16299 on Windows 10</li>
      </ul>
      <p>Tested to work with these browser/assistive technology combinations:</p>
      <ul>
          <li>Safari 12.0.3 and VoiceOver on macOS 10.14.3</li>
          <li>Chrome 71.0.3578.98 and VoiceOver on macOS 10.14.3</li>
          <li>Chrome 71.0.3578.98 and NVDA 2018.4 on Windows 10 <a href="#fn3">3</a></li>
          <li>Chrome 71.0.3578.98 and JAWS 2019 on Windows 10  <a href="#fn3">3</a></li>
          <li>Edge 41.16299.820.0 / EdgeHTML 16.16299 and Narrator on Windows 10  <a href="#fn1">1</a></li>
          <li>Edge 41.16299.820.0 / EdgeHTML 16.16299 and NVDA 2018.4 on Windows 10  <a href="#fn1">1</a></li>
          <li>Edge 41.16299.820.0 / EdgeHTML 16.16299 and JAWS 2019 on Windows 10  <a href="#fn1">1</a>  <a href="#fn4">4</a></li>
          <li>Firefox 65 and NVDA 2018.4 on Windows 10  <a href="#fn2">2</a></li>
          <li>Firefox 65 and JAWS 2019 on Windows 10  <a href="#fn3">3</a></li>
      </ul>
      <h4>Notes</h4>
      <ol class="footnotes">
          <li id="fn1">The settings button is announced as “gear, button”. This is most likely because Edge ignores the <code>aria-label</code> on the <code>span</code> with <code>role=img</code>. Perhaps Edge doesn’t support the <code>img</code>-role.</li>
          <li id="fn2">NVDA announces the settings button as “Settings, graphic, button, view and manage settings”. There’s no delay between the announcement of the button name and its description.</li>
          <li id="fn3">There’s no delay between the announcement of the button name and its description.</li>
          <li id="fn4">The description isn’t announced.</li>
      </ol>
  </section>
  <section>
      <h2 id="resources">Resources</h2>
      <ul>
          <li><a href="https://sarahmhigley.com/writing/tooltips-in-wcag-21/">Tooltips in the time of WCAG 2.1</a> by Sarah Higley</li>
          <li><a href="https://inclusive-components.design/tooltips-toggletips/">Tooltips and Toggletips</a> by Heydon Works</li>
          <li><a href="https://w3c.github.io/aria-practices/#tooltip">ARIA APG: Tooltip design pattern</a></li>
          <li><a href="https://github.com/w3c/aria-practices/issues/128">GitHub APG: Draft tooltip design pattern</a></li>
          <li><a href="https://github.com/w3c/aria-practices/issues/127">GitHub APG: Draft tooltip code example</a></li>
          <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/Pointer_events">MDN: Pointer events</a></li>
      </ul>
  </section>
  <section>
      <h2 id="special-thanks">Special thanks</h2>
      <ul>
          <li><a href="https://github.com/thezacharytaylor">Zachary Taylor</a> for the bounding box calculations</li>
      </ul>
  </section>
  <footer>
      <p>Words by Zoë</p>
  </footer>
</main>

CSS

              
                :root {
    --tooltip-thingy-height: .5em;
}

[aria-hidden="true"] {
    pointer-events: none;
}

.tooltip-container {
    position: relative;
    display: inline-block;
}

.tooltip-container::before {
    position: absolute;
    top: 100%;
    left: 50%;
    transform: translateX(-50%);
    border: var(--tooltip-thingy-height) solid transparent;
    border-bottom-color: black;
}

// This allows users to move their cursor from the button to the tooltip
.tooltip-container::after {
    position: absolute;
    right: -20%;
    top: 100%;
    left: -20%;
    display: block;
    height: calc(var(--tooltip-thingy-height) * 2);
}

.tooltip-container.tooltip-visible::before,
.tooltip-container.tooltip-visible::after {
    content: '';
}

.tooltip-container.top::before,
.tooltip-container.top::after,
.tooltip-container.top [role=tooltip] {
    top: unset;
    bottom: 100%;
}

.tooltip-container.top::before {
    border-top-color: black;
    border-bottom-color: transparent;
}

.hidden {
    display: none;
}

[role=tooltip] {
    position: absolute;
    top: 100%;
    left: 50%;
    transform: translateX(-50%);
    padding: .5em 1em;
    border-radius: .25em;
    color: white;
    background: black;
    min-width: max-content;
    max-width: 10em;
    box-shadow: 0 1px 2px hsl(0, 0%, 0%);
}

button {
  display: inline-block;
  position: relative;
  padding: .4em .7em;
  border: 1px solid hsl(213, 71%, 49%);
  border-radius: 5px;
  box-shadow: 0 1px 2px hsl(216, 27%, 55%);
  color: #fff;
    font-size: inherit;
  text-shadow: 0 -1px 1px hsl(216, 27%, 25%);
  background-color: hsl(216, 82%, 51%);
  background-image: linear-gradient(to bottom, hsl(216, 82%, 53%), hsl(216, 82%, 47%));
}

button:hover {
  border-color: hsl(213, 71%, 29%);
  background-color: hsl(216, 82%, 31%);
  background-image: linear-gradient(to bottom, hsl(216, 82%, 33%), hsl(216, 82%, 27%));
  cursor: default;
}

button:focus {
  outline: 2px transparent;
}

button:focus::before {
  position: absolute;
  z-index: -1;
  /* button border width - outline width - offset */
  top: calc(-1px - 3px - 3px);
  right: calc(-1px - 3px - 3px);
  bottom: calc(-1px - 3px - 3px);
  left: calc(-1px - 3px - 3px);
  border: 3px solid hsl(213, 71%, 49%);
  /* button border radius + outline width + offset */
  border-radius: calc(5px + 3px + 3px);
  content: '';
}

button:active {
  border-color: hsl(213, 71%, 49%);
  background-color: hsl(216, 82%, 31%);
  background-image: linear-gradient(to bottom, hsl(216, 82%, 53%), hsl(216, 82%, 47%));
  box-shadow: inset 0 3px 5px 1px hsl(216, 82%, 30%);
}

JS

              
                class Tooltip {
  constructor(element) {
    this.container = element
    this.button = element.querySelector('button')
    this.tooltip = element.querySelector('[role=tooltip]')
    this.tooltipPosition = this.getTooltipPosition()
    this.globalEscapeBound = this.globalEscape.bind(this)
    this.globalPointerDownBound = this.globalPointerDown.bind(this)
    this.initialiseClassList()
    this.bindEvents()
  }

  // Basic actions
  openTooltip() {
    this.showTooltip()
    this.checkBoundingBox()
    this.attachGlobalListener()
  }

  closeTooltip() {
    this.hideTooltip()
    this.resetBoundingBox()
    this.removeGlobalListener()
  }

  // Binding event listteners
  bindEvents() {
    // Events that trigger openTooltip()
    // Open on mouse hover
    this.container.addEventListener('mouseenter', this.openTooltip.bind(this))
    // Open when a touch is detected
    this.container.addEventListener('touchstart', this.openTooltip.bind(this))
    // Open when the button gets focus
    this.button.addEventListener('focus', this.openTooltip.bind(this))

    // Events that trigger closeTooltip()
    // Close when the mouse cursor leaves the button or tooltip area
    this.container.addEventListener('mouseleave', this.closeTooltip.bind(this))
    // Close when the buttons loses focus
    this.button.addEventListener('blur', this.closeTooltip.bind(this))
  }

  attachGlobalListener() {
    document.addEventListener('keydown', this.globalEscapeBound)
    document.addEventListener('pointerdown', this.globalPointerDownBound)
  }

  removeGlobalListener() {
    document.removeEventListener('keydown', this.globalEscapeBound)
    document.removeEventListener('pointerdown', this.globalPointerDownBound)
  }

  globalEscape(event) {
    if (event.key === 'Escape' || event.key === 'Esc') {
      this.close()
    }
  }

  // Close the tooltip if the target is anything other than the components within the tooltip widget
  globalPointerDown(event) {
    switch (event.target) {
      case this.container:
      case this.button:
      case this.tooltip:
        event.preventDefault()
        break
      default:
        this.close()
        this.button.blur()
    }
  }

  // Show or hide the tooltip
  showTooltip() {
    this.container.classList.add('tooltip-visible')
    this.tooltip.classList.remove('hidden')
  }

  hideTooltip() {
    this.container.classList.remove('tooltip-visible')
    this.tooltip.classList.add('hidden')
  }

  // Get the desired default position for the tooltip (defaults to 'bottom')
  getTooltipPosition() {
    let attribute = this.container.getAttribute('data-tooltip-position')
    let setting = 'bottom'

    if (attribute === 'top') {
      setting = attribute
    }

    return setting;
  }

  // Set the default classes for tooltips based on this.getTooltipPosition()
  initialiseClassList() {
    switch (this.tooltipPosition) {
      case 'top':
        this.container.classList.add('top')
        break

      default:
        this.container.classList.remove('top')
        break
    }
  }

  // Calculate if the tooltip is within the viewport
  checkBoundingBox() {
    let bounds = this.tooltip.getBoundingClientRect()

    this.checkHorizontalBounding(bounds)
    this.checkVerticalBounding(bounds)
  }

  checkHorizontalBounding(bounds) {
    let windowWidth = window.innerWidth

    // If the tooltip overlaps on both sides, throw an error
    if (bounds.right > windowWidth && bounds.left < 0) {
      throw new Error('Tooltip width too wide for the window')
    }

    // Check if the right side of the tooltip is beyond the right side of the viewport
    if (bounds.right > windowWidth) {
      this.moveTooltipLeft(bounds, windowWidth)
    }

    // Check if the left side of the tooltip is beyond the left side of the viewport
    if (bounds.left < 0 ) {
      this.moveTooltipRight(bounds)
    }
  }

  checkVerticalBounding(bounds) {
    let windowHeight = window.innerHeight

    // If the tooltip overlaps on both sides, throw an error
    if (bounds.bottom > windowHeight && bounds.top < 0) {
      throw new Error('Tooltip height too high for the window')
    }

    // Check if the bottom of the tooltip is below the bottom of the viewport
    if (bounds.bottom > windowHeight) {
      this.moveTooltipUp()
    }

    // Check if the top of the tooltip is above the top of the viewport
    if (bounds.top < 0) {
      this.moveTooltipDown()
    }
  }

  // Move the tooltip so it fits within the viewport
  moveTooltipUp() {
    this.container.classList.add('top')
  }

  moveTooltipRight(bounds) {
    let numToMove = Math.floor(bounds.width / 2)
    this.tooltip.style.left = `${numToMove}px`
  }

  moveTooltipDown() {
    this.container.classList.remove('top')
  }

  moveTooltipLeft(bounds, windowWidth) {
    let translateAmount = (windowWidth - Math.round(bounds.right) - (Math.round(bounds.width) / 1.6))
    this.tooltip.style.transform = `translateX(${translateAmount}px)`
  }

  // Reset the changes made by the bounding box functions
  resetBoundingBox() {
    if (tooltip.style.left || tooltip.style.transform) {
      tooltip.style.left = null
      tooltip.style.transform = null
    }

    this.initialiseClassList()
  }
}

Array.from(document.querySelectorAll('.tooltip-container')).forEach(element => new Tooltip(element))

999px

Insecure Resource

About JavaScript Preprocessors

About External Resources

About Packages

HTML

CSS

JS

Console

HTML

HTML Preprocessor

About HTML Preprocessors

Add Class(es) to <html>

Adding Classes

Stuff for <head>

About the <head>

Insecure Resource

CSS

CSS Preprocessor

About CSS Preprocessors

CSS Base

About CSS Base

Vendor Prefixing

About Vendor Prefixing

Add External Stylesheets/Pens

About External Resources

JavaScript

JavaScript Preprocessor

About JavaScript Preprocessors

Add External Scripts/Pens

About External Resources

Packages

Add Packages

About Packages

Behavior

Auto Save

Auto-Updating Preview

Format on Save

Editor Settings

Code Indentation

Code Indent width

Want to change your Syntax Highlighting theme, Fonts and more?

HTML

CSS

JS

Console

Editor Commands

Editor Focus

Misc

HTML Specific

Pen Actions