Cursor Tooltip

ProNew

A tooltip that follows the pointer across a large target such as a chart bar or map region, flips at the viewport edge and appears beside the element on keyboard focus.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

When to use it

Use it when one element is big and the detail depends on where the pointer is: a chart, a heat-map, a floor plan. A fixed tooltip would cover what the person is trying to read.

Do not use it for small buttons or icons; use tooltip-group there. Do not rely on it alone for data that touch or keyboard users need.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/cursor-tooltip

Usage

API

CursorTooltip

Prop	Type	Default	Description
`content`	`ReactNode`	-	The tip text.
`children`	`ReactElement`	-	The target. It receives the pointer and focus handlers.
`offset`	`number`	`14`	Distance from the pointer in px.
`disabled`	`boolean`	`false`	Never show the tip.
`className`	`string`	-	Classes for the tip.

Accessibility

The tip has role="tooltip" and the target gets aria-describedby while it is visible.
Touch pointers do not show it; give the target its own accessible name, since the tip only adds detail.
No animation runs, so there is nothing to reduce. The tip never takes pointer events.

Keyboard

Key	Action
Tab	shows the tip beside the focused target
Escape	hides the tip

Testing

The component ships a Testing Library test (cursor-tooltip.test.tsx) that covers following the pointer, leaving, touch pointers, Escape and the disabled state.

Guide and examples

When to use it

Use it when one element is big and the detail depends on where the pointer is: a chart, a heat-map, a floor plan. A fixed tooltip would cover what the person is trying to read.

Do not use it for small buttons or icons; use tooltip-group there. Do not rely on it alone for data that touch or keyboard users need.

Installation


pnpm dlx shadcn@latest add @tealmac-pro/cursor-tooltip

Usage

API

CursorTooltip

Prop	Type	Default	Description
`content`	`ReactNode`	-	The tip text.
`children`	`ReactElement`	-	The target. It receives the pointer and focus handlers.
`offset`	`number`	`14`	Distance from the pointer in px.
`disabled`	`boolean`	`false`	Never show the tip.
`className`	`string`	-	Classes for the tip.

Accessibility

The tip has role="tooltip" and the target gets aria-describedby while it is visible.
Touch pointers do not show it; give the target its own accessible name, since the tip only adds detail.
No animation runs, so there is nothing to reduce. The tip never takes pointer events.

Keyboard

Key	Action
Tab	shows the tip beside the focused target
Escape	hides the tip

Testing

The component ships a Testing Library test (cursor-tooltip.test.tsx) that covers following the pointer, leaving, touch pointers, Escape and the disabled state.