Tooltip
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.
<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.
- idstring
- HTML id applied to the tooltip content element. Auto-generated when omitted.
- textstring
- Tooltip label text. Can also be set via the #default slot.
- classstring | Array<string> | object
- stylestring | Array<string> | object | StyleValue
- absoluteboolean
- closeOnBackboolean
- contentClassstring | Array<string>
- contentPropsany
- disabledboolean
- noClickAnimationboolean
- modelValueboolean
- v-model for the open state. Controlled mode when provided.
- zIndexnumber | string
- disableGlobalStackboolean
- persistentboolean
- heightnumber | string
- lazybooleantrue
- Defers rendering the content until the first open. Enabled by default for performance.
- maxHeightnumber | string
- maxWidthnumber | string'300px'
- Maximum tooltip width before content wraps.
- minHeightnumber | string
- minWidthnumber | string
- widthnumber | 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.
- activatorPropsany{}
- Props merged onto the activator element via the slot binder.
- openOnClickboolean
- openOnContextMenuboolean
- openOnHoverboolean
- openOnFocusboolean
- closeOnContentClickboolean
- closeDelaynumber | string
- openDelaynumber | string
- locationStrategyTLocationStrategy | TLocationStrategyFn
- Preferred position relative to the activator: top, bottom, start, end, and 2D variants (top start, bottom end, …).
- originTAnchor | 'auto' | 'overlap'
- Transform origin for the entry/exit transition. Defaults to the anchor point.
- offsetnumber | string | Array<number>
- Distance in pixels between the tooltip and the activator edge.
- viewportMarginnumber
- Behavior when the container scrolls: reposition (follow activator) or close.
- containedboolean
- eagerbooleanfalse
- When true, the content is rendered in the DOM even before first open (disables lazy mounting).
- transitionboolean | string | TTransitionProps
- Enter/leave transition. Defaults to origam-translate-scale.
- scrimboolean | string
- attachboolean | string | Element | null
- color
- Foreground color of the tooltip text.
- bgColor
- Background color override. Defaults to neutral.800 (dark inverse surface).
- fontSizeTFontSize
- fontWeightTFontWeight
- lineHeightTLineHeight
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:modelValueany
- 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
Keyboard interactions
| Key | Action |
|---|---|
| Tab / Shift+Tab | Focusing the activator opens the tooltip. Blurring closes it. |
| Escape | Closes 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.
- colorvar(--origam-color__neutral---800)
- Dark inverse background for contrast in both themes.
- colorvar(--origam-color__text---inverse)
- Inverse text color (white on dark surface).
- dimensionvar(--origam-radius---sm)
- Corner radius.
- durationvar(--origam-motion__duration---fast)
- Enter/leave transition duration.
- numbervar(--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
Locations
Colored tooltip