Skip to content

Tooltip

Extra detail about a control, on hover and on focus, built on the Popover API.

<div class="cap-specimen-row">
  <button type="button" class="cap-btn" data-cap-tip="tip-retry" id="sample-retry">Retry job</button>
  <div class="cap-popover" data-cap="tooltip" id="tip-retry" popover="manual" role="tooltip" data-variant="tooltip" data-side="top">Runs job_7c21 again with the same inputs. Its last run failed at 14:02.<span class="cap-popover-arrow" aria-hidden="true"></span></div>
  <button type="button" class="cap-btn" id="sample-next">Cancel job</button>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import { enhance } from "capsomer/behavior/tooltip";

enhance();

Usage

<button type="button" class="cap-btn" data-cap-tip="tip-retry">Retry job</button>
<div class="cap-popover" data-cap="tooltip" id="tip-retry" popover="manual" role="tooltip" data-variant="tooltip" data-side="top">Runs job_7c21 again with the same inputs. <kbd>R</kbd><span class="cap-popover-arrow" aria-hidden="true"></span></div>
<Tooltip tip="Runs job_7c21 again with the same inputs." side="top" arrow>
  {(t) => <button type="button" className="cap-btn" {...t}>Retry job</button>}
</Tooltip>

Examples

Shown on hover, with an arrow

<div class="cap-specimen-row">
  <button type="button" class="cap-btn" data-cap-tip="tip-copy" data-specimen-open>Copy commit</button>
  <div class="cap-popover" data-cap="tooltip" id="tip-copy" popover="manual" role="tooltip" data-variant="tooltip" data-side="top">Copies 366b902 to the clipboard.<span class="cap-popover-arrow" aria-hidden="true"></span></div>
</div>

Shown on focus, below the trigger

<div class="cap-specimen-row">
  <p>Checks for <a href="#s-focus" data-cap-tip="tip-site" data-specimen-open>example.com</a> are failing.</p>
  <div class="cap-popover" data-cap="tooltip" id="tip-site" popover="manual" role="tooltip" data-variant="tooltip" data-side="bottom">3 failed checks since 13:40. It last answered at 14:02.<span class="cap-popover-arrow" aria-hidden="true"></span></div>
</div>

With the shortcut

<div class="cap-specimen-row">
  <button type="button" class="cap-btn" data-cap-tip="tip-refresh" data-specimen-open>Refresh</button>
  <div class="cap-popover" data-cap="tooltip" id="tip-refresh" popover="manual" role="tooltip" data-variant="tooltip" data-side="top">Reload the queue <kbd>R</kbd></div>
</div>

Comfortable density

<div class="cap-specimen-row" data-density="comfortable">
  <button type="button" class="cap-btn" data-cap-tip="tip-comfortable" data-specimen-open>Copy commit</button>
  <div class="cap-popover" data-cap="tooltip" id="tip-comfortable" popover="manual" role="tooltip" data-variant="tooltip" data-side="top">Copies 366b902 to the clipboard.<span class="cap-popover-arrow" aria-hidden="true"></span></div>
</div>

API reference

Tooltip

PropTypeRequiredDoes
tipReactNodeYesExtra detail only. The trigger has its own visible label or accessible name.
children(trigger: TriggerProps) => ReactNodeYesRenders the trigger, a focusable element, with these props spread on it: {(t) => <button type="button" className="cap-btn" {...t}>Retry job</button>}
side"top" | "bottom" | "left" | "right" | "inline-start" | "inline-end"Where the tip sits: above the trigger by default, as shadcn's Tooltip.
align"start" | "center" | "end"
arrowbooleanThe small arrow pointing at the trigger. On by default.
as"div" | "span"The tip's element. "span" keeps it valid inside phrasing content such as a <p>; the tip is then phrasing content too (no block children).

Functions

FunctionSignatureDoes
attach(trigger: HTMLElement, tip: HTMLElement): () => voidWires one trigger to its tip: the tip gets the popover surface (cap-popover, the tooltip variant), popover="manual" and role="tooltip", and the trigger aria-describedby. Returns a function that unwires it.
showTip(trigger: HTMLElement): voidShows or hides the tip of a trigger that is attached.
hideTip(trigger: HTMLElement): void
enhance(root?: ParentNode): () => voidAttaches to every [data-cap-tip] trigger under root not yet attached; the attribute's value is the id of its tip. Returns a function that detaches.

Accessibility

KeyDoes
Tab to the triggerShows the tip at once
EscHides the tip; focus stays on the trigger
Tab away (blur)Hides the tip
  • The trigger keeps its own name; the tip is its description.
  • Tip text is --text on --raised, far above 4.5:1 in both themes; its edge is 3:1 against the page.
  • Touch: there is no hover, so a tip's detail must never be needed.
  • Forced colors: the tip gains an edge.