Fluid Tooltip

Use Fluid Tooltip for a related group of compact controls. One tooltip surface follows the active trigger, so labels remain oriented as someone scans a toolbar or navigation group.

Preview

Reduce motion:Off

Tune:Off

Inspect

Installation

Base UI Motion

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

Basic usage

toolbar-tooltips.tsx

import FluidTooltip from "@/components/ui/fluid-tooltip/fluid-tooltip";
 
export function ToolbarTooltips() {
return (
  <FluidTooltip.Group orientation="horizontal">
    <FluidTooltip.Root>
      <FluidTooltip.Trigger>Search</FluidTooltip.Trigger>
      <FluidTooltip.Content>Search this page</FluidTooltip.Content>
    </FluidTooltip.Root>
  </FluidTooltip.Group>
);
}

Examples

Use a horizontal group for toolbars and a vertical group for stacked controls. The first pointer tooltip observes the configured delay, while adjacent tooltips open immediately.

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>
  );
}

API

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.

Accessibility

Fluid Tooltip uses Base UI tooltip semantics, collision-aware positioning, and accessible descriptions. Keyboard focus opens the relevant label immediately without directional travel.

Styling

Use the group orientation and component class names to fit the control group. Reduced-motion preferences remove content travel while preserving the label.

Contact

Found a bug or need help using this component? Open an issue on GitHub.

License & Usage

Sona UI is available under the MIT license. You may use, modify, and distribute this component in personal and commercial projects.

Sona UI