Skip to content
Kimenpre-v1documentation home
Color scheme

ki-message

Use a message for each chronological entry in a ki-conversation. The user role aligns a bubble at the inline end. The default assistant role shows a reply with an avatar at the inline start. An event is a centered note with an optional decorative icon-name.

Theme for this example
Color scheme for this example
Can I export these settings? Yes. Choose JSON from the export menu.
View source Settings export guide
Found the export guide
<ki-conversation label="Export help">
<ki-message message-role="user">Can I export these settings?</ki-message>
<ki-message message-role="assistant" author="Ava said">
<ki-avatar slot="avatar" size="xs" initials="AV"></ki-avatar>
<strong>Yes.</strong> Choose <code>JSON</code> from the export menu.
<details slot="actions">
<summary>View source</summary>
Settings export guide
</details>
</ki-message>
<ki-message message-role="event" icon-name="search">Found the export guide</ki-message>
</ki-conversation>

Compose the message

Use the default slot for text or formatted content. Give an assistant reply a custom avatar when it has its own identity. Supply controls such as links or buttons in actions and handle them in your application. See Message actions for the reply toolbar, ratings, regeneration and the branch picker. Import any additional event glyphs the same way you would for ki-icon.

Accessible names and streaming

author sets the article’s complete accessible name. The role defaults are “You said,” “Assistant said” and “System event.” Supply a localized author string such as “Ava dijo” for a Spanish transcript. The visible message content is separate from the name.

Set streaming while appending chunks to the content. The caret stays visible and still with reduced motion. Clear streaming when the response is complete so the polite conversation log can present it as one update.

API reference

When to use: Display an entry in ki-conversation.

When not to use: Prompt input, page alerts or tool execution.

Properties & attributes

AttributePropertyTypeDefaultDescription
actions-labelactionsLabelstring | undefined–Names and enables the assistant toolbar.
authorauthorstring | undefined–Accessible article name. Defaults by role.
branch-countbranchCountnumber | undefined1Total replies. Shows a picker for two or more.
branch-indexbranchIndexnumber | undefined1One-based reply index. Update after accepting a branch request.
branch-status-labelbranchStatusLabelstring | undefined'Response {index} of {count}'Branch announcement template with {index} and {count}.
feedbackfeedback"bad" | "good" | undefined–Good or bad rating. Restore it when switching branches.
icon-nameiconNamestring | undefined–Decorative event icon. Search is built in. Import other icons before use.
message-rolemessageRole"assistant" | "event" | "user" | undefined–Trailing user bubble, leading assistant avatar or centered event.
next-branch-labelnextBranchLabelstring | undefined'Next response'Next branch button label.
previous-branch-labelpreviousBranchLabelstring | undefined'Previous response'Previous branch button label.
streamingstreamingbooleanfalseShow a caret and mark the article busy.

Events

EventDetail typeDescription
ki-branch-changeCustomEvent<{ index: number }>Requests a branch by its one-based index.
ki-feedbackCustomEvent<{ value: KiMessageFeedback }>Reports the selected rating.
ki-regenerateCustomEvent<void>Requests a new reply on Regenerate.

Slots

SlotDescription
(default)Text or formatted content.
actionsApp controls. With actions-label, use direct buttons or a layout-only ki-button-group. Mark regenerate and rating buttons with data-message-action.
avatarOverrides the decorative assistant avatar.

CSS parts

PartDescription
actionsFollow-up controls.
avatarAssistant avatar.
branchesBranch picker and position.
caretDecorative streaming marker.
contentBody and optional event icon.
messageNamed article.

CSS custom properties

The public styling contract of ki-message: reassign these tokens at :root or on a subtree — never override internals.

