Components

Tooltip

A short, non-interactive hint attached to a trigger.

Basic example

Installation

Choose the package when you want centralized updates, or copy the source through the registry when you want local ownership.

@constructive-io/ui

Install the package, import its global tokens once, then use this exact subpath.

# install

pnpm add @constructive-io/ui

# app/globals.css

@import '@constructive-io/ui/globals.css';

# import

import { Tooltip } from '@constructive-io/ui/tooltip';

When to use

Use Tooltip for a short, non-interactive hint that clarifies an otherwise understandable control.
Use Popover when the surface needs links, fields, or actions. Keep essential instructions and error messages visible instead of placing them only in a tooltip.

Basic usage

Wrap related tooltips in TooltipProvider, then compose TooltipTrigger and TooltipContent inside each Tooltip root. Use render for Base UI composition or asChild for compatibility, and match the visible hint to the trigger purpose.

npm source

tsx

'use client';
import { Plus } from 'lucide-react';
import { Button } from '@constructive-io/ui/button';
import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@constructive-io/ui/tooltip';
export function BasicTooltipDemo() {
    return (<TooltipProvider>
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline" size="icon" aria-label="Create database"/>}>
            <Plus aria-hidden="true"/>
          </TooltipTrigger>
          <TooltipContent>Create database</TooltipContent>
        </Tooltip>
      </TooltipProvider>);
}

Controlled and uncontrolled open state

Tooltip normally owns its hover and focus state. Pass open and onOpenChange only when another interaction must synchronize the hint; keep pointer and keyboard access intact.

Controlled and uncontrolled open state

Examples

01Placement, arrow, and delaySet delay on the provider or trigger, choose a side, and show the arrow when it improves spatial clarity.

02Disabled triggerRender the trigger on a focusable wrapper when a disabled control other than Button cannot emit pointer or focus events. A disabled Button needs no wrapper.

Resolve validation errors before deploying.

Accessibility

Keep TooltipContent concise and non-interactive. A tooltip supplements the trigger name and cannot replace a persistent label for unfamiliar controls.
Make the trigger keyboard focusable. A disabled Button used as the trigger (asChild or render) stays hoverable and focusable: it is marked aria-disabled instead of disabled, in place and without a wrapper, so its layout and state do not change. A disabled control of another kind cannot emit pointer or focus events, so attach TooltipTrigger to a focusable wrapper you provide.
Base UI opens tooltips from hover or focus, closes them on Escape, and preserves the relationship through the portal chain.

API Reference

Constructive-specific behavior is listed here. Each part links to its inherited platform or primitive contract.

TooltipProvider

Coordinates open delays and behavior across related tooltips.

Prop	Type	Default	Description
delay	number	0	Delay in milliseconds before opening.
delayDurationdeprecated	number	—	Compatibility alias for delay.

Also accepts Base UI Tooltip props.

Tooltip

Root that owns or receives tooltip visibility.

Prop	Type	Default	Description
open	boolean	—	Controlled open state.
defaultOpen	boolean	—	Initial open state in uncontrolled usage.
onOpenChange	Base UI callback	—	Runs when visibility changes.
delayDurationdeprecated	number	—	Compatibility prop; set delay on TooltipTrigger instead.

Also accepts Base UI Tooltip props.

TooltipTrigger

Element whose hover or focus state opens the tooltip.

Prop	Type	Default	Description
delay	number	0	Trigger-specific opening delay.
render	ReactElement \| render function	—	Preferred Base UI composition API.
asChild	boolean	false	Compatibility composition API.

Also accepts Base UI Tooltip props.

TooltipContent

Portal, positioner, popup, and optional arrow composition.

Prop	Type	Default	Description
side	'top' \| 'right' \| 'bottom' \| 'left'	'top'	Preferred side of the trigger.
align	'start' \| 'center' \| 'end'	'center'	Alignment along the trigger edge.
sideOffset	number	4	Distance from the trigger.
showArrow	boolean	false	Renders an arrow pointing toward the trigger.

Also accepts Base UI Tooltip props.