Skip to content
Kimenpre-v1documentation home
Color scheme

ki-conversation

Use the conversation for a chronological exchange between a person and an assistant. Add a ki-message for each turn or system event. Keep the composer outside the transcript so it stays outside the live region.

Theme for this example
Color scheme for this example
Which inputs handle form errors? Searched the component docs Input, textarea and select show field errors.
<ki-conversation label="Component help">
<ki-message message-role="user">Which inputs handle form errors?</ki-message>
<ki-message message-role="event" icon-name="search">Searched the component docs</ki-message>
<ki-message message-role="assistant" author="Ava said">
Input, textarea and select show field errors.
</ki-message>
</ki-conversation>

Following the conversation

Give the host a block size and set stick-to-bottom to follow new messages and growing replies. When the person scrolls back, the log stays at their reading position and a Jump to latest button appears. Scrolling to the end or activating the button resumes following. Omit stick-to-bottom for manual scrolling.

Theme for this example
Color scheme for this example
The first release added forms. The next release added navigation. The third release introduced the icon set. The fourth release added page layouts. The latest release adds conversation views.
<ki-conversation label="Release history" stick-to-bottom style="block-size: 9rem">
<ki-message>The first release added forms.</ki-message>
<ki-message>The next release added navigation.</ki-message>
<ki-message>The third release introduced the icon set.</ki-message>
<ki-message>The fourth release added page layouts.</ki-message>
<ki-message>The latest release adds conversation views.</ki-message>
</ki-conversation>

Message actions

Set actions-label on an assistant reply to give its actions one Tab stop. Left and Right Arrow move through the controls, and Home and End move to the first and last controls. The latest assistant reply shows its toolbar. Earlier replies reveal theirs on hover or when focus enters the reply. Devices without hover keep the actions visible.

Use ButtonGroup in its default layout mode. The message handles keyboard movement across Copy, Regenerate, the rating buttons, the More trigger and the branch picker. Give each More trigger a unique ID and point Menu to it. CopyButton can read the current reply from the element identified by from.

<ki-conversation label="Export help">
<ki-message id="reply" actions-label="Reply actions" branch-index="2" branch-count="3">
<span id="reply-text">Choose JSON from the export menu.</span>
<ki-button-group slot="actions" label="Reply commands">
<ki-copy-button from="reply-text" size="sm" label="Copy reply"></ki-copy-button>
<ki-icon-button data-message-action="regenerate" size="sm" variant="ghost" label="Regenerate">
<ki-icon name="refresh-cw"></ki-icon>
</ki-icon-button>
<ki-icon-button data-message-action="good" size="sm" variant="ghost" label="Good response">
<ki-icon name="thumbs-up"></ki-icon>
</ki-icon-button>
<ki-icon-button data-message-action="bad" size="sm" variant="ghost" label="Bad response">
<ki-icon name="thumbs-down"></ki-icon>
</ki-icon-button>
<ki-icon-button id="reply-more" size="sm" variant="ghost" label="More actions">
<ki-icon name="ellipsis"></ki-icon>
</ki-icon-button>
<ki-menu anchor="reply-more">
<ki-menu-item value="sources">View sources</ki-menu-item>
</ki-menu>
</ki-button-group>
</ki-message>
</ki-conversation>

Import the four glyphs using the per-icon modules. Keep the labels of the rating buttons stable. The message sets their pressed states and emits ki-feedback with { value: 'good' | 'bad' }. Store the rating in the app if it should persist. A form for additional feedback is optional. Handle ki-regenerate to request a new answer and ki-select for the menu action.

ki-branch-change carries { index }, a one-based request. Update the reply text and branchIndex together after accepting it. Set feedback to that branch’s saved rating, or remove it to clear both pressed states. CopyButton reads the updated text on the next activation. Localize the branch picker with previous-branch-label, next-branch-label and branch-status-label. The status template takes {index} and {count}.

Accessibility

The label prop names the polite log. Give each transcript a distinct name if a page contains more than one. Localize Jump to latest with jump-label. After the person activates that button with the keyboard, focus returns to the log.

A streaming reply exposes a busy article while the text arrives. Clear streaming once the final reply is in the DOM so assistive technology can present it as a single update. Use author to localize the accessible name of each article. See the message guide for role defaults.

API reference

When to use: Display chronological user, assistant and event messages. Give the host a block-size constraint to keep scrolling within the transcript.

When not to use: Collect input, send messages or present a static sequence of cards. Place the composer outside the transcript.

Properties & attributes

AttributePropertyTypeDefaultDescription
jump-labeljumpLabelstring'Jump to latest'Visible and accessible label for the control that resumes following.
labellabelstring'Conversation'Accessible name of the transcript. Supply a distinct label when several logs share a page.
stick-to-bottomstickToBottombooleanfalseFollow new or growing messages until the reader scrolls away from the end.

Slots

SlotDescription
(default)The chronological transcript, normally ki-message elements.

CSS parts

PartDescription
jumpThe Jump to latest button shown while following is paused.
logThe named polite live region and keyboard-focusable scrollport.
messagesThe stack of slotted messages inside the scrollport.

CSS custom properties

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

TokenDescription
--ki-conversation-gapSpace between messages in the transcript.
--ki-conversation-max-widthMaximum inline size of the transcript.
--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-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-layout-spacing-mdThe md spacing step for a stack or grid gap.
--ki-typography-family-bodysemantic font family for typography family body.

Workshop

Open ki-conversation in Storybook