Tooltip — Astryx v0.7.1 docs

A short text hint that appears on hover or focus, anchored to a trigger element. Use it to describe icon-only buttons, show the full text of truncated labels, or provide supplementary context without cluttering the UI.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Usage guidance

Keep tooltip content concise: aim for under 140 characters of plain text.
Add a tooltip to icon-only buttons and controls that lack a visible label.
Set touchTrigger to tap when the trigger is a button whose only job is revealing the tooltip, such as an info icon: touch has no hover, and auto keeps the tap for triggers that perform an action.
Avoid: Place interactive elements like links or buttons inside a tooltip; use HoverCard or Popover instead.
Avoid: Use tooltips for essential information that users must see to complete a task.

Theming API

{
  "targets": [
    {
      "className": "astryx-tooltip"
    }
  ]
}

Component wrapper for tooltip display triggered on hover or focus.

Prop	Type	Default	Description
children	ReactNode		Trigger element(s) that activate the tooltip.
anchorRef	RefObject<HTMLElement>		External anchor ref for sibling mode.
content	ReactNode		Tooltip content, typically short text.
placement	'above' \| 'below' \| 'start' \| 'end'	'above'	Position relative to the anchor element. Logical: start/end resolve against the popover's own inherited direction (RTL mirrors in pure CSS).
alignment	'start' \| 'center' \| 'end'	'center'	Alignment along the placement axis. Logical: start/end resolve against the popover's own inherited direction (RTL mirrors in pure CSS).
delay	number	200	Show delay in milliseconds.
hideDelay	number	0	Hide delay in milliseconds.
focusTrigger	'auto' \| 'always' \| 'never'	'auto'	Controls when focus events trigger the tooltip.
touchTrigger	'auto' \| 'tap' \| 'none'	'auto'	What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control. tap always opens; use it for an info icon rendered as a button, whose only job is to reveal the tooltip. none never opens on touch.
isEnabled	boolean	true	Enables or disables the tooltip triggers.
onOpenChange	(isOpen: boolean) => void		Callback fired when tooltip visibility changes. Called with true when shown and false when hidden.
hasHoverIndication	'auto' \| boolean	'auto'	Shows a dashed underline on the trigger element.
isDefaultOpen	boolean		Whether the tooltip should be shown on mount. Still dismissible.
isOpen	boolean		Controlled open state for the tooltip.

Anatomy

Tooltip surface: Painted overlay surface that presents the tooltip.
Tooltip text: Tooltip content rendered within the surface.

useTooltip

Headless hook for hover/focus-triggered tooltips. Builds on useLayer with hover intent, keyboard focus handling, and accessible aria-describedby linking. Use for custom trigger elements that need tooltip behavior without the wrapper component.

Parameters

Parameter	Type	Description
placement	'above' \| 'below' \| 'start' \| 'end'	Position relative to the trigger. Logical: start/end resolve against the popover's own inherited direction (RTL mirrors in pure CSS).
alignment	'start' \| 'center' \| 'end'	Alignment along the placement axis. Logical: start/end resolve against the popover's own inherited direction (RTL mirrors in pure CSS).
delay	number	Delay before showing on hover, in milliseconds.
hideDelay	number	Delay before hiding after mouse or focus leaves, in milliseconds.
focusTrigger	'auto' \| 'always' \| 'never'	When focus should open the tooltip. auto only attaches focus listeners to naturally focusable elements.
touchTrigger	'auto' \| 'tap' \| 'none'	What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own; tap always opens (an info icon rendered as a button); none never opens on touch.
isEnabled	boolean	Whether hover and focus triggers are enabled.
isOpen	boolean	Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.
isDefaultOpen	boolean	Whether the tooltip should be shown on mount.
onShow	() => void	Callback fired when the tooltip becomes visible.
onHide	() => void	Callback fired when the tooltip is hidden.

Returns

[
  {
    "name": "ref",
    "type": "RefCallback<HTMLElement>",
    "description": "Combined ref that sets both position and interaction on the same trigger element."
  },
  {
    "name": "positionRef",
    "type": "RefCallback<HTMLElement>",
    "description": "Ref for the positioning anchor element."
  },
  {
    "name": "interactionRef",
    "type": "RefCallback<HTMLElement>",
    "description": "Ref for the hover/focus interaction element."
  },
  {
    "name": "anchorId",
    "type": "string",
    "description": "CSS anchor name for advanced positioning cases."
  },
  {
    "name": "describedBy",
    "type": "string",
    "description": "ID to compose into aria-describedby on the trigger."
  },
  {
    "name": "renderTooltip",
    "type": "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode",
    "description": "Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment."
  }
]

Usage guidance

Use for brief text labels that describe icon buttons, truncated text, abbreviations, or compact controls.
Prefer the Tooltip component for standard wrapping; use the hook when the trigger is not a simple child.
Avoid: Put interactive content inside tooltips: use Popover or HoverCard instead.

Examples

Tooltip:
Tooltip — Action Bar: Tooltips on an action button bar with contextual descriptions.
Tooltip — Hook Usage: Tooltip using the useTooltip hook for programmatic control.
Tooltip — Inline Text: Tooltips on inline text terms for definitions.