Tooltip Component — Astro

Accessible tooltip component with positioning options and hover states

Tooltip Component

An accessible tooltip component that provides additional context or information when users hover over or focus on an element. Tooltips are positioned relative to their trigger element and support multiple positions.

Basic Usage

Wrap any element with a tooltip wrapper and include the Tooltip component:

Basic Tooltip
astro astro 
---
import Tooltip from '../../components/Tooltip.astro';
---

<div class="tooltip-wrapper" aria-describedby="tooltip-basic">
  <button class="btn btn-primary">Hover me</button>
  <Tooltip id="tooltip-basic" text="This is a basic tooltip" position="top" />
</div>

Positions

Tooltips can be positioned in four directions: top, bottom, left, or right.

Position Examples
astro astro 
<!-- Top position -->
<div class="tooltip-wrapper" aria-describedby="tooltip-top">
  <button>Hover me</button>
  <Tooltip id="tooltip-top" text="Tooltip on top" position="top" />
</div>

<!-- Bottom position -->
<div class="tooltip-wrapper" aria-describedby="tooltip-bottom">
  <button>Hover me</button>
  <Tooltip id="tooltip-bottom" text="Tooltip on bottom" position="bottom" />
</div>

<!-- Left position -->
<div class="tooltip-wrapper" aria-describedby="tooltip-left">
  <button>Hover me</button>
  <Tooltip id="tooltip-left" text="Tooltip on left" position="left" />
</div>

<!-- Right position -->
<div class="tooltip-wrapper" aria-describedby="tooltip-right">
  <button>Hover me</button>
  <Tooltip id="tooltip-right" text="Tooltip on right" position="right" />
</div>

With Different Elements

Tooltips work with any element - buttons, links, icons, badges, etc.

Tooltip Examples
Hover link
New

Long Text

Tooltips automatically wrap long text and have a maximum width:

Long Text Tooltip

Props

  • text (string, required) - The tooltip text content
  • position ('top' | 'bottom' | 'left' | 'right', optional) - Tooltip position relative to trigger element (default: 'top')
  • delay (number, optional) - Delay in milliseconds before showing tooltip (default: 0)
  • id (string, optional) - Unique ID for the tooltip. If not provided, a random ID will be generated
  • class (string, optional) - Additional CSS classes

Features

  • Four position options (top, bottom, left, right)
  • Automatic arrow positioning
  • Accessible with ARIA attributes
  • Keyboard accessible (works with focus states)
  • Theme-aware styling using semantic variables
  • Smooth animations (respects prefers-reduced-motion)
  • Automatic text wrapping for long content
  • Maximum width constraint for readability

Accessibility

The Tooltip component includes comprehensive accessibility features:

  • ARIA Attributes: Uses role="tooltip" and aria-describedby pattern
  • Keyboard Support: Tooltips appear on focus for keyboard users
  • Screen Reader Support: Tooltip content is associated with the trigger element
  • Focus Management: Tooltips work with :focus-within for proper focus handling

Proper Usage

Always use aria-describedby on the trigger element to associate it with the tooltip:

astro astro 
<div class="tooltip-wrapper" aria-describedby="my-tooltip">
  <button>Hover me</button>
  <Tooltip id="my-tooltip" text="Tooltip text" />
</div>

Styling

Tooltips use semantic theme variables and automatically adapt to the selected theme:

  • Background: var(--text) (uses text color for high contrast)
  • Text: var(--background) (uses background color for contrast)
  • Shadow: var(--shadow-lg) for depth

Svelte & Vanilla: Svelte ¡ Vanilla: same HTML and BEM as in Usage above; add minimal JS for show/hide and position.