Tooltip

A short label that appears beside an element on hover or keyboard focus.

import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export default function TooltipDemo() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" />}>Hover</TooltipTrigger>
      <TooltipContent>Pin to sidebar</TooltipContent>
    </Tooltip>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/tooltip

Needs the arene setup first.

Usage

import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"
<Tooltip>
  <TooltipTrigger>Hover</TooltipTrigger>
  <TooltipContent>Pin to sidebar</TooltipContent>
</Tooltip>

Composition

TooltipProvider           once, at the app root
└── Tooltip
    ├── TooltipTrigger
    └── TooltipContent    portal + positioner + popup + arrow

TooltipTrigger renders a <button>. Pass render to use a different element as the trigger, such as a Button variant.

Every tooltip inside the provider shares its delay. While one is open, moving to a neighbour opens the next one with no delay and no transition.

A tooltip opens on hover and on keyboard focus, never on press. A touch screen has no hover, so the tooltip never opens there. Put nothing in it that a reader cannot also reach another way, and give an icon-only trigger an aria-label of its own rather than relying on the tooltip's text.

Side

Use side on TooltipContent to pick the edge it opens from. Base UI flips the side when there is no room, and the arrow follows.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { HStack } from "@/components/ui/stack"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

const styles = stylex.create({
  trigger: { textTransform: "capitalize" },
})

const sides = ["left", "top", "bottom", "right"] as const

export default function TooltipSides() {
  return (
    <HStack gap={2} wrap="wrap">
      {sides.map((side) => (
        <Tooltip key={side}>
          <TooltipTrigger render={<Button variant="outline" xstyle={styles.trigger} />}>
            {side}
          </TooltipTrigger>
          <TooltipContent side={side}>Pin to sidebar</TooltipContent>
        </Tooltip>
      ))}
    </HStack>
  )
}

Disabled button

A disabled button fires no pointer events, so wrap it in a <span> and make the span the trigger.

import * as stylex from "@stylexjs/stylex"
import { Button } from "@/components/ui/button"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

const styles = stylex.create({
  wrapper: { display: "inline-block", width: "fit-content" },
})

export default function TooltipDisabled() {
  return (
    <Tooltip>
      <TooltipTrigger render={<span {...stylex.props(styles.wrapper)} />}>
        <Button variant="outline" disabled>
          Disabled
        </Button>
      </TooltipTrigger>
      <TooltipContent>Ask a workspace admin to turn this on</TooltipContent>
    </Tooltip>
  )
}

Keyboard shortcut

Put a Kbd in the content to show the shortcut beside the label.

import { Button } from "@/components/ui/button"
import { Kbd, KbdGroup } from "@/components/ui/kbd"
import { HStack } from "@/components/ui/stack"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

export default function TooltipKbd() {
  return (
    <Tooltip>
      <TooltipTrigger render={<Button variant="outline" />}>Save</TooltipTrigger>
      <TooltipContent>
        <HStack gap={2} align="center">
          Save changes
          <KbdGroup>
            <Kbd>⌘</Kbd>
            <Kbd>S</Kbd>
          </KbdGroup>
        </HStack>
      </TooltipContent>
    </Tooltip>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Every part wraps the Base UI Tooltip part of the same name and accepts its props. See the Base UI reference for the full list. TooltipContent also takes xstyle and className, and style for real inline CSS, merged over whatever its Base UI state resolves to.

TooltipProvider

PropTypeDefault
delaynumber0
closeDelaynumber—
timeoutnumber400

timeout is how long after one tooltip closes the next one still opens instantly.

Tooltip

PropTypeDefault
openboolean—
defaultOpenbooleanfalse
onOpenChange(open: boolean, details) => void—
disabledbooleanfalse
disableHoverablePopupbooleanfalse
trackCursorAxis"none" | "x" | "y" | "both""none"
handleTooltipHandle—

TooltipTrigger

PropTypeDefault
delaynumber600
closeDelaynumber0
closeOnClickbooleantrue
disabledbooleanfalse
payloadPayload—

A delay on the trigger is only read when the provider sets none.

TooltipContent

PropTypeDefault
side"top" | "bottom" | "left" | "right""top"
sideOffsetnumber4
align"start" | "center" | "end""center"
alignOffsetnumber0
styleCSSProperties—

The popup is as wide as its text and wraps past 20rem. Change the width through xstyle.

Data attributes

AttributeOnEffect
data-slot="tooltip-content"the popupPopup surface
data-slot="tooltip-arrow"the arrowPositioned by Base UI on the cross axis, by the side on ours
data-side, data-alignbothWhich way the popup slides in from, and where the arrow sits
data-instantthe popupBase UI writes it when the transition is skipped
data-starting-style, data-ending-stylethe popupBase UI writes them while the popup animates
data-popup-openthe triggerBase UI writes it while this trigger's tooltip is open