Tooltip

Contextual labels that appear when hovering an element. Uses the data-tooltip attribute — no wrapper components or JavaScript required for basic usage.

Preview · Tooltip

Code

HTML · @primus/ui-core

<!-- Add data-tooltip to any element -->
<button data-tooltip="Save all pending changes">Save</button>

<!-- Below position -->
<span data-tooltip="Your unique tenant ID" data-tooltip-pos="bottom">Tenant ID</span>

<!-- On badges -->
<span class="badge warning" data-tooltip="Trial expires in 7 days">Trial</span>

<!-- On disabled buttons (explain why disabled) -->
<button disabled data-tooltip="Requires Admin role">Delete tenant</button>

<!-- Long tooltip text wraps automatically -->
<button data-tooltip="This action will permanently delete the tenant and all associated data. This cannot be undone.">
  Delete
</button>

React

// No import needed — data-tooltip is a plain HTML attribute
// Works after @primus/ui-core JS bundle is loaded

function ActionBar({ record, userRole }) {
  const canDelete = userRole === 'admin';

  return (
    <div className="hstack">
      <button
        data-tooltip="Save all changes"
        onClick={handleSave}>
        Save
      </button>

      <button
        data-tooltip={canDelete
          ? 'Permanently delete this record'
          : 'Admin role required to delete'}
        disabled={!canDelete}
        data-variant="danger">
        Delete
      </button>

      <span
        data-tooltip={`ID: ${record.id}`}
        data-tooltip-pos="bottom"
        style={{ borderBottom: '1px dashed var(--muted-foreground)', cursor: 'help' }}>
        {record.name}
      </span>
    </div>
  );
}

Angular

<!-- Works with static or dynamic values -->
<button data-tooltip="Export as CSV">Export</button>

<!-- Dynamic binding -->
<button
  [attr.data-tooltip]="canExport ? 'Export all records as CSV' : 'Select records first'"
  [disabled]="!canExport">
  Export
</button>

<!-- Below position -->
<span
  [attr.data-tooltip]="'Plan: ' + tenant.plan + ' | Seats: ' + tenant.seats"
  data-tooltip-pos="bottom"
  style="border-bottom:1px dashed var(--muted-foreground);cursor:help">
  {{ tenant.name }}
</span>

API Reference

data-tooltip

Attribute	Value	Description
data-tooltip	string	Tooltip text. Appears on hover/focus.
data-tooltip-pos	'top' (default) | 'bottom' | 'left' | 'right'	Position relative to the element

Auto-conversion

When the @primus/ui-core JS bundle loads, any existing title attributes are automatically converted to data-tooltip — so legacy title="..." patterns will work too.

<!-- These are equivalent after the JS bundle loads -->
<button title="Save changes">Save</button>
<button data-tooltip="Save changes">Save</button>

When to use

Use tooltip for	Don't use tooltip for
Clarifying icon-only buttons	Critical information (use inline text instead)
Explaining disabled states	Long instructions — use a popover or help text
Showing full values that are truncated	Mobile-primary interactions (hover doesn't exist)
Abbreviation expansions	Error messages (use role="alert" instead)

Version history

See the Changelog for version history and breaking changes.