Tooltip

Material Design 3 brief floating label for contextual descriptions on hover and keyboard focus. Not intended for critical instructions or required form guidance that users must read before acting.

Basic Usage

Attach a tooltip to a target by referencing the target id. Tooltips reveal supplemental context without adding permanent on-screen text.

Helpful context 
<button id="tooltip-basic-target">Hover or focus me</button>
<ds-tooltip for="tooltip-basic-target">Helpful context</ds-tooltip>

Initial Value

Configure initial position and delay through attributes.

Opens immediately below 
<ds-tooltip for="tooltip-initial-target" position="bottom" delay="0">
  Opens immediately below
</ds-tooltip>

Variants

Use position to set fixed placement, or keep auto for viewport-aware placement.

Auto (Default)

Auto positioned tooltip

Fixed Positions

Top tooltip
Bottom tooltip
Left tooltip
Right tooltip 
<ds-tooltip for="tooltip-top-target" position="top">Top tooltip</ds-tooltip>
<ds-tooltip for="tooltip-bottom-target" position="bottom">Bottom tooltip</ds-tooltip>
<ds-tooltip for="tooltip-left-target" position="left">Left tooltip</ds-tooltip>
<ds-tooltip for="tooltip-right-target" position="right">Right tooltip</ds-tooltip>

States

Tooltip visibility is controlled by hover/focus and the configured delay.

Appears immediately
Appears after 500ms
Appears after 1 second 
<ds-tooltip for="tooltip-delay-0" delay="0">Appears immediately</ds-tooltip>
<ds-tooltip for="tooltip-delay-default">Appears after 500ms</ds-tooltip>
<ds-tooltip for="tooltip-delay-long" delay="1000">Appears after 1 second</ds-tooltip>

Interactive Example

Change tooltip position and delay, then focus or hover the target to inspect emitted lifecycle events.

Interactive tooltip message 
Event log:

API

Attributes

Attribute Type Default Description
for string previous sibling Target element id. When omitted, previous sibling is used.
position string auto auto, top, bottom, left, or right.
delay number 500 Delay in milliseconds before showing the tooltip.

Properties

Property Type Description
position string Reflects the position attribute.
delay number Reflects the delay attribute.

Events

Event Detail Description
ds-tooltip:show { position, targetId } Fired when the tooltip becomes visible.
ds-tooltip:hide { targetId } Fired when the tooltip is hidden.

Methods

Method Description
show() Schedules tooltip visibility using delay.
hide() Clears pending show timeout and hides immediately.
updatePosition() Recomputes placement against viewport boundaries.

CSS Parts

Part Description
None This component currently does not expose shadow parts.

CSS Custom Properties

Property Description
--ds-tooltip-max-inline-size Maximum tooltip width. Default 12.5rem.
--ds-tooltip-padding-block Vertical padding. Default var(--ds-space-1).
--ds-tooltip-padding-inline Horizontal padding. Default var(--ds-space-2).
--ds-tooltip-offset Distance between target and tooltip. Default var(--ds-space-2).
--ds-tooltip-arrow-size Arrow size. Default var(--ds-space-1).

Accessibility

Keyboard Interaction

Key Context Expected Result
Tab Focusable target present Moves focus to target and shows tooltip after delay
Shift+Tab Focus on target Moves focus away and hides tooltip
Escape Tooltip visible Hides tooltip when supported by host behavior

Semantics

  • Tooltip content uses role="tooltip".
  • Target elements receive aria-describedby linkage.
  • Tooltip is non-interactive and does not capture pointer events.

Usage Guidelines

  • When to use: Use tooltips for short supplemental descriptions of controls, icons, and abbreviated labels.
  • When not to use: Avoid tooltips for required instructions, validation errors, or content users must read on touch-only devices.
  • Composition: Keep copy short, prefer position="auto" for viewport-aware placement, and tune delay for workflow speed.
  • Common mistakes: Long tooltip text becomes hard to scan and can obscure nearby UI. Keep tooltips non-interactive.