TokenDescription
--ki-button-ghost-neutral-disabled-bgcolor used by the button component for ghost neutral disabled background.
--ki-button-ghost-neutral-disabled-bordercolor used by the button component for ghost neutral disabled border.
--ki-button-ghost-neutral-disabled-fgcolor used by the button component for ghost neutral disabled foreground.
--ki-button-ghost-neutral-hover-bgcolor used by the button component for ghost neutral hover background.
--ki-button-ghost-neutral-hover-bordercolor used by the button component for ghost neutral hover border.
--ki-button-ghost-neutral-hover-fgcolor used by the button component for ghost neutral hover foreground.
--ki-button-ghost-neutral-rest-bgcolor used by the button component for ghost neutral rest background.
--ki-button-ghost-neutral-rest-bordercolor used by the button component for ghost neutral rest border.
--ki-button-ghost-neutral-rest-fgcolor used by the button component for ghost neutral rest foreground.
--ki-button-xs-radiusdimension used by the button component for xs radius (Button master 8003:300 binds Radius/small-component/xs, the scale a radius mode reassigns).
--ki-control-border-widthStroke width of the boundary of a compact control.
--ki-density-target-minThe smallest pointer target any density may produce: 24 x 24 CSS px by default and in compact (WCAG 2.5.8 AA), 44 x 44 in touch (WCAG 2.5.5). It floors a shrinking control but never lifts what a control paints: a control painted smaller extends its target to it, invisibly; rows and tabs grow to it (spec 045 A1).
--ki-focus-ring-colorColour of the keyboard focus ring every focusable component draws: 3:1 or more against the page in every theme and scheme.
--ki-focus-ring-offsetGap between a focusable component and its keyboard focus ring.
--ki-focus-ring-widthThickness of the keyboard focus ring every focusable component draws (its outline). One token instead of one per component, so a mode or a theme changes every ring at once.
--ki-icon-button-xs-icon-sizedimension used by the icon button component for xs icon size (MarsUI Icon/Placeholder_xs 16px — one step above the button xs icon).
--ki-icon-button-xs-sizedimension used by the icon button component for xs box (24px square, Figma Space/7xl).
--ki-layout-conversation-avatar-radiusRound corner radius of the fallback assistant avatar.
--ki-layout-conversation-bubble-end-radiusSmaller radius of the end corner of a user bubble.
--ki-layout-conversation-caret-block-sizeBlock size of a streaming caret.
--ki-layout-conversation-caret-inline-sizeInline size of a streaming caret.
--ki-layout-conversation-user-max-widthMaximum width of a user bubble relative to the transcript.
--ki-layout-spacing-2xlThe 2xl spacing step for a stack or grid gap.
--ki-layout-spacing-3xlThe 3xl spacing step for a stack or grid gap.
--ki-layout-spacing-9xlThe 9xl spacing step for a stack or grid gap.
--ki-layout-spacing-mdThe md spacing step for a stack or grid gap.
--ki-layout-spacing-xlThe xl spacing step for a stack or grid gap.
--ki-layout-spacing-xxsThe xxs spacing step for a stack or grid gap.
--ki-message-assistant-fgText ink of an assistant reply on the page surface.
--ki-message-avatar-backdrop-filterComplete filter behind the default assistant avatar.
--ki-message-avatar-bgSolid primary container of the default assistant avatar.
--ki-message-avatar-bg-imageOptional image over the default assistant avatar background.
--ki-message-avatar-fgGlyph ink inside the default assistant avatar.
--ki-message-event-fgText and icon ink of a system event on the page surface.
--ki-message-paddingBlock and inline padding inside a user bubble, in that order.
--ki-message-radiusRadius of the user bubble corners.
--ki-message-user-backdrop-filterComplete filter behind the user bubble.
--ki-message-user-bgSolid background of a user bubble.
--ki-message-user-bg-imageOptional image over the user bubble background.
--ki-message-user-fgText ink in a user bubble.
--ki-motion-duration-activity-pulsePeriod of an indeterminate typing pulse.
--ki-motion-easing-activity-pulseSymmetric easing for fluctuations in a typing pulse.
--ki-outline-low-emsemantic color for outline low em.
--ki-typography-family-bodysemantic font family for typography family body.
--ki-typography-line-height-body-2semantic dimension for typography line height body 2.
--ki-typography-line-height-caption-2semantic dimension for typography line height caption 2.
--ki-typography-size-body-2semantic dimension for typography size body 2.
--ki-typography-size-caption-2semantic dimension for typography size caption 2.

Workshop

Open ki-message in Storybook