Ark UI Logo
DocsExamplesBlogPlus
GitHub
Components
Tooltip

Tooltip

A label that provides information on hover or focus.

Anatomy

To set up the tooltip correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the Tooltip component in your project. Let's take a look at the most basic example:

import { Tooltip } from '@ark-ui/react/tooltip'

export const Basic = () => (
  <Tooltip.Root>
    <Tooltip.Trigger>Hover Me</Tooltip.Trigger>
    <Tooltip.Positioner>
      <Tooltip.Content>I am a tooltip!</Tooltip.Content>
    </Tooltip.Positioner>
  </Tooltip.Root>
)

Controlled Tooltip

To create a controlled Tooltip component, manage the state of whether the tooltip is open using the open prop:

import { Tooltip } from '@ark-ui/react/tooltip'
import { useState } from 'react'

export const Controlled = () => {
  const [isOpen, setIsOpen] = useState(false)
  return (
    <>
      <button type="button" onClick={() => setIsOpen(!isOpen)}>
        Toggle
      </button>
      <Tooltip.Root open={isOpen}>
        <Tooltip.Trigger>Hover Me</Tooltip.Trigger>
        <Tooltip.Positioner>
          <Tooltip.Content>I am a tooltip!</Tooltip.Content>
        </Tooltip.Positioner>
      </Tooltip.Root>
    </>
  )
}

Using a Render Function

For more control over the Tooltip's functionality, you can use a function as a child, which provides access to the Tooltip API:

import { Tooltip } from '@ark-ui/react/tooltip'

export const RenderFn = () => (
  <Tooltip.Root>
    <Tooltip.Trigger>Hover Me</Tooltip.Trigger>
    <Tooltip.Positioner>
      <Tooltip.Context>
        {(tooltip) => <Tooltip.Content>This tooltip is open: {tooltip.open.toString()}</Tooltip.Content>}
      </Tooltip.Context>
    </Tooltip.Positioner>
  </Tooltip.Root>
)

Adding an Arrow

To display an arrow pointing to the trigger from the tooltip, use the Tooltip.Arrow and Tooltip.ArrowTip components:

import { Tooltip } from '@ark-ui/react/tooltip'

export const Arrow = () => (
  <Tooltip.Root>
    <Tooltip.Trigger>Hover Me</Tooltip.Trigger>
    <Tooltip.Positioner>
      <Tooltip.Content>
        <Tooltip.Arrow>
          <Tooltip.ArrowTip />
        </Tooltip.Arrow>
        I am a tooltip!
      </Tooltip.Content>
    </Tooltip.Positioner>
  </Tooltip.Root>
)

Configuring Delay Timings

To configure the delay timings for the Tooltip, use the closeDelay and openDelay props:

import { Tooltip } from '@ark-ui/react/tooltip'

export const Timings = () => (
  <Tooltip.Root closeDelay={0} openDelay={0}>
    <Tooltip.Trigger>Hover Me</Tooltip.Trigger>
    <Tooltip.Positioner>
      <Tooltip.Content>I am a tooltip!</Tooltip.Content>
    </Tooltip.Positioner>
  </Tooltip.Root>
)

Custom Positioning

To customize the position of the Tooltip relative to the trigger, use the positioning prop:

import { Tooltip } from '@ark-ui/react/tooltip'

export const Positioning = () => (
  <Tooltip.Root
    positioning={{
      placement: 'left-start',
      offset: { mainAxis: 12, crossAxis: 12 },
    }}
  >
    <Tooltip.Trigger>Hover Me</Tooltip.Trigger>
    <Tooltip.Positioner>
      <Tooltip.Content>I am a tooltip!</Tooltip.Content>
    </Tooltip.Positioner>
  </Tooltip.Root>
)

Using the Root Provider

The RootProvider component provides a context for the tooltip. It accepts the value of the useTooltip hook. You can leverage it to access the component state and methods from outside the tooltip.

import { Tooltip, useTooltip } from '@ark-ui/react/tooltip'

export const RootProvider = () => {
  const tooltip = useTooltip()

  return (
    <>
      <button onClick={() => tooltip.setOpen(true)}>Open</button>

      <Tooltip.RootProvider value={tooltip}>
        <Tooltip.Trigger disabled>Hover Me</Tooltip.Trigger>
        <Tooltip.Positioner>
          <Tooltip.Content>I am a tooltip!</Tooltip.Content>
        </Tooltip.Positioner>
      </Tooltip.RootProvider>
    </>
  )
}

If you're using the RootProvider component, you don't need to use the Root component.

API Reference

Root

PropDefaultType
aria-label
string

Custom label for the tooltip.

closeDelay500
number

The close delay of the tooltip.

closeOnClicktrue
boolean

Whether the tooltip should close on click

closeOnEscapetrue
boolean

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

closeOnPointerDowntrue
boolean

Whether to close the tooltip on pointerdown.

closeOnScrolltrue
boolean

Whether the tooltip should close on scroll

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

interactivefalse
boolean

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

lazyMountfalse
boolean

Whether to enable lazy mounting

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

openDelay1000
number

The open delay 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)

skipAnimationOnMountfalse
boolean

Whether to allow the initial presence animation.

unmountOnExitfalse
boolean

Whether to unmount on exit.

Arrow

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.

ArrowTip

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.

Content

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.
Data AttributeValue
[data-scope]tooltip
[data-part]content
[data-state]"open" | "closed"
[data-placement]The placement of the content

Positioner

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.

RootProvider

PropDefaultType
value
UseTooltipReturn

immediate
boolean

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

lazyMountfalse
boolean

Whether to enable lazy mounting

onExitComplete
VoidFunction

Function called when the animation ends in the closed state

present
boolean

Whether the node is present (controlled by the user)

skipAnimationOnMountfalse
boolean

Whether to allow the initial presence animation.

unmountOnExitfalse
boolean

Whether to unmount on exit.

Trigger

PropDefaultType
asChild
boolean

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

For more details, read our Composition guide.
Data AttributeValue
[data-scope]tooltip
[data-part]trigger
[data-expanded]Present when expanded
[data-state]"open" | "closed"

Accessibility

Complies with the Tooltip WAI-ARIA design pattern.

Keyboard Support

KeyDescription
Tab
Opens/closes the tooltip without delay.
Escape
If open, closes the tooltip without delay.

Prev page

Toggle

Next page

Tour

Pro Support and Training

Supercharge your team with support from the creators of Ark UI

Get Pro Support