- Vesyl UI

A small label that appears on hover or focus to explain a control. Built on base-ui Tooltip — focus handling, hover intent, and ARIA wiring come for free.

Compose three parts: Tooltip (root), TooltipTrigger (the element that reveals it — pass an interactive control via render so the tooltip is keyboard-reachable), and TooltipContent (the label, portaled with an arrow). Each Tooltip self-wraps in a TooltipProvider, so a single tooltip needs no extra setup; wrap a group in your own TooltipProvider only to share the open delay between them.

Reach for a tooltip for short, non-interactive labels keyed to a control. For richer, hoverable content — avatars, summaries, links — use HoverCard; for click-triggered interactive panels use Popover.

Basic

A Tooltip wraps a trigger and its content. Pass the trigger control through render on TooltipTrigger so the tooltip opens on both hover and keyboard focus. Hover (or tab to) the button to reveal the label.

import { Button, Tooltip, TooltipContent, TooltipTrigger } from "@vesyl/ui-next";

export default function TooltipBasic() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" size="sm" />}>
        Print labels
      </TooltipTrigger>
      <TooltipContent>Generate PDF labels for the selected shipments</TooltipContent>
    </Tooltip>
  );
}

Positioning

TooltipContent accepts side ("top" default, "right", "bottom", "left") to choose where it opens relative to the trigger, plus sideOffset for the gap and align / alignOffset to shift it along that edge. The arrow tracks the chosen side automatically.

import { Button, HStack, Tooltip, TooltipContent, TooltipTrigger } from "@vesyl/ui-next";

export default function TooltipPositioning() {
  return (
    <HStack gap={8} justify="center">
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="sm" />}>Top</TooltipTrigger>
        <TooltipContent side="top">Opens above the trigger</TooltipContent>
      </Tooltip>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="sm" />}>Right</TooltipTrigger>
        <TooltipContent side="right">Opens to the right</TooltipContent>
      </Tooltip>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="sm" />}>Bottom</TooltipTrigger>
        <TooltipContent side="bottom">Opens below the trigger</TooltipContent>
      </Tooltip>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" size="sm" />}>Left</TooltipTrigger>
        <TooltipContent side="left">Opens to the left</TooltipContent>
      </Tooltip>
    </HStack>
  );
}

Shared delay

By default each tooltip opens instantly (delay={0}). Wrap a group of triggers in a TooltipProvider to give them a shared open delay — once one tooltip in the group has opened, its neighbors open instantly until the group’s timeout elapses. This is the icon-toolbar pattern: a brief hesitation before the first label, then snappy hops between buttons.

import {
  Button,
  HStack,
  Tooltip,
  TooltipContent,
  TooltipProvider,
  TooltipTrigger,
} from "@vesyl/ui-next";
import { Printer, RefreshCcw, Tag, Trash2 } from "lucide-react";

export default function TooltipProviderDemo() {
  return (
    <TooltipProvider delay={600} closeDelay={0}>
      <HStack gap={2} justify="center">
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline" size="icon-sm" aria-label="Print labels" />}>
            <Printer />
          </TooltipTrigger>
          <TooltipContent>Print labels</TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline" size="icon-sm" aria-label="Buy postage" />}>
            <Tag />
          </TooltipTrigger>
          <TooltipContent>Buy postage</TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline" size="icon-sm" aria-label="Refresh rates" />}>
            <RefreshCcw />
          </TooltipTrigger>
          <TooltipContent>Refresh rates</TooltipContent>
        </Tooltip>
        <Tooltip>
          <TooltipTrigger render={<Button variant="outline" size="icon-sm" aria-label="Void shipment" />}>
            <Trash2 />
          </TooltipTrigger>
          <TooltipContent>Void shipment</TooltipContent>
        </Tooltip>
      </HStack>
    </TooltipProvider>
  );
}

Reference

Root container. Self-wraps in a TooltipProvider. Extends base-ui Tooltip.Root props.

Prop	Type	Default	Description
`defaultOpen`	`boolean`	`false`	Whether the tooltip is initially open (uncontrolled)
`open`	`boolean`	—	Controlled open state
`onOpenChange`	`(open, eventDetails) => void`	—	Fires when the tooltip opens or closes
`disabled`	`boolean`	`false`	Disables the tooltip
`disableHoverablePopup`	`boolean`	`false`	When `false`, the popup can be hovered without closing
`trackCursorAxis`	`"none" \| "x" \| "y" \| "both"`	`"none"`	Which axis the tooltip follows the cursor on

TooltipTrigger

The element that reveals the tooltip. Pass an interactive control through render so it stays keyboard-reachable. Extends base-ui Tooltip.Trigger props.

Prop	Type	Default	Description
`render`	`ReactElement \| (props) => …`	—	Renders the trigger as this element (e.g. a `Button`) instead of the default span

TooltipContent

The label. Portaled, with an arrow that tracks side. Extends base-ui Tooltip.Popup props plus the positioning props below.

Prop	Type	Default	Description
`side`	`"top" \| "right" \| "bottom" \| "left"`	`"top"`	Which side of the trigger the tooltip opens on
`sideOffset`	`number`	`4`	Gap in px between the trigger and the tooltip
`align`	`"start" \| "center" \| "end"`	`"center"`	Alignment along the chosen side
`alignOffset`	`number`	`0`	Shift in px along the alignment axis
`className`	`string`	—	Merged onto the popup

TooltipProvider

Optional. Shares an open delay across the tooltips it wraps. Extends base-ui Tooltip.Provider props.

Prop	Type	Default	Description
`delay`	`number`	`0`	How long to wait, in ms, before opening a tooltip
`closeDelay`	`number`	—	How long to wait, in ms, before closing a tooltip
`timeout`	`number`	`400`	Within this window after one tooltip closes, the next opens instantly
`delayDuration`	`number`	—	Deprecated. Use `delay` instead