Ark UI Logo
[New] Marquee component
DocsShowcaseBlogPlus
GitHub
Components
Tooltip

Tooltip

A label that provides information on hover or focus.

Loading...

You can explore the tooltip component in the following curated examples.

Popover with Tooltip

Render a Popover with a Tooltip that shows upon hovering over the Popover Trigger.

Slider with Tooltip

Render a Slider with a Tooltip that shows the current value of the Slider.

Tooltip with following cursor

Render a Tooltip that follows the cursor when hovering over the target element.

Dialog with Tooltip

Render a Dialog with a Tooltip that shows upon hovering over the Dialog Trigger.

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} onOpenChange={({open}) => setIsOpen(open)}>
        <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

Props

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.
CSS VariableDescription
--arrow-sizeThe size of the arrow
--arrow-size-halfHalf the size of the arrow
--arrow-backgroundUse this variable to style the arrow background
--arrow-offsetThe offset position of the arrow

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.
CSS VariableDescription
--reference-widthThe width of the reference element
--reference-heightThe height of the root
--available-widthThe available width in viewport
--available-heightThe available height in viewport
--xThe x position for transform
--yThe y position for transform
--z-indexThe z-index value
--transform-originThe transform origin for animations

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"

Context

These are the properties available when using Tooltip.Context, useTooltipContext hook or useTooltip hook.

API

PropertyType
open
boolean

Whether the tooltip is open.

setOpen
(open: boolean) => void

Function to open the tooltip.

reposition
(options?: Partial<PositioningOptions>) => void

Function to reposition the popover

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