Skip to main content

​
Overview

A tooltip provides contextual information or labels for UI elements on hover or focus.

​
Features

  • Provider to control display delay globally
  • Opens when the trigger is focused or hovered
  • Closes when the trigger is activated or when pressing Esc
  • Supports custom timings
  • Ignores hovering on touch devices

​
Installation

npm install @radix-ui/react-tooltip

​
Anatomy

Import all parts and piece them together. 
import * as Tooltip from '@radix-ui/react-tooltip';

export default () => (
  <Tooltip.Provider>
    <Tooltip.Root>
      <Tooltip.Trigger />
      <Tooltip.Portal>
        <Tooltip.Content>
          <Tooltip.Arrow />
        </Tooltip.Content>
      </Tooltip.Portal>
    </Tooltip.Root>
  </Tooltip.Provider>
);

​
API Reference

​
Provider

Wraps your app to provide global settings for tooltips.
​
delayDuration
number
default:"700"
The duration from when the mouse enters a tooltip trigger until the tooltip opens.
​
skipDelayDuration
number
default:"300"
How much time a user has to enter another trigger without incurring a delay again.
​
disableHoverableContent
boolean
default:"false"
When true, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger.

​
Root

Contains all the parts of a tooltip.
​
open
boolean
The controlled open state of the tooltip. Must be used in conjunction with onOpenChange.
​
defaultOpen
boolean
The open state of the tooltip when it is initially rendered. Use when you do not need to control its open state.
​
onOpenChange
(open: boolean) => void
Event handler called when the open state of the tooltip changes.
​
delayDuration
number
default:"700"
Override the duration given to the Provider to customize the open delay for a specific tooltip.
​
disableHoverableContent
boolean
default:"false"
When true, trying to hover the content will result in the tooltip closing as the pointer leaves the trigger.

​
Trigger

The button that toggles the tooltip.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.

​
Portal

When used, portals the content part into the body.
​
container
HTMLElement
default:"document.body"
Specify a container element to portal the content into.
​
forceMount
boolean
Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.

​
Content

The component that pops out when the tooltip is open.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.
​
aria-label
string
By default, screen readers will announce the content inside the tooltip. Use this when you want to announce something different.
​
side
'top' | 'right' | 'bottom' | 'left'
default:"'top'"
The preferred side of the trigger to render against when open.
​
sideOffset
number
default:"0"
The distance in pixels from the trigger.
​
align
'start' | 'center' | 'end'
default:"'center'"
The preferred alignment against the trigger. May change when collisions occur.
​
alignOffset
number
default:"0"
An offset in pixels from the “start” or “end” alignment options.
​
avoidCollisions
boolean
default:"true"
When true, overrides the side and align preferences to prevent collisions with boundary edges.
​
collisionBoundary
Element | Element[]
default:"[]"
The element used as the collision boundary. By default this is the viewport.
​
collisionPadding
number | Padding
default:"0"
The distance in pixels from the boundary edges where collision detection should occur.
​
sticky
'partial' | 'always'
default:"'partial'"
The sticky behavior on the align axis. partial will keep the content in the boundary as long as the trigger is at least partially in the boundary whilst always will keep the content in the boundary regardless.
​
hideWhenDetached
boolean
default:"false"
Whether to hide the content when the trigger becomes fully occluded.
​
onEscapeKeyDown
(event: KeyboardEvent) => void
Event handler called when the escape key is down. It can be prevented by calling event.preventDefault.
​
onPointerDownOutside
(event: PointerDownOutsideEvent) => void
Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling event.preventDefault.

​
Arrow

An optional arrow element to render alongside the tooltip.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child, merging their props and behavior.
​
width
number
default:"10"
The width of the arrow in pixels.
​
height
number
default:"5"
The height of the arrow in pixels.

​
Example

import * as Tooltip from '@radix-ui/react-tooltip';

function TooltipDemo() {
  return (
    <Tooltip.Provider>
      <Tooltip.Root>
        <Tooltip.Trigger>Hover me</Tooltip.Trigger>
        <Tooltip.Portal>
          <Tooltip.Content className="tooltip-content">
            Add to library
            <Tooltip.Arrow className="tooltip-arrow" />
          </Tooltip.Content>
        </Tooltip.Portal>
      </Tooltip.Root>
    </Tooltip.Provider>
  );
}

​
Accessibility

Adheres to the Tooltip WAI-ARIA design pattern.

​
Keyboard Interactions

  • Tab - Opens the tooltip when the trigger receives keyboard focus
  • Space - Opens the tooltip without closing when keyboard users activate the trigger
  • Enter - Opens the tooltip without closing when keyboard users activate the trigger
  • Esc - Closes the tooltip
Tooltips are automatically dismissed when the user activates the trigger, unless using keyboard navigation.

Build docs developers (and LLMs) love

Get started for freeTalk to us