Clean Markup

Non-Disruptive Tooltips with HTML popover hint Semantics

Non-Disruptive Tooltips with HTML popover hint Semantics

Since the baseline arrival of the HTML Popover API, developers gained declarative top-layer rendering, built-in Escape handling, and light-dismiss behavior via popover="auto". Yet using popover="auto" for lightweight tooltips immediately exposed a subtle layering conflict: opening any auto popover automatically closes every other open auto popover outside its ancestor chain. If a user opens a toolbar dropdown menu (popover="auto") and then hovers over an icon button inside or beside it to inspect a tooltip, showing that tooltip as popover="auto" dismisses the active menu right under their cursor. Conversely, switching tooltips to popover="manual" preserves the underlying menu, but strips away automatic light-dismissal and forces teams back into writing global Escape listeners and focus-tracking boilerplate.

The HTML popover="hint" state resolves this exact clash by introducing a dedicated ephemeral tier in the top-layer popover stack. Showing a hint popover closes any other currently open hint popovers so only one tooltip appears at a time, while leaving unrelated auto popovers—such as open menus, comboboxes, or non-modal drawers—completely undisturbed. At the same time, hint popovers remain integrated into the browser's light-dismiss lifecycle: opening a new auto popover, pressing Escape, or clicking outside clears the active hint cleanly. Paired with CSS Anchor Positioning (anchor-name and position-anchor) and accessible aria-describedby associations, popover="hint" enables clean, non-disruptive tooltips with minimal JavaScript.

Example

<div class="toolbar">
  <button
    type="button"
    popovertarget="format-menu"
    aria-haspopup="menu"
  >
    Format
  </button>

  <div id="format-menu" popover="auto" role="menu">
    <button
      type="button"
      role="menuitem"
      aria-describedby="bold-tip"
      data-tooltip="bold-tip"
    >
      Bold
    </button>
  </div>
</div>

<!-- Opening #bold-tip does NOT close #format-menu -->
<div id="bold-tip" popover="hint" role="tooltip">
  Toggle bold text (Ctrl+B)
</div>

Implementation

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Non-Disruptive Popover Hint Tooltips</title>
  <style>
    :root {
      --surface: #ffffff;
      --border: #d4d4d8;
      --ink: #18181b;
      --tip-bg: #18181b;
      --tip-ink: #fafafa;
    }

    .toolbar {
      display: inline-flex;
      gap: 0.5rem;
      padding: 0.5rem;
      border: 1px solid var(--border);
      border-radius: 0.5rem;
      background: var(--surface);
    }

    .tool-btn {
      padding: 0.45rem 0.75rem;
      border: 1px solid var(--border);
      border-radius: 0.375rem;
      background: var(--surface);
      color: var(--ink);
      font: inherit;
      cursor: pointer;
    }

    .tool-btn:focus-visible {
      outline: 2px solid #2563eb;
      outline-offset: 2px;
    }

    [popover="auto"] {
      margin: 0.35rem 0 0;
      padding: 0.35rem;
      border: 1px solid var(--border);
      border-radius: 0.5rem;
      background: var(--surface);
      box-shadow: 0 10px 25px rgb(0 0 0 / 0.1);
    }

    .tooltip-hint {
      position: fixed;
      inset: auto;
      margin: 0;
      padding: 0.375rem 0.625rem;
      border: 0;
      border-radius: 0.375rem;
      background: var(--tip-bg);
      color: var(--tip-ink);
      font-size: 0.8125rem;
      line-height: 1.3;
      pointer-events: none;
      opacity: 0;
      transform: translateY(4px);
      transition:
        opacity 140ms ease,
        transform 140ms ease,
        display 140ms allow-discrete,
        overlay 140ms allow-discrete;
    }

    .tooltip-hint:popover-open {
      opacity: 1;
      transform: translateY(0);
    }

    @starting-style {
      .tooltip-hint:popover-open {
        opacity: 0;
        transform: translateY(4px);
      }
    }

    @supports (anchor-name: --a) and (position-area: top) {
      .tooltip-hint {
        position-area: top center;
        margin-bottom: 0.5rem;
        position-try-fallbacks: flip-block, flip-inline;
      }
    }

    @media (prefers-reduced-motion: reduce) {
      .tooltip-hint {
        transition: none;
      }
    }
  </style>
</head>
<body>
  <div class="toolbar" role="toolbar" aria-label="Document actions">
    <button
      id="btn-save"
      class="tool-btn"
      type="button"
      aria-describedby="tip-save"
      data-tooltip="tip-save"
      style="anchor-name: --anchor-save;"
    >
      Save
    </button>

    <button
      id="btn-menu"
      class="tool-btn"
      type="button"
      popovertarget="more-menu"
      aria-haspopup="menu"
      aria-describedby="tip-menu"
      data-tooltip="tip-menu"
      style="anchor-name: --anchor-menu;"
    >
      More
    </button>
  </div>

  <div id="more-menu" popover="auto" role="menu">
    <button
      class="tool-btn"
      type="button"
      role="menuitem"
      aria-describedby="tip-export"
      data-tooltip="tip-export"
      style="anchor-name: --anchor-export;"
    >
      Export Markdown
    </button>
  </div>

  <div id="tip-save" class="tooltip-hint" popover="hint" role="tooltip" style="position-anchor: --anchor-save;">
    Save draft to local storage
  </div>
  <div id="tip-menu" class="tooltip-hint" popover="hint" role="tooltip" style="position-anchor: --anchor-menu;">
    Open additional document actions
  </div>
  <div id="tip-export" class="tooltip-hint" popover="hint" role="tooltip" style="position-anchor: --anchor-export;">
    Download clean .md source file
  </div>

  <script>
    const supportsHintPopover = (() => {
      const probe = document.createElement('div');
      probe.setAttribute('popover', 'hint');
      return probe.popover === 'hint';
    })();

    const triggers = document.querySelectorAll('[data-tooltip]');

    for (const trigger of triggers) {
      const tipId = trigger.dataset.tooltip;
      const tip = document.getElementById(tipId);
      if (!tip) continue;

      // Progressive fallback for browsers without native popover="hint"
      if (!supportsHintPopover) {
        tip.setAttribute('popover', 'manual');
      }

      let showTimer = null;

      const positionFallback = () => {
        if (CSS.supports('position-area: top')) return;
        const rect = trigger.getBoundingClientRect();
        tip.style.left = `${Math.max(8, rect.left)}px`;
        tip.style.top = `${Math.max(8, rect.top - tip.offsetHeight - 8)}px`;
      };

      const openTip = () => {
        clearTimeout(showTimer);
        showTimer = setTimeout(() => {
          if (!tip.matches(':popover-open')) {
            tip.showPopover({ source: trigger });
            positionFallback();
          }
        }, 120);
      };

      const closeTip = () => {
        clearTimeout(showTimer);
        if (tip.matches(':popover-open')) {
          tip.hidePopover();
        }
      };

      trigger.addEventListener('pointerenter', (event) => {
        if (event.pointerType !== 'touch') openTip();
      });
      trigger.addEventListener('pointerleave', closeTip);
      trigger.addEventListener('focusin', openTip);
      trigger.addEventListener('focusout', closeTip);
      trigger.addEventListener('keydown', (event) => {
        if (event.key === 'Escape') closeTip();
      });
    }
  </script>
</body>
</html>

Main Point: Using popover="hint" isolates lightweight tooltips into their own ephemeral top-layer tier so hovering or focusing controls never dismisses active auto menus or dialogs while still preserving native Escape and light-dismiss behavior.

Credits

Photo by Johannes Plenio on Unsplash

← Home