Tooltip

Tooltip component that displays contextual information on hover. Built on @base-ui/react for robust accessibility and positioning. Provides an intuitive placement API with collision handling and animation support.

Live Preview

Import

import { Tooltip } from 'entangle-ui';

Usage

<Tooltip title="Save your work">
  <Button>Save</Button>
</Tooltip>

Placement

The placement prop controls where the tooltip appears relative to the trigger. Supports 12 positions.

<Tooltip placement="top" title="Top">
  <Button>Top</Button>
</Tooltip>

<Tooltip placement="bottom-start" title="Bottom start">
  <Button>Bottom Start</Button>
</Tooltip>

<Tooltip placement="right" title="Right">
  <Button>Right</Button>
</Tooltip>

| Placement | Description | | -------------------------------------- | -------------------- | | top, top-start, top-end | Above the trigger | | bottom, bottom-start, bottom-end | Below the trigger | | left, left-start, left-end | Left of the trigger | | right, right-start, right-end | Right of the trigger |

Collision Handling

The collision prop controls how the tooltip reacts when it would overflow the viewport.

<Tooltip collision="smart" title="Intelligent positioning">
  <Button>Smart (default)</Button>
</Tooltip>

<Tooltip collision="flip" title="Flips to opposite side">
  <Button>Flip</Button>
</Tooltip>

<Tooltip collision="shift" title="Shifts within bounds">
  <Button>Shift</Button>
</Tooltip>

| Strategy | Behavior | | ------------ | ---------------------------------------- | | smart | Intelligent fallback with axis switching | | flip | Flip to the opposite side | | shift | Shift within viewport bounds | | flip-shift | Flip first, then shift | | hide | Hide when no space available | | none | No collision handling |

For advanced control, use collisionConfig to configure side and alignment collision behavior independently.

<Tooltip
  collisionConfig={{
    side: 'flip',
    align: 'shift',
    fallbackAxisSide: 'start',
  }}
  title="Advanced collision"
>
  <Button>Advanced</Button>
</Tooltip>

Delay

Control the show and hide delays in milliseconds.

<Tooltip delay={300} title="Shows faster">
  <Button>Fast delay</Button>
</Tooltip>

<Tooltip delay={1000} closeDelay={200} title="Slow show, delayed hide">
  <Button>Custom delay</Button>
</Tooltip>

Arrow

The arrow pointing to the trigger is shown by default. Set arrow={false} to hide it.

<Tooltip arrow={false} title="No arrow">
  <Button>No arrow</Button>
</Tooltip>

Rich Content

The title prop accepts React nodes for complex tooltip content.

<Tooltip
  title={
    <div>
      <strong>Save</strong>
      <br />
      Ctrl+S
    </div>
  }
>
  <Button>Save</Button>
</Tooltip>

Disabled

When disabled is true, the tooltip does not render. The trigger element is returned as-is.

<Tooltip disabled title="This tooltip is disabled">
  <Button>No tooltip</Button>
</Tooltip>

Custom Animation

Configure tooltip animation with the animation prop.

<Tooltip
  animation={{
    animated: true,
    duration: 300,
    easing: 'ease-in-out',
  }}
  title="Custom animation"
>
  <Button>Animated</Button>
</Tooltip>

<Tooltip animation={{ animated: false }} title="No animation">
  <Button>Instant</Button>
</Tooltip>

Advanced Positioning

Use the positioner prop for fine-grained positioning control.

<Tooltip
  positioner={{
    offset: 12,
    padding: 10,
    sticky: true,
  }}
  title="Advanced positioning"
>
  <Button>Custom offset</Button>
</Tooltip>

Raw Props Pass-Through

For power users, rootProps and positionerProps provide direct access to the underlying Base UI components.

<Tooltip
  rootProps={{ trackCursorAxis: 'x' }}
  positionerProps={{ arrowPadding: 20 }}
  title="Cursor tracking"
>
  <Button>Track cursor</Button>
</Tooltip>

Props

Prop	Type	Default	Description
children	ReactElement	—	The trigger element that shows the tooltip on hover.
title	ReactNode	—	Content displayed in the tooltip. Text or React elements.
placement	'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'	'top'	Tooltip placement relative to the trigger.
collision	'flip' | 'shift' | 'hide' | 'flip-shift' | 'smart' | 'none'	'smart'	Collision handling strategy when tooltip overflows viewport.
collisionConfig	{ side?: string; align?: string; fallbackAxisSide?: string }	—	Advanced collision configuration. Overrides the collision strategy.
positioner	{ offset?: number; padding?: number; sticky?: boolean; boundary?: string | HTMLElement; trackCursor?: string }	—	Advanced positioning configuration.
animation	{ animated?: boolean; duration?: number; easing?: string }	—	Animation configuration for show/hide transitions.
delay	number	600	Delay in milliseconds before showing the tooltip.
closeDelay	number	0	Delay in milliseconds before hiding the tooltip.
arrow	boolean	true	Whether to show the arrow pointing to the trigger.
disabled	boolean	false	Whether the tooltip is disabled.
rootProps	Partial<BaseTooltipRootProps>	—	Direct props for the Base UI Root component.
positionerProps	Partial<BaseTooltipPositionerProps>	—	Direct props for the Base UI Positioner component.
className	string	—	Additional CSS class names for the tooltip popup.
style	CSSProperties	—	Inline styles for the tooltip popup.
testId	string	—	Test identifier for automated testing.
ref	Ref<HTMLDivElement>	—	Ref to the tooltip popup element.

Accessibility

• Built on @base-ui/react which implements WAI-ARIA tooltip patterns
• Tooltip content is associated with the trigger via aria-describedby
• Tooltip appears on hover and focus, and dismisses on Escape
• The trigger is wrapped in a focusable container for keyboard access
• Use meaningful text in title for screen reader users