Overlays

Tooltip

A brief, non-interactive description shown from pointer, focus, or touch.

TooltipTooltipPropsTooltipPosition

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

'use client';

import { Button, Tooltip } from '@ai-created/ui';

export function Example() {
  return (
    <Tooltip
      content={"Copy link"}
      delay={300}
    >
      <Button variant="secondary">Copy</Button>
    </Tooltip>
  );
}

Import

tsx

import { Tooltip } from '@ai-created/ui';

Client boundary

Add 'use client' to the file that owns this interactive state.

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Wrapper

Required

Inline trigger measurement context.

span

Trigger

Required

Exactly one cloned focusable element.

Tooltip bubble

Required

Portalled, viewport-positioned description associated while visible.

[role=tooltip]

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Overlays/Tooltip

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish position and visibility variants attached to an example trigger.

Auto layout

Direction: horizontal
Gap: 0px
Padding: 6px 12px
Alignment: Center
Wrap: Text wraps up to maximum width

Resizing

Width: hug
Height: hug
Minimum width: Content width
Maximum width: 240px
Minimum height: Content controlled
Maximum height: Content controlled
Overflow: visible

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
ContentRequired	text	Helpful information	content	No additional constraint
Position	variant	top	position	top, bottom, left, right
Delay	number	300	delay	No additional constraint
Visible preview	boolean	true	Internal interaction state; no public prop	No additional constraint
TriggerRequired	instance-swap	None	children	No additional constraint

Nested assets and slots

Trigger

slot / required

One focusable element that owns described-by state.

children

Tooltip bubble

primitive / required

Positioned supplemental text.

<span role="tooltip">

Content limits

Content

One short sentence, maximum about 120 characters

Overflow: Wrap up to 240px; move longer guidance into persistent UI.

Tooltips are supplemental and transient.

Children

Exactly one focusable trigger

Overflow: Wrap compound visuals in one semantic control.

Focus and described-by must have one owner.

Localization and RTL

Translatable: Content

Position uses physical sides today; choose the appropriate side for the layout direction.
Text follows locale direction.
Test 240px maximum width.
Test touch, keyboard, and pointer access with translated text.

Responsive behavior

Bubble hugs content, portals to the document, flips when the opposite side fits, and clamps within an 8px viewport inset.

No internal breakpoint

Preferred physical side remains consumer-selected.
Do not depend on tooltip access for essential mobile instructions.

Authoring limits

Figma hover prototypes do not cover delayed focus, pointer travel, Escape, touch toggling, outside touch, viewport collision, or aria-describedby.
Keep content supplemental, plain text, and non-interactive.

Accountable owner

Design systems overlay primitive owner

Canonical source: src/components/Tooltip.tsx

Timing or trigger-event changes require input-modality and accessibility testing.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Bubble padding

12px horizontal / 6px vertical

Trigger offset

8px

Viewport inset

8px minimum

Maximum width

240px

Radius

6px

Entrance

200ms fade

Rules

Keep content brief, plain text, and non-interactive.
Preferred placement flips when its opposite side has available space and clamps to the viewport.
Do not hide essential instructions in the tooltip.

Token dependencies

--color-surface

Bubble background.

--color-border

Bubble border.

--color-text2

Tooltip text.

--radius-md

Bubble radius.

--shadow-elevation-medium / --layer-tooltip

Portalled elevation and stacking.

--motion-fast

Entrance fade.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

hidden

Trigger: No active pointer, focus, or toggled touch.
Visual response: Bubble is not mounted.
Behavior: Trigger retains its original aria-describedby.

visible

Trigger: Pointer hover remains for delay milliseconds.
Visual response: Bubble appears at the resolved viewport position.
Behavior: Pointer may cross onto the bubble without dismissing it; leaving both hides after a short bridge delay.
Accessibility: Tooltip id is appended to aria-describedby while visible.

focused

Trigger: Trigger receives focus for delay milliseconds.
Visual response: Same bubble as hover.
Behavior: Blur hides it.

touch-visible

Trigger: Trigger receives touchstart.
Visual response: Bubble toggles immediately.
Behavior: Another touch or outside touch hides it.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: role=tooltip associated through aria-describedby only while visible.
Accessible name: content provides the supplemental description; the trigger still needs its own accessible name.

Wrap exactly one focusable trigger.
Preserve existing trigger event handlers and aria-describedby; the component composes them.
Keep content non-interactive and supplemental.
Do not use the tooltip as the accessible name of an icon button.

Keyboard behavior

Tab / Shift+Tab: Focuses the child trigger; tooltip appears after delay.
Escape: Dismisses the tooltip without moving focus.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { Tooltip } from '@ai-created/ui';

Client Component required

The child element is cloned to compose hover, focus, blur, and touch handlers.
Show and hover-bridge timeouts are cleared on hide and unmount.
The bubble portals to document.body, flips to the opposite side when needed, clamps to the viewport, and tracks scroll/resize.
Escape and outside touch listeners exist only while visible.

tsx

<Tooltip content="Copy link"><Button variant="icon" aria-label="Copy link">...</Button></Tooltip>

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
content	string	required	Tooltip text.
position	TooltipPosition	top	top, bottom, left, or right.
delay	number	300	Show delay in milliseconds.
children	ReactElement	required	Trigger element.
className	string	undefined	Additional tooltip classes.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Use to explain an unfamiliar icon or compact control.
Keep one short sentence or phrase.

Do not

Do not put links, buttons, or form fields inside.
Do not repeat a visible label verbatim without adding value.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Composes existing child handlers and aria-describedby.
Clears timers and temporary listeners.

Interaction

Hover/focus delay, pointer travel onto the bubble, Escape, leave/blur, touch toggle, outside touch, flip, clamp, scroll, and resize behave correctly.

Accessibility

Role, id relationship, trigger name, Escape dismissal, and keyboard discoverability are valid.

Visual

Capture all positions, viewport edges, wrapping at max width, focus/hover visibility, and themes.

Related specifications

button