On this pageOverview
Tooltip
A non-interactive floating label anchored to a trigger. Tooltips appear on hover after a short delay, or immediately on keyboard focus. They hide on pointer-leave, blur, or Escape. Use tooltips for short hints about a control. Because they rely on hover and keyboard focus, donβt use them for content that must be reachable on touch; for that, or for rich or interactive content, use Popover instead.
Bind TooltipBlock in the parent. The positioning engine is shared with Popover and Menu. Pass anchor to control placement and spacing.
See it in an app
Check out how Tooltip is wired up in a real Foldkit app.
Hover or tab into the trigger to reveal the tooltip. Hover waits for showDelay (default 500ms); keyboard focus shows it immediately.
Tooltip is headless. The toView callback receives attribute bundles for the trigger and panel, and the consumer composes the markup. The panel is rendered with pointer-events: none so it never captures hover or clicks, which keeps the open/close logic tied to the trigger.
| Attribute | Condition |
|---|---|
data-open | Present on trigger and panel when the tooltip is visible. |
data-disabled | Present on the trigger when disabled. |
data-placement | Present on the panel, set to the side it currently sits on: top, right, bottom, or left. Fixed to the first resolved side when isPlacementLocked is true. |
| Key | Description |
|---|---|
Escape | Hides the tooltip while visible. It will not reopen until the user disengages by moving the pointer away or blurring the trigger. |
The panel has role="tooltip" and the trigger is linked via aria-describedby. Focus is never moved into the tooltip, so assistive technology announces the panel contents as a description of the trigger.
The tooltip describes the trigger but does not name it, so give the trigger an accessible name. For a visible label, wire a native <label for> that targets the trigger id with triggerId(id) imported from @foldkit/ui/tooltip rather than hardcoding the -trigger convention. The for association makes the trigger properly labeled: assistive technology announces it by the visible label text, and clicking the label focuses the trigger. That is why it is the recommended pattern.
Two ViewInputs fields cover the cases a <label for> does not. Pass ariaLabel for an icon-only trigger with no visible label, or ariaLabelledBy when the element that names the trigger is not a <label> you can point for at.
Configuration passed to the Tooltip Binding's child initializer. Direct completed Block calls use Tooltip.TooltipBlock.init().
| Name | Type | Default | Description |
|---|---|---|---|
id | string | β | Unique ID for the tooltip instance. |
showDelay | Duration.Input | Duration.millis(500) | How long the pointer must hover before the tooltip appears. Accepts any Effect Duration input. A bare number is interpreted as milliseconds. Keyboard focus shows the tooltip immediately regardless of this value. |
Pass the child Model as model and these fields as viewInputs to the Tooltip Binding's embedView method. The Binding supplies the canonical view, Message wrapper, and composition scope. Keep toView at the top level, and spread the published ChildAttribute groups unchanged; see Callback dispatch boundaries.
| Name | Type | Default | Description |
|---|---|---|---|
anchor | AnchorConfig | β | Floating positioning config: placement, gap, offset, padding, isPlacementLocked, and portal. Required. Portaled to the document body, or into an enclosing dialog, by default; pass portal: false to keep the panel inside its wrapper. |
toView | (render: RenderInfo) => Html | β | Callback that receives the trigger and panel attribute bundles plus a derived isVisible flag, and returns the composed layout. |
isDisabled | boolean | false | Disables the trigger. Hover, focus, and keyboard events are ignored and the tooltip will not open. |
ariaLabel | string | β | Accessible name for the trigger button. Use for an icon-only trigger with no visible label. Applied as aria-label, and takes precedence over ariaLabelledBy. |
ariaLabelledBy | string | β | Id of an external element that labels the trigger button, applied as aria-labelledby. Pair with a visible label element. |
Payload delivered to the toView callback each render.
| Name | Type | Default | Description |
|---|---|---|---|
trigger | ReadonlyArray<ChildAttribute> | β | Spread onto the trigger element. Carries type="button", the hover/focus/keyboard handlers, and aria-describedby linking to the panel. |
panel | ReadonlyArray<ChildAttribute<Mount.RequirementsOf<typeof Tooltip.mounts>>> | β | Spread onto the panel element. Carries role="tooltip", the anchor Mount that positions the panel via Floating UI, and a data-open attribute when visible. |
isVisible | boolean | β | Whether the tooltip is currently visible. The consumer decides whether to render the panel conditionally on this. |
Call TooltipBinding.informShowDelayChanged(showDelay) when parent-owned configuration changes the Tooltip's delay. The Binding call returns a connected parent Step. Its producer accepts every Duration.Input form, normalizes the value, and constructs InformedOfShowDelayChange; Tooltip update stores the normalized Duration.
| Binding call | Arguments | Description |
|---|---|---|
TooltipBinding.informShowDelayChanged(showDelay) | showDelay: Duration.Input | Dispatches InformedOfShowDelayChange through Tooltip update. A bare number is milliseconds. The update branch returns { model }, emits no OutMessage, and applies the new delay on the next hover. |
Messages emitted to the parent through the optional outMessage field. They fire only on visibility transitions, so consumers donβt see spurious events for Messages that only update internal hover/focus/delay state.
| Name | Type | Default | Description |
|---|---|---|---|
Shown | {} | β | Emitted once the tooltip transitions to visible (isOpen becomes true). Handle it in the Binding's selected fold policy. Useful for analytics, instrumentation, or coordinating with other transient UI. |
Hidden | {} | β | Emitted once the tooltip transitions to hidden (isOpen becomes false). |