useTooltip · astryx-svelte

useTooltip @astryx-svelte/core v0.3.0 · Tooltip

Usage

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.

ts
 
import { Tooltip } from '@astryx-svelte/core';

Best practices

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

Parameters

Parameter	Type	Default	Description
`placement`	`'below' \| 'above' \| 'end' \| 'start'`	`'above'`	Position relative to the trigger. Logical: start/end resolve against the popover's own inherited direction (RTL mirrors in pure CSS).
`alignment`	`'end' \| 'start' \| 'center'`	`'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`	Delay before showing on hover, in milliseconds.
`hideDelay`	`number`	`0`	Delay before hiding after mouse or focus leaves, in milliseconds.
`focusTrigger`	`'auto' \| 'always' \| 'never'`	`'auto'`	When focus should open the tooltip. auto only attaches focus listeners to naturally focusable elements.
`isEnabled`	`boolean`	`true`	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`	`false`	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

Field	Type	Default	Description
`ref`	`(node: HTMLElement \| null) => void`	—	Combined ref that sets both position and interaction on the same trigger element. Svelte has no ref prop. Reach the element with an attachment through the spread props; `bind:this` on a component yields the instance rather than its element.Upstream declares `RefCallback<HTMLElement>`.
`positionRef`	`(node: HTMLElement \| null) => void`	—	Ref for the positioning anchor element. Element references are attachments here. The port returns an `Attachment<HTMLElement>` named `attach…`; spread it onto the element instead of assigning a ref.Upstream declares `RefCallback<HTMLElement>`.
`interactionRef`	`(node: HTMLElement \| null) => void`	—	Ref for the hover/focus interaction element. Element references are attachments here. The port returns an `Attachment<HTMLElement>` named `attach…`; spread it onto the element instead of assigning a ref.Upstream declares `RefCallback<HTMLElement>`.
`anchorId`	`string`	—	CSS anchor name for advanced positioning cases.
`describedBy`	`string`	—	ID to compose into aria-describedby on the trigger.
`renderTooltip`	`(children: string \| Snippet, props?: Omit<ContextRenderProps, 'positioning'>) => string \| Snippet`	—	Render function for the anchor-positioned tooltip content. The positioning opt-out is excluded: the tooltip always derives its position from placement/alignment. A Svelte hook cannot return markup. This hook returns state only; render its companion component and pass the hook’s value to it.Upstream declares `(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode`.

Examples

Common configurations, variations, and states.

Tooltip — Hook Usage

Tooltip using the useTooltip hook for programmatic control.