Skip to content
Kimenpre-v1documentation home
Color scheme

ki-tooltip

Give a control a brief, text-only hint when the same information is discoverable elsewhere.

Theme for this example
Color scheme for this example
<ki-tooltip label="Closes the dialog">
<ki-icon-button label="Close">
<span aria-hidden="true">✕</span>
</ki-icon-button>
</ki-tooltip>

Four logical placements — top (default), bottom, start and end — that follow the writing direction in RTL:

Theme for this example
Color scheme for this example
top bottom start end
<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>

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.

Theme for this example
Color scheme for this example
Retention Deleted projects stay restorable for 30 days.
<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.

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

AttributePropertyTypeDefaultDescription
forforstring | undefined–ID of the rich tooltip's external trigger in the same document or shadow tree.
headingheadingstring | undefined–Rich tooltip heading. Pair it with for and optional direct text in the default slot.
labellabelstring''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.
placementplacement"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

SlotDescription
(default)One trigger for a plain tooltip, or direct explanatory text when for and heading are provided. Rich tooltips accept text only.

CSS parts

PartDescription
tooltipThe 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.

TokenDescription
--ki-density-space-scaleMultiplies every scaled container padding and gap (card, dialog, alert, list, list item, select listbox, tab panel, tooltip).
--ki-effect-component-secondary-default-shadowMarsUI 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-smMotion travel distance sm (4px): small slide/settle offsets.
--ki-motion-duration-fastFast interaction transition duration.
--ki-motion-duration-instantZero-duration step: transitions that must complete immediately (reduced-motion fallbacks, instant handoffs).
--ki-motion-easing-outDecelerating interaction transition easing curve.
--ki-motion-easing-standard-accelerateUtility exit curve. M3 md.sys.motion.easing.standard-accelerate. onmars: the MarsUI accelerate curve (ki.easing.in).
--ki-surface-image-tooltip-arrow-endEnd-edge arrow color for a themed tooltip surface.
--ki-surface-image-tooltip-arrow-startStart-edge arrow color for a themed tooltip surface.
--ki-tooltip-arrow-radiusdimension used by the tooltip component for the rounding of the arrow tip (Tooltip master pointer: 1.5px, nearest radius step).
--ki-tooltip-arrow-sizedimension 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-filterComplete backdrop filter behind the tooltip bubble.
--ki-tooltip-bgBase background color of the tooltip. Onmars v1 uses a transparent backing beneath its glass image.
--ki-tooltip-bg-imageOptional CSS background image layered over the tooltip fill. Use none for a solid fill.
--ki-tooltip-border-colorcolor 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-widthdimension 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-fgcolor 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-sizedimension used by the tooltip component for font size (MarsUI Heading_top style UI/Para/medium: body_1 13px).
--ki-tooltip-font-weightfont weight used by the tooltip component for font weight.
--ki-tooltip-line-heightdimension used by the tooltip component for line height (MarsUI line_height/para 20px).
--ki-tooltip-max-inline-sizedimension 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-offsetdimension used by the tooltip component for offset (MarsUI caret depth 8px with zero extra gap = trigger-to-card distance).
--ki-tooltip-padding-blockdimension used by the tooltip component for padding block (MarsUI card padding Space/xl 12px on all sides).
--ki-tooltip-padding-inlinedimension used by the tooltip component for padding inline (MarsUI card padding Space/xl 12px on all sides).
--ki-tooltip-radiusdimension used by the tooltip component for radius (MarsUI Tooltip master 12089:7621 List_wrap: Radius/big_component/radius_xs 16px).
--ki-tooltip-rich-backdrop-filterComplete backdrop filter of the rich surface.
--ki-tooltip-rich-bgFill of the rich tooltip or rich popover.
--ki-tooltip-rich-bg-imageOptional image layer over the rich surface fill.
--ki-tooltip-rich-border-colorOutline ink of the rich surface.
--ki-tooltip-rich-border-widthOutline thickness of the rich surface.
--ki-tooltip-rich-fgInk of the rich surface body text.
--ki-tooltip-rich-font-sizeBody text size of the rich surface.
--ki-tooltip-rich-font-weightBody text weight of the rich surface.
--ki-tooltip-rich-heading-familyTypeface of the rich surface heading.
--ki-tooltip-rich-heading-fgInk of the rich surface heading over the shared fill.
--ki-tooltip-rich-heading-gapDistance between the rich heading and its body.
--ki-tooltip-rich-heading-sizeText size of the rich surface heading.
--ki-tooltip-rich-heading-weightText weight of the rich surface heading.
--ki-tooltip-rich-line-heightBody text line height of the rich surface.
--ki-tooltip-rich-max-widthMaximum inline size of the rich surface.
--ki-tooltip-rich-padding-blockBlock-axis inset of the rich surface, before density scaling.
--ki-tooltip-rich-padding-inlineInline-axis inset of the rich surface, before density scaling.
--ki-tooltip-rich-radiusCorner radius of the rich surface.
--ki-tooltip-rich-shadowRaised elevation of the rich surface.
--ki-tooltip-shadowshadow used by the tooltip component for shadow (MarsUI Elevation/e4 on the master wrap).
--ki-typography-family-bodysemantic font family for typography family body.

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.

Open ki-tooltip in Storybook