Tooltip

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


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

Tooltip Props

AttributeTypeDescriptionDefault
children*ReactNode[]The children to render. Usually a trigger element.-
contentReactNodeThe content to render inside the tooltip.-
sizesm | md | lgThe tooltip size. This change the content font size.md
colordefault | primary | secondary | success | warning | dangerThe tooltip color theme.default
radiusnone | sm | md | lg | fullThe tooltip border radius.md
shadownone | sm | md | lgThe tooltip shadow.sm
placementTooltipPlacementThe placement of the tooltip relative to its trigger reference.top
delaynumberThe delay in milliseconds before the tooltip opens.0
closeDelaynumberThe delay in milliseconds before the tooltip closes.500
isOpenbooleanWhether the tooltip is open by default (controlled).-
defaultOpenbooleanWhether the tooltip is open by default (uncontrolled).-
offset(px)numberThe distance or margin between the reference and popper. It is used internally to create an offset modifier.7
containerPadding(px)numberThe placement padding that should be applied between the element and its surrounding container.12
crossOffset(px)numberThe additional offset applied along the cross axis between the element and its anchor element.0
showArrowbooleanWhether the tooltip should have an arrow.false
shouldFlipbooleanWhether the tooltip should change its placement and flip when it's about to overflow its boundary area.true
triggerScaleOnOpenbooleanWhether the trigger should scale down when the tooltip is open.true
shouldBlockScrollbooleanWhether to block scrolling outside the tooltip.true
isKeyboardDismissDisabledbooleanWhether pressing the escape key to close the tooltip should be disabled.false
isDismissablebooleanWhether to close the overlay when the user interacts outside it.false
shouldCloseOnBlurbooleanWhether the tooltip should close when focus is lost or moves outside it.true
motionPropsMotionPropsThe props to modify the framer motion animation. Use the variants API to create your own animation.-
portalContainerHTMLElementThe container element in which the overlay portal will be placed.document.body
updatePositionDepsany[]The dependencies to force the tooltip position update.[]
isDisabledbooleanWhether the tooltip is disabled.false
disableAnimationbooleanWhether the tooltip is animated.false
classNamesRecord<"base"|"content", string>Allows to set custom class names for the tooltip slots.-

Tooltip Events

AttributeTypeDescription
onOpenChange(isOpen: boolean) => voidHandler that is called when the tooltip's open state changes.
shouldCloseOnInteractOutside(e: HTMLElement) => voidWhen 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() => voidHandler that is called when the tooltip should close.

Tooltip types

Tooltip Placement

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/