Tooltip

Introduction

The Tooltip component displays supplemental information in a small popup anchored to a trigger element. It uses the Popover API together with CSS Anchor Positioning, so placement and fallback behavior are handled by the browser.

Interaction pattern

This implementation is activated via a trigger button (popovertarget), which makes it suitable for concise helper content users intentionally reveal.

Modern API support and fallback strategy

Tooltip intentionally leans on newer platform APIs (Popover API, CSS Anchor Positioning, and @starting-style) to reduce custom JavaScript and align with future browser-native UI patterns. The component still uses defensive CSS behavior and robust ARIA relationships for accessibility, but some positioning and animation features remain newer and may degrade in older/other browser engines.

When to use

Use the Tooltip component when you need to:

• Explain icon-only controls
• Add short contextual guidance near an action
• Clarify labels or terms without cluttering the UI
• Show non-critical, supplementary content

Use concise content

Tooltips are best for short supporting text. If users need rich content or interactive controls, use a dialog or drawer instead.

Quick example

Account status More information Your current billing and plan status.

Usage

Learn how to implement the Tooltip component in your project, from simple helper text to positioned variants.

Basic usage

---
import { Tooltip } from 'accessible-astro-components'
---

<Tooltip id="tooltip-help" triggerLabel="More information">
  Profile
  <span slot="tooltip">This is the name visible to other users.</span>
</Tooltip>

Positioning

<Tooltip id="tooltip-right" position="right" triggerLabel="Open help">
  Help
  <span slot="tooltip">This tooltip appears on the right when possible.</span>
</Tooltip>

Icon-only trigger

<Tooltip id="tooltip-icon" triggerLabel="Learn more about notifications">
  <span aria-hidden="true">Notifications</span>
  <span slot="tooltip">Choose when and how you receive updates.</span>
</Tooltip>

Props

Configure the Tooltip component with these available props.

Prop	Type	Default	Description
id	string	-	Unique ID used to connect trigger and tooltip
position	'top' | 'bottom' | 'left' | 'right'	'top'	Preferred tooltip position
offset	string	'var(--space-2xs)'	Distance between trigger and tooltip
triggerLabel	string	undefined	Screen reader label for icon-only or unclear trigger text
showIcon	boolean	true	Show or hide the default help icon
class	string	undefined	Additional wrapper classes

Accessibility

Accessibility is built into the component through semantic trigger markup and descriptive relationships:

• Semantic <button> trigger for keyboard interaction
• aria-describedby linking trigger and tooltip text
• role="tooltip" on the popup content
• Preserved focus visibility from native button behavior
• Reduced motion support through prefers-reduced-motion

Accessible naming

Provide meaningful visible trigger text. When the trigger is icon-only or ambiguous, set triggerLabel so assistive technologies receive a clear accessible name.

Styling

Make the Tooltip component your own while preserving readability and contrast.

Accessibility considerations

When customizing styles, keep sufficient color contrast and preserve visible focus indicators on the trigger.

The component exposes CSS custom properties for spacing and animation behavior:

• --tooltip-offset
• --transition-duration
• --transition-easing
• --translate-offset-x
• --translate-offset-y

You can provide a custom class via the class prop and override styles using global selectors in your project stylesheet.

Interactive examples

See the Tooltip component in action with common usage patterns.

Position examples

Top Info top Tooltip on top (default). Right Info right Tooltip prefers the right side. Left Info left Tooltip prefers the left side. Bottom Info bottom Tooltip prefers the bottom side.

Related components

• Modal
• Drawer
• Notification