Tooltip

Tooltips display a brief, informative message that appears when a user interacts with an element.

Storybook @nextui-org/tooltip React Aria Source Styles source

Installation

npx nextui-cli@latest add tooltip

The above command is for individual installation only. You may skip this step if @nextui-org/react is already installed globally.

Import

For individual installation, please note that you should add ./node_modules/@nextui-org/theme/dist/components/popover.js to your tailwind.config.js file instead since tooltip reuses popover styles.

Usage

With Arrow

Colors

Placements

Offset

Controlled

With Delay

You can control the open and close delay of the tooltip with delay and closeDelay props.

Hovering over the second button shows the tooltip immediately. If you wait for a delay before hovering another element, the delay restarts.

Custom Content

Custom Motion

Tooltip offers a motionProps property to customize the enter / exit animation.

Learn more about Framer motion variants here.

Slots

base: The main tooltip slot, it wraps the tooltip content.
arrow: The arrow slot, it wraps the tooltip arrow, the placement of the arrow is based on the tooltip placement, e.g. data-[placement=top]:....

Custom Styles

You can customize the Tooltip component by passing custom Tailwind CSS classes to the component slots.

Data Attributes

Tooltip has the following attributes on the base element:

data-open: When the tooltip is open. Based on tooltip state.
data-placement: The placement of the tooltip. Based on placement prop. The arrow element is positioned based on this attribute.
data-disabled: When the tooltip is disabled. Based on isDisabled prop.

Accessibility

Keyboard focus management and cross browser normalization.
Hover management and cross browser normalization.
Labeling support for screen readers (aria-describedby).
Exposed as a tooltip to assistive technology via ARIA.
Matches native tooltip behavior with delay on hover of first tooltip and no delay on subsequent tooltips.

API

Attribute	Type	Description	Default
children*	`ReactNode[]`	The children to render. Usually a trigger element.	-
content	`ReactNode`	The content to render inside the tooltip.	-
size	`sm` \| `md` \| `lg`	The tooltip size. This change the `content` font size.	`md`
color	`default` \| `primary` \| `secondary` \| `success` \| `warning` \| `danger`	The tooltip color theme.	`default`
radius	`none` \| `sm` \| `md` \| `lg` \| `full`	The tooltip border radius.	`md`
shadow	`none` \| `sm` \| `md` \| `lg`	The tooltip shadow.	`sm`
placement	TooltipPlacement	The placement of the tooltip relative to its trigger reference.	`top`
delay	`number`	The delay in milliseconds before the tooltip opens.	`0`
closeDelay	`number`	The delay in milliseconds before the tooltip closes.	`500`
isOpen	`boolean`	Whether the tooltip is open by default (controlled).	-
defaultOpen	`boolean`	Whether the tooltip is open by default (uncontrolled).	-
offset(px)	`number`	The distance or margin between the reference and popper. It is used internally to create an offset modifier.	`7`
containerPadding(px)	`number`	The placement padding that should be applied between the element and its surrounding container.	`12`
crossOffset(px)	`number`	The additional offset applied along the cross axis between the element and its anchor element.	`0`
showArrow	`boolean`	Whether the tooltip should have an arrow.	`false`
shouldFlip	`boolean`	Whether the tooltip should change its placement and flip when it's about to overflow its boundary area.	`true`
triggerScaleOnOpen	`boolean`	Whether the trigger should scale down when the tooltip is open.	`true`
shouldBlockScroll	`boolean`	Whether to block scrolling outside the tooltip.	`true`
isKeyboardDismissDisabled	`boolean`	Whether pressing the escape key to close the tooltip should be disabled.	`false`
isDismissable	`boolean`	Whether to close the overlay when the user interacts outside it.	`false`
shouldCloseOnBlur	`boolean`	Whether the tooltip should close when focus is lost or moves outside it.	`true`
motionProps	MotionProps	The props to modify the framer motion animation. Use the `variants` API to create your own animation.	-
portalContainer	`HTMLElement`	The container element in which the overlay portal will be placed.	`document.body`
updatePositionDeps	`any[]`	The dependencies to force the tooltip position update.	`[]`
isDisabled	`boolean`	Whether the tooltip is disabled.	`false`
disableAnimation	`boolean`	Whether the tooltip is animated.	`false`
classNames	`Record<"base"｜"content", string>`	Allows to set custom class names for the tooltip slots.	-

Attribute	Type	Description
onOpenChange	`(isOpen: boolean) => void`	Handler that is called when the tooltip's open state changes.
shouldCloseOnInteractOutside	`(e: HTMLElement) => void`	When user interacts with the argument element outside of the tooltip ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the tooltip. By default, onClose will always be called on interaction outside the overlay ref.
onClose	`() => void`	Handler that is called when the tooltip should close.

type TooltipPlacement =
  | "top"
  | "bottom"
  | "right"
  | "left"
  | "top-start"
  | "top-end"
  | "bottom-start"
  | "bottom-end"
  | "left-start"
  | "left-end"
  | "right-start"
  | "right-end";

Motion Props

export type MotionProps = HTMLMotionProps<"div">; // @see https://www.framer.com/motion/