Tooltip

Short hint anchored to an element. It shows on pointer, keyboard focus and touch: a hint that only responds to the mouse doesn't exist for keyboard users, and never shows on a phone, where there's no hover.

Examples

Side and alignment are the same as shadcn's, and so is the default: top-center.

How to use

The text goes in the attribute itself, and it initializes on its own, including whatever arrives later through HTMX.

<button data-tuc-tip="Generates the PDF with the current layout">Export</button>
<button data-tuc-tip="..." data-placement="right-center" data-delay="600">More</button>
<button data-tuc-tip title="Comes from the title">From title</button>

With an empty data-tuc-tip, the text comes from the title, which is removed: otherwise the browser's native tooltip would show on top of ours. Without the attribute, no title is touched — hijacking every title on the page would be far too intrusive for a library. With neither text nor title, there's nothing to show, and the component logs an error to the console.

In a Django template

<span class="tuc-badge is-warning" data-tuc-tip="Due on {{ contract.due_date|date:'d/m/Y' }}">
  {{ contract.get_status_display }}
</span>

On an element that doesn't receive focus, like that <span>, the component adds tabindex="0": without it the hint wouldn't exist for keyboard users. Buttons, links and fields are already focusable and are left as they are.

In JavaScript

new Tucano.Tooltip('#export', {
  text: 'Generates the PDF',
  placement: 'right-center',
  delay: 350,         // on hover: avoids flicker when the mouse just brushes past
  delayOut: 120,      // on leave
  maxWidth: '20rem',
  className: 'tip-accent',
});

Color

Two variables, and the arrow reads the same ones: changing the bubble's color doesn't detach the tip. Set them for all tooltips, on .tuc-tip, or for a single case, with data-tip-class.

.tip-accent { --tuc-tip-bg: var(--tuc-accent); --tuc-tip-fg: var(--tuc-accent-fg); }
.tip-danger { --tuc-tip-bg: var(--tuc-danger-fill); --tuc-tip-fg: #fff; }
.tip-light  { --tuc-tip-bg: var(--tuc-bg); --tuc-tip-fg: var(--tuc-fg); box-shadow: var(--tuc-shadow); }

<button data-tuc-tip="Only administrators can delete" data-tip-class="tip-danger">Delete</button>

When it shows and when it hides

Only one hint stays open at a time: opening another closes the previous one.

Accessibility

The bubble is a role="tooltip", and the element points to it with aria-describedby: the screen reader reads the hint along with the button, as its description, and not as a stray element on the page.

The hint is text only and doesn't receive the pointer. A link, a button or information the person needs to finish the task doesn't belong in it: anyone who doesn't point at or focus that element will never see it. The arrow is decoration and gets aria-hidden. With prefers-reduced-motion the hint shows and hides without animation.

API

Generated from the code on every build — if something is not here, it does not exist.

Options

The notes in this table come from comments in the source code, which are written in Portuguese.