st-tooltip

Basic Usage

Add the data-tooltip attribute to any element to show a tooltip on hover:

<button data-tooltip="Save changes">
  <svg><!-- save icon --></svg>
</button>

With Keyboard Shortcut

Add data-shortcut to display a keyboard shortcut alongside the tooltip text:

<button data-tooltip="Toggle sidebar" data-shortcut="⌘B">
  <svg><!-- sidebar icon --></svg>
</button>

The shortcut is displayed in a kbd-styled inline element after the tooltip text.

How It Works

• Tooltips appear after a 350ms hover delay
• A single tooltip element is reused across the page for performance
• Positioned to the right of the trigger element
• Dismissed on mouseout or Escape key
• Uses role="tooltip" and aria-hidden for accessibility

Sidebar Integration

The st-sidebar component automatically shows tooltips for .nav-item elements when in rail (collapsed) mode. No additional configuration needed:

<st-sidebar>
  <nav>
    <a href="/dashboard" class="nav-item" data-tooltip="Dashboard">
      <svg><!-- icon --></svg>
      <span>Dashboard</span>
    </a>
  </nav>
</st-sidebar>

When the sidebar is expanded, tooltips are automatically suppressed since the text labels are visible.

Programmatic API

The tooltip manager is exported and can be used to attach tooltips to custom regions:

import { tooltipManager } from '@stellisoft/stellify-ui'

// Attach tooltip handling to a container
const scope = tooltipManager.attach(containerElement, {
  // Optional: conditionally show tooltips
  shouldShow: (event) => someCondition
})

// Later: clean up
scope.detach()

Styling

The tooltip element has the class st-tooltip and uses data-visible for show/hide state:

.st-tooltip {
  position: fixed;
  z-index: 50;
  padding: 0.5rem 0.75rem;
  background: var(--popover, #18181b);
  color: var(--popover-foreground, #fafafa);
  border-radius: 0.375rem;
  font-size: 0.875rem;
  pointer-events: none;
  opacity: 0;
  transition: opacity 150ms;
}

.st-tooltip[data-visible="true"] {
  opacity: 1;
}

.st-tooltip .kbd-inline {
  margin-left: 0.5rem;
  padding: 0.125rem 0.375rem;
  background: rgba(255, 255, 255, 0.1);
  border-radius: 0.25rem;
  font-family: monospace;
  font-size: 0.75rem;
}