ki-tooltip
@kimen/elements/ki-tooltip- Source
- Agent reference
Give a control a brief, text-only hint when the same information is discoverable elsewhere.
<ki-tooltip label="Closes the dialog"><ki-icon-button label="Close"> <span aria-hidden="true">✕</span></ki-icon-button></ki-tooltip>Examples
Section titled “Examples”Placement
Section titled “Placement”Four logical placements — top (default), bottom, start and end —
that follow the writing direction in RTL:
<ki-tooltip label="Above (default)" placement="top"><ki-button type="button">top</ki-button></ki-tooltip><ki-tooltip label="Below" placement="bottom"><ki-button type="button">bottom</ki-button></ki-tooltip><ki-tooltip label="Inline start" placement="start"><ki-button type="button">start</ki-button></ki-tooltip><ki-tooltip label="Inline end" placement="end"><ki-button type="button">end</ki-button></ki-tooltip>Rich tooltip
Section titled “Rich tooltip”Pair heading with for, the ID of a trigger in the same document or
shadow tree. Put the explanation directly in the default slot as text. The
heading and body describe the trigger before the tooltip opens.
<ki-button id="retention-info" type="button" variant="ghost">Retention</ki-button><ki-tooltip for="retention-info" heading="Grace period">Deleted projects stay restorable for 30 days.</ki-tooltip>Hover over the trigger or focus it to reveal the tooltip. You can move the
pointer onto the tooltip or press Escape to dismiss it. For links and
buttons, use ki-popover with kind="toggletip" and appearance="rich".
Both rich surfaces use the --ki-tooltip-rich-* tokens.
API reference
Section titled “API reference”When to use: add a brief clarifying hint for an icon-only, abbreviated, or otherwise ambiguous control when the same information is discoverable elsewhere in the interface.
When not to use: essential or unique information in a tooltip; interactive content in a tooltip; form validation messages, disabled controls, or touch-primary flows. Use visible layout text or a rich ki-popover with kind="toggletip" when the content includes actions.
Properties & attributes
| Attribute | Property | Type | Default | Description |
|---|---|---|---|---|
for | for | string | undefined | – | ID of the rich tooltip's external trigger in the same document or shadow tree. |
heading | heading | string | undefined | – | Rich tooltip heading. Pair it with for and optional direct text in the default slot. |
label | label | string | '' | The entire plain tooltip content. The string is reflected to the slotted trigger's accessible description without changing its name. Empty or whitespace-only labels render no tooltip and expose no description. When to use: a short hint that clarifies the slotted trigger. When NOT to use: never use label for essential information, rich content, interactive content, validation messages, or information attached to disabled controls; put that content in visible UI or a popover. |
placement | placement | "bottom" | "end" | "start" | "top" | 'top' | Preferred placement for the tooltip. The component may flip or clamp the rendered placement to keep the bubble inside the viewport; unknown runtime values fall back to top. When NOT to use: do not depend on placement for meaning or reading order. |
Slots
| Slot | Description |
|---|---|
| (default) | One trigger for a plain tooltip, or direct explanatory text when for and heading are provided. Rich tooltips accept text only. |
CSS parts
| Part | Description |
|---|---|
tooltip | The non-focusable tooltip bubble. |
CSS custom properties
The public styling contract of ki-tooltip: reassign these tokens at :root or on a subtree — never override internals.
| Token | Description |
|---|---|
--ki-density-space-scale | Multiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip). |
--ki-effect-component-secondary-default-shadow | MarsUI Component_effect/secondary_default: drop 0/2/1.5/-0.5 plus inner White/3 0/2/3. Pair with --ki-effect-component-backdrop-filter. |
--ki-motion-distance-sm | Motion travel distance sm (4px): small slide/settle offsets. |
--ki-motion-duration-fast | Fast interaction transition duration. |
--ki-motion-duration-instant | Zero-duration step: transitions that must complete immediately (reduced-motion fallbacks, instant handoffs). |
--ki-motion-easing-out | Decelerating interaction transition easing curve. |
--ki-motion-easing-standard-accelerate | Utility exit curve. M3 md.sys.motion.easing.standard-accelerate. onmars: the MarsUI accelerate curve (ki.easing.in). |
--ki-surface-image-tooltip-arrow-end | End-edge arrow color for a themed tooltip surface. |
--ki-surface-image-tooltip-arrow-start | Start-edge arrow color for a themed tooltip surface. |
--ki-tooltip-arrow-radius | dimension used by the tooltip component for the rounding of the arrow tip (Tooltip master pointer: 1.5px, nearest radius step). |
--ki-tooltip-arrow-size | dimension used by the tooltip component for the depth of the arrow that points at the trigger; it is twice as wide (Tooltip master 12089:7621 pointer: 16x8). Zero removes it. Equal to offset, so the tip meets the trigger. |
--ki-tooltip-backdrop-filter | Complete backdrop filter behind the tooltip bubble. |
--ki-tooltip-bg | Base background color of the tooltip. Onmars v1 uses a transparent backing beneath its glass image. |
--ki-tooltip-bg-image | Optional CSS background image layered over the tooltip fill. Use none for a solid fill. |
--ki-tooltip-border-color | color used by the tooltip component for its edge (MarsUI hairline bevel, Outline/secondary_button_top); one token so a mode or a theme can strengthen it. |
--ki-tooltip-border-width | dimension used by the tooltip component for the bevel outline width (MarsUI glass card 1px Outline/secondary_button_top stroke; replaces the 1px literal ki-tooltip.css shipped while the token was pending). |
--ki-tooltip-fg | color used by the tooltip component for foreground (MarsUI title row Text/high_em; lands together with the glass background — white-on-glass would break contrast). |
--ki-tooltip-font-size | dimension used by the tooltip component for font size (MarsUI Heading_top style UI/Para/medium: body_1 13px). |
--ki-tooltip-font-weight | font weight used by the tooltip component for font weight. |
--ki-tooltip-line-height | dimension used by the tooltip component for line height (MarsUI line_height/para 20px). |
--ki-tooltip-max-inline-size | dimension used by the tooltip component for max inline size (288px; the master card is fixed 280px wide in its rich variants — the 8px divergence is a documented text-only reduction). |
--ki-tooltip-offset | dimension used by the tooltip component for offset (MarsUI caret depth 8px with zero extra gap = trigger-to-card distance). |
--ki-tooltip-padding-block | dimension used by the tooltip component for padding block (MarsUI card padding Space/xl 12px on all sides). |
--ki-tooltip-padding-inline | dimension used by the tooltip component for padding inline (MarsUI card padding Space/xl 12px on all sides). |
--ki-tooltip-radius | dimension used by the tooltip component for radius (MarsUI Tooltip master 12089:7621 List_wrap: Radius/big_component/radius_xs 16px). |
--ki-tooltip-rich-backdrop-filter | Complete backdrop filter of the rich surface. |
--ki-tooltip-rich-bg | Fill of the rich tooltip or rich popover. |
--ki-tooltip-rich-bg-image | Optional image layer over the rich surface fill. |
--ki-tooltip-rich-border-color | Outline ink of the rich surface. |
--ki-tooltip-rich-border-width | Outline thickness of the rich surface. |
--ki-tooltip-rich-fg | Ink of the rich surface body text. |
--ki-tooltip-rich-font-size | Body text size of the rich surface. |
--ki-tooltip-rich-font-weight | Body text weight of the rich surface. |
--ki-tooltip-rich-heading-family | Typeface of the rich surface heading. |
--ki-tooltip-rich-heading-fg | Ink of the rich surface heading over the shared fill. |
--ki-tooltip-rich-heading-gap | Distance between the rich heading and its body. |
--ki-tooltip-rich-heading-size | Text size of the rich surface heading. |
--ki-tooltip-rich-heading-weight | Text weight of the rich surface heading. |
--ki-tooltip-rich-line-height | Body text line height of the rich surface. |
--ki-tooltip-rich-max-width | Maximum inline size of the rich surface. |
--ki-tooltip-rich-padding-block | Block-axis inset of the rich surface, before density scaling. |
--ki-tooltip-rich-padding-inline | Inline-axis inset of the rich surface, before density scaling. |
--ki-tooltip-rich-radius | Corner radius of the rich surface. |
--ki-tooltip-rich-shadow | Raised elevation of the rich surface. |
--ki-tooltip-shadow | shadow used by the tooltip component for shadow (MarsUI Elevation/e4 on the master wrap). |
--ki-typography-family-body | semantic font family for typography family body. |
Accessibility
Section titled “Accessibility”The tooltip’s label becomes the trigger’s accessible description,
never its name — the trigger still owns its own label. Never put essential
or unique information, interactive content, or form validation messages in
a tooltip; tooltips are unreliable on touch-primary flows and invisible to
anyone who never hovers or focuses the trigger.