Build faster with Premium Chakra UI Components 💎

Learn more
Skip to Content
DocsShowcaseBlogGuides
Sponsor

Tooltip

Used to display additional information when a user hovers over an element.

SourceStorybookRecipeArk
AI TipWant to skip the docs? Use the MCP Server

Setup

For ease of use, create a closed component composition for the Tooltip component.

import { Tooltip as ChakraTooltip, Portal } from "@chakra-ui/react"
import * as React from "react"

export interface TooltipProps extends ChakraTooltip.RootProps {
  showArrow?: boolean
  portalled?: boolean
  portalRef?: React.RefObject<HTMLElement | null>
  content: React.ReactNode
  contentProps?: ChakraTooltip.ContentProps
  disabled?: boolean
}

export const Tooltip = React.forwardRef<HTMLDivElement, TooltipProps>(
  function Tooltip(props, ref) {
    const {
      showArrow,
      children,
      disabled,
      portalled = true,
      content,
      contentProps,
      portalRef,
      ...rest
    } = props

    if (disabled) return children

    return (
      <ChakraTooltip.Root {...rest}>
        <ChakraTooltip.Trigger asChild>{children}</ChakraTooltip.Trigger>
        <Portal disabled={!portalled} container={portalRef}>
          <ChakraTooltip.Positioner>
            <ChakraTooltip.Content ref={ref} {...contentProps}>
              {showArrow && (
                <ChakraTooltip.Arrow>
                  <ChakraTooltip.ArrowTip />
                </ChakraTooltip.Arrow>
              )}
              {content}
            </ChakraTooltip.Content>
          </ChakraTooltip.Positioner>
        </Portal>
      </ChakraTooltip.Root>
    )
  },
)

Alternatively, you can add it to your project using the following command.

npx @chakra-ui/cli snippet add tooltip

Usage

import { Tooltip } from "@/components/ui/tooltip"
<Tooltip content="...">
  <button />
</Tooltip>

Examples

Arrow

Use the showArrow prop to show an arrow on the tooltip.

Placement

Use the positioning.placement prop to change the position of the tooltip.

Offset

Use the positioning.offset prop to change the offset of the tooltip.

Delay

Use the openDelay and closeDelay prop to change the delay of the tooltip.

Custom Background

Use the --tooltip-bg CSS variable to change the background color of the tooltip.

Controlled

Use the open and onOpenChange prop to control the visibility of the tooltip.

Store

An alternative way to control the tooltip is to use the RootProvider component and the useTooltip store hook.

This way you can access the tooltip state and methods from outside the tooltip.

Interactive

Use the interactive prop to keep the tooltip open when interacting with its content.

Disabled

Use the disabled prop to disable the tooltip. When disabled, the tooltip will not be shown.

With Avatar

Here's an example of how to use the Tooltip component with an Avatar component.

SA

With Checkbox

Here's an example of how to use the Tooltip component with a Checkbox component.

With MenuItem

Here's an example of how to use the Tooltip with a MenuItem component.

With MenuTrigger

Here's an example of how to use the Tooltip with a MenuTrigger component.

With Switch

Here's an example of how to wrap Tooltip around a Switch component.

With Tabs

Here's an example of how to wrap Tooltip around a Tabs component.

Manage your team members

Props

Root

PropDefaultType
closeDelay 500
number

The close delay of the tooltip.

closeOnClick true
boolean

Whether the tooltip should close on click

closeOnEscape true
boolean

Whether to close the tooltip when the Escape key is pressed.

closeOnPointerDown true
boolean

Whether to close the tooltip on pointerdown.

closeOnScroll true
boolean

Whether the tooltip should close on scroll

interactive false
boolean

Whether the tooltip's content is interactive. In this mode, the tooltip will remain open when user hovers over the content.

lazyMount false
boolean

Whether to enable lazy mounting

openDelay 1000
number

The open delay of the tooltip.

skipAnimationOnMount false
boolean

Whether to allow the initial presence animation.

unmountOnExit false
boolean

Whether to unmount on exit.

as
React.ElementType

The underlying element to render.

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
unstyled
boolean

Whether to remove the component's style.

aria-label
string

Custom label for the tooltip.

defaultOpen
boolean

The initial open state of the tooltip when rendered. Use when you don't need to control the open state of the tooltip.

disabled
boolean

Whether the tooltip is disabled

id
string

The unique identifier of the machine.

ids
Partial<{ trigger: string; content: string; arrow: string; positioner: string }>

The ids of the elements in the tooltip. Useful for composition.

immediate
boolean

Whether to synchronize the present change immediately or defer it to the next frame

onExitComplete
VoidFunction

Function called when the animation ends in the closed state

onOpenChange
(details: OpenChangeDetails) => void

Function called when the tooltip is opened.

open
boolean

The controlled open state of the tooltip

positioning
PositioningOptions

The user provided options used to position the popover content

present
boolean

Whether the node is present (controlled by the user)

Explorer

Explore the Tooltip component parts interactively. Click on parts in the sidebar to highlight them in the preview.

Component Anatomy

Hover to highlight, click to select parts

trigger

arrow

arrowTip

positioner

content

tooltip.recipe.ts

Previous

Toggle Tip

Next

Accordion