Tooltip

Explain a control with short text on hover or focus.

View component source ↗

Preview

Example

A minimal example to get started.

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/tooltip.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

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

export default function Example() {
  return (
    <TooltipProvider>
      <Tooltip>
        <TooltipTrigger render={<Button variant="outline" />}>Hover or focus me</TooltipTrigger>
        <TooltipContent>Helpful additional context</TooltipContent>
      </Tooltip>
    </TooltipProvider>
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

Tooltip

Tooltip properties
Prop	Type	Default	Description
`defaultOpen`	boolean \| undefined boolean \| undefined	`false`	Whether the tooltip is initially open. To render a controlled tooltip, use the `open` prop instead.
`open`	boolean \| undefined boolean \| undefined	`—`	Whether the tooltip is currently open.
`onOpenChange`	((open: boolean, eventDetails: TooltipPrimitive.Root.ChangeEventDetails) => void) \| undefi… ((open: boolean, eventDetails: TooltipPrimitive.Root.ChangeEventDetails) => void) \| undefined	`—`	Event handler called when the tooltip is opened or closed.
`onOpenChangeComplete`	((open: boolean) => void) \| undefined ((open: boolean) => void) \| undefined	`—`	Event handler called after any animations complete when the tooltip is opened or closed.
`disableHoverablePopup`	boolean \| undefined boolean \| undefined	`false`	Whether the tooltip contents can be hovered without closing the tooltip.
`trackCursorAxis`	"none" \| "x" \| "y" \| "both" \| undefined "none" \| "x" \| "y" \| "both" \| undefined	`'none'`	Determines which axis the tooltip should track the cursor on.
`actionsRef`	React.RefObject<TooltipRootActions \| null> \| undefined React.RefObject<TooltipRootActions \| null> \| undefined	`—`	A ref to imperative actions. - `unmount`: Unmounts the tooltip popup. - `close`: Closes the tooltip imperatively when called.
`disabled`	boolean \| undefined boolean \| undefined	`false`	Whether the tooltip is disabled.
`handle`	TooltipPrimitive.Handle<unknown> \| undefined TooltipPrimitive.Handle<unknown> \| undefined	`—`	A handle to associate the tooltip with a trigger. If specified, allows external triggers to control the tooltip's open state. Can be created with the Tooltip.createHandle() method.
`children`	React.ReactNode \| PayloadChildRenderFunction<unknown> React.ReactNode \| PayloadChildRenderFunction<unknown>	`—`	The content of the tooltip. This can be a regular React node or a render function that receives the `payload` of the active trigger.
`triggerId`	string \| null \| undefined string \| null \| undefined	`—`	ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `open` prop to create a controlled tooltip. There's no need to specify this prop when the tooltip is uncontrolled (that is, when the `open` prop is not set).
`defaultTriggerId`	string \| null \| undefined string \| null \| undefined	`—`	ID of the trigger that the tooltip is associated with. This is useful in conjunction with the `defaultOpen` prop to create an initially open tooltip.

TooltipTrigger

TooltipTrigger properties
Prop	Type	Default	Description
`handle`	TooltipPrimitive.Handle<unknown> \| undefined TooltipPrimitive.Handle<unknown> \| undefined	`—`	A handle to associate the trigger with a tooltip.
`payload`	unknown unknown	`—`	A payload to pass to the tooltip when it is opened.
`delay`	number \| undefined number \| undefined	`600`	How long to wait before opening the tooltip. Specified in milliseconds.
`closeOnClick`	boolean \| undefined boolean \| undefined	`true`	Whether the tooltip should close when this trigger is clicked.
`closeDelay`	number \| undefined number \| undefined	`0`	How long to wait before closing the tooltip. Specified in milliseconds.
`disabled`	boolean \| undefined boolean \| undefined	`false`	If `true`, the tooltip will not open when interacting with this trigger. Note that this doesn't apply the `disabled` attribute to the trigger element. If you want to disable the trigger element itself, you can pass the `disabled` prop to the trigger element via the `render` prop.
`ref`	React.Ref<HTMLButtonElement> \| undefined React.Ref<HTMLButtonElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLButtonElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLButtonElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLButtonElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLButtonElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLButtonElement, MouseEvent>>) => void) \| undefine… ((event: BaseUIEvent<React.MouseEvent<HTMLButtonElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`name`	string \| undefined string \| undefined	`—`	Field name used in form data.
`type`	"button" \| "submit" \| "reset" \| undefined "button" \| "submit" \| "reset" \| undefined	`—`	The native input or button behavior.
`value`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	The current value when controlled by the application.
`className`	string \| ((state: TooltipTriggerState) => string \| undefined) \| undefined string \| ((state: TooltipTriggerState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, TooltipTriggerState> \| undefined	`—`	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	React.CSSProperties \| ((state: TooltipTriggerState) => React.CSSProperties \| undefined) \| … React.CSSProperties \| ((state: TooltipTriggerState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.

TooltipContent

TooltipContent properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLDivElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLDivElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void) \| undefined ((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`className`	string \| ((state: TooltipPopupState) => string \| undefined) \| undefined string \| ((state: TooltipPopupState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, TooltipPopupState> \| undefined	`—`	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	React.CSSProperties \| ((state: TooltipPopupState) => React.CSSProperties \| undefined) \| un… React.CSSProperties \| ((state: TooltipPopupState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.
`align`	Align \| undefined Align \| undefined	`"center"`	How to align the popup relative to the specified side.
`side`	Side \| undefined Side \| undefined	`"top"`	Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
`sideOffset`	number \| OffsetFunction \| undefined number \| OffsetFunction \| undefined	`4`	Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.
`alignOffset`	number \| OffsetFunction \| undefined number \| OffsetFunction \| undefined	`0`	Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.

TooltipProvider

TooltipProvider properties
Prop	Type	Default	Description
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`delay`	number \| undefined number \| undefined	`0`	How long to wait before opening a tooltip. Specified in milliseconds.
`closeDelay`	number \| undefined number \| undefined	`—`	How long to wait before closing a tooltip. Specified in milliseconds.
`timeout`	number \| undefined number \| undefined	`400`	Another tooltip will open instantly if the previous tooltip is closed within this timeout. Specified in milliseconds.

Usage notes

Wrap tooltip content in TooltipProvider. Use tooltips for supplementary information rather than the only label of a control.