Tooltip

Mode

Skin

Theme

Overview & Philosophy

ln-tooltip is applied to any HTML element via data-ln-tooltip="text". In its baseline CSS-first mode, tooltips display instantly on :hover and :focus via styled ::after pseudo-elements with zero JavaScript overhead. Adding data-ln-tooltip-enhance activates the JS top-layer engine: on mouse enter or keyboard focus, it mounts a tooltip bubble into a shared portal (#ln-tooltip-portal), promotes it via the native Popover API (popover="manual") to escape ancestor overflow clipping, and calculates viewport boundary-aware coordinates.

It is engineered on a progressive enhancement model, allowing simple tooltips to remain 100% CSS-driven while complex layouts upgrade to top-layer collision avoidance on demand.

The progressive Tooltip Doctrine

A tooltip is a non-interactive decorative bubble. For interactive panels, menus, or click-triggered overlays, use ln-popover. The CSS baseline handles standard layouts cleanly. The JS portal layer should only be used when escaping ancestor clipping or requiring screen reader descriptions. The `data-ln-tooltip` attribute is the sole contract.

Architectural Design Features

  1. CSS Baseline (Pure CSS, Zero JS): Triggers instantly on hover or keyboard focus using standard pseudo-elements. Super-lightweight, zero bundle size impact.
  2. JS Progressive Portal Layer: Appends the tooltip to a global #ln-tooltip-portal at the body root, allowing tooltips to escape parent containers styled with overflow: hidden.
  3. Viewport-Aware Placement: Preferred positioning (top, bottom, left, right) serves as a starting seed. If the bubble hits the edge of the viewport, the JS layer automatically flips it to the opposite side.
  4. Accessibility Integration: Automatically wires aria-describedby on the active focus target, feeding the tooltip content directly into the browser's accessibility tree for screen readers.

For the full guide see the ln-tooltip README and the architecture reference.

1. CSS baseline — default position (top)

Icon buttons with data-ln-tooltip="…". The default position is top. aria-label is still required for screen readers — the tooltip text is only visual.

2. CSS baseline — all four positions

Override the default with data-ln-tooltip-position="bottom|left|right". The compass layout below places one trigger per position.

3. CSS baseline — on inline text

Hover over ISO 9001 to see the full standard name. This is the pure CSS baseline — no JS runs for elements without a title attribute.

4. JS enhance — side by side

Hover both buttons. Both show a tooltip. Only the enhanced button gets aria-describedby when focused — inspect with DevTools.

Tab to the JS-enhanced button. Open DevTools Elements tab. The button should have aria-describedby="ln-tooltip-1" pointing at a node inside #ln-tooltip-portal.

5. JS enhance — edge auto-flip (right → left)

The last button is pushed to the far right edge of the container. Its preferred side is right. Hover it — the tooltip should appear on the left because there is no room on the right. Inspect data-ln-tooltip-placement on the tooltip node.

6. JS enhance — long-text max-width wrap

The tooltip below has text that exceeds 20 rem. Hover it to verify the max-width: 20rem wraps the text instead of overflowing the viewport.

7. JS enhance — keyboard focus + aria-describedby

Instructions: Tab to the button below. Open DevTools (F12) and switch to the Elements panel. Inspect the button — it should have aria-describedby="ln-tooltip-N". Inspect #ln-tooltip-portal in the body — there should be a <div class="ln-tooltip"> with the matching id. Tab away — both attributes should disappear.

8. JS enhance — auto-attach on [data-ln-tooltip][title]

Any element with both data-ln-tooltip and title auto-enhances — the JS layer attaches without requiring data-ln-tooltip-enhance. The CSS baseline cannot strip title, so the browser's native tooltip would leak alongside the styled one. Auto-enhance resolves this for the semantic <abbr> pattern.

Hover (or tab to) ISO. Open DevTools and watch the title attribute — it is stripped while the styled tooltip is visible and restored on hide. No data-ln-tooltip-enhance flag is required.