Tooltip

Overlay & Surface
stable

Contextual floating label anchored to an activator element. Appears on hover/focus, auto-positioned via location strategy.

Structure

Anatomy

Visual breakdown of the component's internal structure with BEM class call-outs.

Anatomy of OrigamTooltipSchematic of the Tooltip overlay with 3 numbered internal parts. Tooltip text activator 1 2 3
Anatomy of <origam-tooltip> — overlay wraps a content div ① with the text ②; the activator ③ (any element) triggers visibility.
1.origam-tooltip
Root overlay element — transparent, zero-size. Wraps OrigamOverlay; positions via location strategy. role="tooltip" set explicitly.
2.origam-tooltip__content
Visible content surface. Background: neutral.800 (dark inverse). Contains the text or #default slot.
3[activator]
External activator element projected via #activator slot. Receives aria-describedby pointing to the tooltip id.

API

Props

All props accepted by this component, with their type, default value and description.

id
string
HTML id applied to the tooltip content element. Auto-generated when omitted.
text
string
Tooltip label text. Can also be set via the #default slot.
class
string | Array<string> | object
style
string | Array<string> | object | StyleValue
absolute
boolean
closeOnBack
boolean
contentClass
string | Array<string>
contentProps
any
disabled
boolean
noClickAnimation
boolean
modelValue
boolean
v-model for the open state. Controlled mode when provided.
zIndex
number | string
disableGlobalStack
boolean
persistent
boolean
height
number | string
lazy
boolean
true
Defers rendering the content until the first open. Enabled by default for performance.
maxHeight
number | string
maxWidth
number | string
'300px'
Maximum tooltip width before content wraps.
minHeight
number | string
minWidth
number | string
width
number | string
target
'parent' | 'cursor' | TAnyString | Element | ComponentPublicInstance | [x: number, y: number] | undefined
activator
'parent' | 'cursor' | TAnyString | Element | ComponentPublicInstance
Reference to the activator element. Use the #activator slot instead for most cases.
activatorProps
any
{}
Props merged onto the activator element via the slot binder.
openOnClick
boolean
openOnContextMenu
boolean
openOnHover
boolean
openOnFocus
boolean
closeOnContentClick
boolean
closeDelay
number | string
openDelay
number | string
locationStrategy
TLocationStrategy | TLocationStrategyFn
location
'top'
Preferred position relative to the activator: top, bottom, start, end, and 2D variants (top start, bottom end, …).
origin
TAnchor | 'auto' | 'overlap'
Transform origin for the entry/exit transition. Defaults to the anchor point.
offset
number | string | Array<number>
Distance in pixels between the tooltip and the activator edge.
viewportMargin
number
scrollStrategy
'reposition'
Behavior when the container scrolls: reposition (follow activator) or close.
contained
boolean
eager
boolean
false
When true, the content is rendered in the DOM even before first open (disables lazy mounting).
transition
boolean | string | TTransitionProps
Enter/leave transition. Defaults to origam-translate-scale.
scrim
boolean | string
attach
boolean | string | Element | null
color
Foreground color of the tooltip text.
bgColor
Background color override. Defaults to neutral.800 (dark inverse surface).
fontSize
TFontSize
fontWeight
TFontWeight
lineHeight
TLineHeight

API

Slots

Content slots exposed by this component.

#activator
The element that triggers the tooltip. Receives `props` to forward (aria-describedby, onMouseenter, onFocus, …) via v-bind.
#default
Tooltip content. Falls back to rendering the text prop as a plain span.

API

Emits

Events emitted by this component.

@update:modelValue
any
Fired when the open state changes.

API

Exposed members

Properties and methods accessible via template ref (defineExpose). Use them for programmatic control.

<T extends object>(props: T, exclude?: string[]) => Partial<T>
Utility to forward a filtered subset of props to OrigamOverlay.
Ref<string>
Reactive CSS string for computed tooltip styles.
string
Unique ID for this tooltip instance (referenced by aria-describedby on the activator).
() => void
Injects the computed style sheet.
() => void
Removes the injected style sheet.
Ref<boolean>
True once the style sheet has been injected.
string
Unique style-sheet ID scoping injected CSS rules.

Customisation

CSS variables

CSS custom properties exposed by this component. Override them to customise the component without losing theme compatibility.

Tooltip background. Dark inverse surface for contrast in both themes.
Tooltip text color.
Font size of the tooltip label.
Corner radius of the tooltip pill.
Maximum width before tooltip text wraps.
Z-index of the tooltip overlay.
Enter/leave transition duration.

Inclusion

Accessibility

ARIA roles, keyboard navigation and focus management. Sourced from the real component template.

ARIA roles

tooltip

Keyboard interactions

Keyboard interactions
KeyAction
Tab / Shift+TabFocusing the activator opens the tooltip. Blurring closes it.
EscapeCloses the tooltip if it was opened via keyboard focus.

Notes

  • The activator element receives aria-describedby pointing to the tooltip id so screen readers announce the tooltip text.
  • role="tooltip" is applied directly on the OrigamOverlay element (not just the content div) so the association is unambiguous.
  • Transitions are disabled under prefers-reduced-motion: reduce.

Foundation

Design tokens

Excerpt from this component's token declarations — the --origam-<component>---<property> variables, declared in its hand-maintained token sheet with no build step.

Source
color
var(--origam-color__neutral---800)
Dark inverse background for contrast in both themes.
color
var(--origam-color__text---inverse)
Inverse text color (white on dark surface).
dimension
var(--origam-radius---sm)
Corner radius.
duration
var(--origam-motion__duration---fast)
Enter/leave transition duration.
number
var(--origam-zIndex---tooltip)
Z-index layer.

Interactive

Playground

Edit props live and see the component update in real time. The generated code snippet updates as you change values.

Rendering the live preview…

Usage

Examples

Ready-to-paste code snippets for your templates.

Basic tooltip

vue

Locations

vue

Colored tooltip

vue