Fluid Tooltip Component

A grouped tooltip system that preserves spatial orientation while people scan related icon controls.

Features

Uses a deliberate first pointer delay, then opens sibling tooltips immediately.
Moves new labels eight pixels from left or right in horizontal groups and from top or bottom in vertical groups.
Keeps the tooltip surface continuous while its anchor and content change.
Places horizontal tooltips above their triggers and vertical tooltips to the right by default, with collision-aware flipping.
Shows keyboard tooltips immediately without directional travel.
Removes travel for reduced-motion preferences and leaves coarse-pointer controls usable.
Built on Base UI for tooltip semantics, positioning, collision handling, and accessible descriptions.

Playground

Adjust the group delay and orientation, then move between the controls.

Controls

Orientation

First open delay (ms)350

Close delay (ms)100

Disable tooltips

Installation

npx shadcn@latest add @sona-ui/fluid-tooltip

Usage


const items = [
  { id: "home", label: "Home", icon: Home },
  { id: "search", label: "Search", icon: Search },
  { id: "notifications", label: "Notifications", icon: Bell },
  { id: "settings", label: "Settings", icon: Settings },
];
 
export default function FluidTooltipDemo() {
  return (
    <FluidTooltip.Group orientation="horizontal">
      <div className="flex items-center gap-1 rounded-2xl border border-border bg-muted/60 p-1.5">
        {items.map((item) => (
          <FluidTooltip.Root key={item.id} id={item.id}>
            <FluidTooltip.Trigger asChild>
              <button
                type="button"
                aria-label={item.label}
                className="grid size-10 place-items-center rounded-xl text-muted-foreground outline-none transition-colors duration-150 hover:bg-background hover:text-foreground focus-visible:bg-background focus-visible:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
              >
                <item.icon aria-hidden="true" className="size-4" />
              </button>
            </FluidTooltip.Trigger>
            <FluidTooltip.Content>{item.label}</FluidTooltip.Content>
          </FluidTooltip.Root>
        ))}
      </div>
    </FluidTooltip.Group>
  );
}

Props

Property	Type	Default	Description
`children`	`ReactNode`	`required`	Related tooltip roots rendered inside the group.
`orientation`	`FluidTooltipOrientation`	`"auto"`	Axis used to calculate directional content entry.
`openDelay`	`number`	`350`	Delay before the first pointer tooltip opens, in milliseconds.
`closeDelay`	`number`	`100`	Grace period before a pointer tooltip closes, in milliseconds.
`disabled`	`boolean`	`false`	Disables tooltip behavior for every trigger in the group.
`className`	`string`	`undefined`	Additional CSS classes for the positioned tooltip surface.