Chat
Agent conversations with unboxed answers, activity disclosures, user bubbles, long-message collapse, waiting queues, and steering
Long Messages And Links
Messages wrap long text and links; pre blocks scroll within their message body instead
of widening the transcript. Keep readable link text and native keyboard focus.
Scrollable code blocks should use tabindex="0" and a descriptive accessible
label so Safari keyboard users can reach and scroll them.
Transcript height, message updates, announcement policy and scroll-indicator
navigation belong to the application. Existing chat-scroll / data-chat-tl
contracts remain unchanged. Do not treat timeline styling as automatic message
loading or scroll-position management.
Chat
Chat provides CSS-only primitives for agent conversations. User messages appear in rounded bubbles; agent answers render directly in the transcript, with optional avatars, activity disclosures, reasoning traces, tool calls, and streaming states.
Basic Usage
Use .chat.chat-end with .chat-bubble for user messages. Use .chat.chat-start.chat-agent with .chat-content for agent output: it takes the available width with no bubble background, border, or padding. Put any existing .avatar inside an optional .chat-avatar; omit the slot when no avatar is needed. Start and end alignment follow the text direction, including RTL transcripts.
Wrap a transcript in .chat-scroll when the conversation should scroll inside a fixed-height panel. Scroll behavior defaults to smooth. Pair agent replies with matching indicators via data-chat-tl so Scroll-Driven Animations can sync the rail with visible assistant rows.
Basic Chat
<div id="demo-basic-chat" style="width: min(42rem, 100%); display: flex; flex-direction: column; gap: 1rem;">
<div class="chat chat-start chat-agent">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-primary">AI</div>
</div>
<div class="chat-header">Agent - 2:15 PM</div>
<div class="chat-content">How can I help you today?</div>
<div class="chat-footer">Delivered</div>
</div>
<div class="chat chat-end">
<div class="chat-avatar">
<div class="avatar avatar-sm">GA</div>
</div>
<div class="chat-header">You - 2:16 PM</div>
<div class="chat-bubble chat-bubble-primary">Show me a compact chat transcript.</div>
<div class="chat-footer">Sent</div>
</div>
</div>Agent Answers And Activity
Keep the answer in a direct .chat-content block, adding .markdown-body for rich text.
Group work records in native <details class="chat-work"> with a .chat-work-summary
and .chat-work-body. The compact summary can show Worked, tool or command counts,
and failed operations; the application supplies those labels and values.
Place the work disclosure before a completed answer. During progress, a brief content
update may come first, with the activity summary below it. The answer stays visible
when the work disclosure is closed. Reasoning and tool records can be nested inside
the work body or placed directly in the agent row. All disclosures use native
<details> / <summary> interaction and need no toggle script.
This static example illustrates completed checks and a pending preview retry; it does not execute tools or make network requests.
Worked · 3 tool calls · 1 failed
Review approach
read_component_sourceDone
run_scoped_testsDone
capture_mobile_previewFailed
Reviewed the chat components. The focused behavior checks passed; the mobile preview needs another attempt.
- Waiting messages keep their sending order.
- Steer adds a message to the active conversation immediately.
- Sent user messages taller than six lines can be expanded.
Use a direct agent content block for the answer:
<div class="chat-content markdown-body">Answer</div>2 commands · 1 other operation · 1 failed
check_preview_serverFailed
start_preview_serverDone
retry_mobile_previewRunning...
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-primary">Review the chat components.</div>
</div>
<div class="chat chat-start chat-agent">
<div class="chat-avatar"><div class="avatar avatar-sm avatar-primary">AI</div></div>
<details class="chat-work">
<summary class="chat-work-summary">Worked · 3 tool calls · 1 failed</summary>
<div class="chat-work-body">
<p>Source and scoped tests checked. The mobile preview needs a retry.</p>
</div>
</details>
<div class="chat-content markdown-body">
<p><strong>Review complete.</strong> Queue, steer, and long-message checks passed.</p>
</div>
</div>
Collapsible Sent Messages
Add .chat-bubble-collapsible to sent user bubbles to keep messages taller than
six rendered lines compact. Put the message text in a direct .chat-bubble-content
child and a native .chat-bubble-toggle button after it. The collapsed content preserves
newlines and wraps naturally; Show more reveals the complete message and changes to
Show less. Short messages and messages of exactly six rendered lines need no toggle.
Assistant replies and waiting queue items keep their existing presentation.
<div class="chat chat-end">
<div class="chat-header">You</div>
<div class="chat-bubble chat-bubble-primary chat-bubble-collapsible">
<div class="chat-bubble-content" id="demo-long-message" tabindex="-1">Review the chat view.
Keep the waiting queue.
Support immediate steer.
Preserve message order.
Keep multiline text.
Check keyboard focus.
Check narrow screens.
Share the results.</div>
<button class="btn btn-ghost btn-xs chat-bubble-toggle" type="button"
aria-controls="demo-long-message" aria-expanded="false" hidden>Show more</button>
</div>
</div>
The application wires the toggle and decides when it is needed. After rendering, compare
the content’s natural scrollHeight against six times its computed line height,
allowing one pixel for rounding. Reveal the button only when content exceeds that limit.
On click, switch its aria-expanded value and Show more / Show less label;
core CSS reads aria-expanded="true" to remove the height limit. Give each content
element a unique ID and reference it through aria-controls.
Use ResizeObserver to remeasure actual wrapped lines when the available width changes,
and refresh after message text updates (or observe them with MutationObserver). If a
message becomes short enough, hide its button and reset aria-expanded to false.
Before hiding a focused button, move focus to the controlled content with tabindex="-1".
Disconnect observers when removing messages or leaving the page. The demos use a shared
controller with cleanup on Astro navigation; this controller is documentation code,
and core remains CSS-only. Sent, steered, and automatically dispatched user messages
in the waiting-queue demo all use this same behavior.
Waiting Queue And Steer
Keep messages sent during an active reply in a separate .chat-queue, in sending order.
A waiting message enters the transcript when the application dispatches it after the
current reply completes. Steer dispatches that message immediately: remove it from
the waiting queue, add its user row to the current conversation, and use it to guide
the active reply. Steer does not cancel the active reply or start another assistant turn.
Remove discards a waiting message without sending it.
This demo starts with an active simulated reply and two waiting messages so the queue is visible immediately. Use a row’s Steer to add it to the same current reply, or Complete response to finish that reply and send the oldest waiting message first. Start fresh returns to the idle greeting. The demo has no backend or generated answer.
Message Queue (0)
0 QueuedReady. 0 messages waiting.
Place the queue and composer in one .chat-input-area. The queue forms a shallow,
inset tray tucked behind the rounded composer, with one message per row and no
individual card borders or colored fills. A leading .chat-queue-icon introduces the
single-line preview; a native title preserves the full message. Keep the queue’s
accessible heading and ordered positions visually hidden, and announce the waiting
count through the polite status region. Every row keeps its icon-only Steer and Remove actions available, with accessible
names and descriptions in native Popover tooltips. The application still marks the next message
with .chat-queue-item-active and updates its position when the queue changes; the
leading icon provides emphasis without an active border highlight.
Multiple rows share the same tray. Add an optional .chat-queue-attachment thumbnail
beside a message preview when the caller already has attached media. The caller supplies
the image source and meaningful alternative text; this presentation primitive does not
upload files or manage attachment state. The live demo uses text-only drafts.
Use .chat-composer with a labelled native .chat-composer-input textarea and adjacent
icon-only ghost actions. The primary action is named Send while idle and Queue during a reply; its name and shortcut appear in a native Popover tooltip.
The composer’s Steer action sends the current draft directly into the active
conversation without adding it to the waiting queue. It is disabled while idle or when the draft is blank.
Disable submission for empty or whitespace-only drafts without native validation
bubbles. The draft clears only after successful admission. The help icon opens
usage instructions in a native Popover. Use
.chat-composer-ghost for the reference’s transparent border while retaining its
keyboard focus treatment.
| Key | Action |
|---|---|
Enter |
Send while idle; queue while a reply is active |
Shift+Enter |
Insert a native textarea newline |
Ctrl+Enter or ⌘+Enter |
Steer the current draft immediately while a reply is active |
Ignore shortcuts during input-method composition, including isComposing and legacy
key code 229, so pressing Enter to confirm an IME candidate never sends the draft.
Keep native selection and editing. The textarea grows and shrinks with its content,
scrolls internally at 16rem, and has no manual resize handle. Complete response
is a separate demo control that simulates completion; it is not a composer action.
<div class="chat-input-area">
<section class="chat-queue" aria-labelledby="demo-waiting-title">
<div class="chat-queue-header sr-only">
<h3 class="chat-queue-title" id="demo-waiting-title">Message Queue (1)</h3>
<span class="chat-queue-count">1 Queued</span>
</div>
<ol class="chat-queue-list" role="list" tabindex="0" aria-label="Waiting messages">
<li class="chat-queue-item chat-queue-item-active">
<svg class="chat-queue-icon" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m8 6 4 4-4 4"/><path d="M12 10H5m10-4h4m-4 6h4m-4 6h4"/></svg>
<span class="chat-queue-number sr-only">#1</span>
<img class="chat-queue-attachment" src="mockup.png" alt="Attached mockup" />
<div class="chat-queue-content" title="Also include the accessibility checks.">Also include the accessibility checks.</div>
<div class="chat-actions chat-queue-actions">
<button class="btn btn-ghost btn-sm btn-square chat-queue-steer" type="button" aria-label="Steer waiting message 1">
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m15 4 5 5-5 5"/><path d="M20 9h-9a6 6 0 0 0-6 6v4"/></svg>
</button>
<button class="btn btn-ghost btn-sm btn-square chat-queue-remove" type="button" aria-label="Remove waiting message 1">
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M3 6h18M9 6V3h6v3M5 6l1 15h12l1-15M10 10v7m4-7v7"/></svg>
</button>
</div>
</li>
</ol>
</section>
<form class="chat-composer chat-composer-ghost">
<label class="sr-only" for="demo-waiting-message">Message</label>
<textarea class="chat-composer-input" id="demo-waiting-message" name="message" rows="1" placeholder="Message the agent…"></textarea>
<div class="chat-composer-actions">
<button class="btn btn-ghost btn-sm btn-square" type="submit" aria-label="Queue message" aria-keyshortcuts="Enter" disabled>
<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M12 19V5m-7 7 7-7 7 7"/></svg>
</button>
<button class="btn btn-ghost btn-sm btn-square" type="button" aria-label="Steer current message" aria-keyshortcuts="Control+Enter Meta+Enter" disabled>
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m15 4 5 5-5 5"/><path d="M20 9h-9a6 6 0 0 0-6 6v4"/></svg>
</button>
</div>
</form>
</div>
<p class="chat-status" role="status" aria-live="polite" aria-atomic="true">1 message waiting.</p>
Core supplies presentation only; the application owns queue state, completion events,
network requests, steering support, and keyboard handlers. Wire Enter to the form’s
native submission and Ctrl/⌘+Enter to immediate steering, keeping Shift+Enter native.
The sample buttons need application handlers and composition guards. Enable them
only when a nonblank draft is available. Use .tooltip[popover="hint"] with
interestfor and aria-describedby for action names and shortcut descriptions;
use a help button with popovertarget for longer instructions.
For real asynchronous integrations, await successful dispatch or steering acknowledgment
before dequeuing a message; keep rejected messages available for retry. Give each message
a stable identity so a completed or steered message cannot be dispatched twice. Hide an
empty queue with hidden rather than leaving an empty panel in the layout.
Composer Parts
Compose the existing shell with optional references, quote previews, attachments, suggestions, and a toolbar. These are visual parts: Core does not create an editor, resolve a reference, upload a file, submit a draft, or mutate a waiting queue. The compact examples below use local demo handlers for configuration, file previews, and send/stop. No files are uploaded and no model request is made.
Anatomy And States
Only the shell and a labelled editor are required for an editable composer. Keep submission actions outside scrolling editor, attachment, and suggestion regions. All other parts are optional; reuse existing button, chip, popover, and progress classes.
| Part / classes | Expected element and visual state contract |
|---|---|
.chat-composer |
Form or container; retains the currentColor border/focus ring, seven semantic variants, and ghost variant. data-state="readonly", data-state="disabled" / aria-disabled="true", and data-state="error" / aria-invalid="true" describe the displayed shell state. |
.chat-composer-input, .chat-composer-editor |
Labelled native <textarea> or scoped contenteditable editor; shared text, caret, selection, content-based sizing, and bounded overflow. Existing .chat-composer-input usage remains supported. |
.chat-composer-editor[contenteditable] |
Give the editable surface role="textbox", aria-multiline="true", and an accessible name. data-placeholder plus application-managed data-empty="true" supplies the rich-editor placeholder. Native textareas use placeholder. |
.chip.chat-composer-reference |
Atomic reference label, optionally with an existing button. Use data-selected="true", aria-invalid="true", or aria-busy="true" for selected, invalid, and resolving presentation; put contenteditable="false" on atomic nodes inside an editor. |
.chat-composer-label |
Flexible, truncated label for references or suggestion rows. Retain full text and a native title when the preview is truncated. |
.chat-composer-quote, .chat-composer-quote-text |
Quote preview container and <blockquote> text, with optional attribution and removal button. data-selected="true" marks a selected quote. The application retains the complete quote behind a bounded preview. |
.chat-composer-attachments, .chat-composer-attachment |
Named <ul role="list"> and <li> items. Item data-state values: validating, uploading, ready, error, cancelled. State text and available actions come from the application. |
.chat-composer-preview, .chat-composer-attachment-info, .chat-composer-filename |
Optional image/icon preview, flexible metadata wrapper, and truncated filename. Images need alternative text; use existing native .progress for upload values. |
.chat-composer-description |
Supporting text such as attribution, file status, or suggestion details. |
.chat-composer-toolbar, .chat-composer-actions |
Wrapping control row and submission action group. Add .chat-composer-toolbar-compact for a single compact row and .chat-composer-config to let a configuration trigger truncate before the icon actions. |
.chat-composer-thumbnails, .chat-composer-attachment-tile, .chat-composer-attachment-remove |
Optional horizontal attachment strip, square image tile, and overlaid icon removal action. Place the strip above the editor and hide it when empty. |
.popover.chat-composer-menu, .chat-composer-menu-end |
Native configuration Popover, bounded to the viewport with anchor flip fallbacks. Use the end modifier for settings on the right. Compose rows with .popover-menu-item, .chat-composer-menu-option[aria-pressed], .chat-composer-menu-row, and .chat-composer-menu-field. |
.chat-composer-status |
Optional status text with data-state="pending", "unknown", or "error". Use role="status" for polite updates or role="alert" for actionable validation errors, and connect the editor with aria-describedby. |
.chat-composer-completions |
In-flow suggestion surface or native [popover] surface. The host supplies a unique position-anchor; Core supplies viewport bounds and block/inline flip fallbacks. |
.chat-composer-breadcrumb, .chat-composer-group |
Optional directory navigation and labelled suggestion group heading. The application owns directory queries and drill-down behavior. |
.chat-composer-option, .chat-composer-completions > [role="option"] |
Suggestion row; data-active="true" or aria-selected="true" displays the active row, and aria-disabled="true" displays an unavailable choice. Nested rows require .chat-composer-option; the host prevents unavailable selection. |
.chat-queue-item[data-state] |
Existing queue row with optional editing, stale, conflict, or consuming presentation. Preserve stable row identities, visible actions, and application-owned queue revisions. |
State attributes supply presentation only. Enforce disabled/read-only behavior with
native disabled / readonly, contenteditable="false", or the host’s appropriate
interaction boundary. Do not make an active model run imply a read-only editor.
A selected visual node does not acquire selection or removal behavior from CSS.
Compact Composition
Compact Composer
<div class="chat-input-area" style="width: min(48rem, 100%)">
<form class="chat-composer chat-composer-ghost" data-compact-composer="composer-plain">
<ul class="chat-composer-attachments chat-composer-thumbnails" role="list" aria-label="Draft attachments" data-attachments hidden>
</ul>
<label class="sr-only" for="demo-composer-plain-message">Message</label>
<textarea class="chat-composer-input" id="demo-composer-plain-message" rows="1" placeholder="Describe the next change…"></textarea>
<input type="file" multiple hidden aria-label="Attach files" data-file-input />
<div class="chat-composer-toolbar chat-composer-toolbar-compact">
<button class="btn btn-ghost btn-sm btn-circle" type="button" aria-label="Add files and more" popovertarget="demo-composer-plain-add" interestfor="demo-composer-plain-add-tip" aria-describedby="demo-composer-plain-add-tip" style="anchor-name: --demo-composer-plain-add"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M12 5v14M5 12h14"/></svg></button>
<button class="btn btn-ghost btn-sm btn-circle" type="button" aria-label="Approval mode: Ask for approval" data-permission-trigger popovertarget="demo-composer-plain-permissions" interestfor="demo-composer-plain-permissions-tip" aria-describedby="demo-composer-plain-permissions-tip" style="anchor-name: --demo-composer-plain-permissions"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m12 3 8 4v5c0 5-8 9-8 9s-8-4-8-9V7l8-4Z"/><path d="m9 12 2 2 4-4"/></svg></button>
<div class="chat-composer-actions">
<button class="btn btn-ghost btn-sm chat-composer-config" type="button" aria-label="Model and reasoning: Model A, Medium" data-config-trigger popovertarget="demo-composer-plain-settings" style="anchor-name: --demo-composer-plain-settings"><span class="chat-composer-label" data-config-label>Model A · Medium</span><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m6 9 6 6 6-6"/></svg></button>
<button class="btn btn-primary btn-sm btn-circle" type="submit" aria-label="Send message" aria-keyshortcuts="Control+Enter Meta+Enter" data-send interestfor="demo-composer-plain-send-tip" aria-describedby="demo-composer-plain-send-tip" style="anchor-name: --demo-composer-plain-send" disabled><span data-send-icon><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M12 19V5m-7 7 7-7 7 7"/></svg></span><span data-stop-icon hidden><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><rect x="6" y="6" width="12" height="12" rx="1" fill="currentColor" stroke="none"/></svg></span></button>
</div>
</div>
<div class="popover popover-menu chat-composer-menu" id="demo-composer-plain-add" popover aria-label="Add files and more" style="position-anchor: --demo-composer-plain-add">
<div class="chat-composer-group">Add</div>
<button class="popover-menu-item" type="button" data-attach-files><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m8 12 7-7a3 3 0 0 1 4 4L9 19a5 5 0 0 1-7-7L12 2m-7 12 9-9"/></svg><span>Files</span></button>
<button class="popover-menu-item" type="button" popovertarget="demo-composer-plain-sources"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8Z"/><path d="M14 2v6h6M8 13h8M8 17h5"/></svg><span>Source reference</span></button>
<button class="popover-menu-item" type="button" popovertarget="demo-composer-plain-help"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="9"/><path d="M12 11v6M12 7h.01"/></svg><span>Composer help</span></button>
</div>
<div class="popover popover-menu chat-composer-menu" id="demo-composer-plain-permissions" popover aria-label="Approval mode" style="position-anchor: --demo-composer-plain-permissions">
<div class="chat-composer-group">Approval mode</div>
<button class="popover-menu-item chat-composer-menu-option" type="button" data-permission="Ask for approval" aria-pressed="true"><span class="popover-menu-item-icon"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m12 3 8 4v5c0 5-8 9-8 9s-8-4-8-9V7l8-4Z"/><path d="m9 12 2 2 4-4"/></svg></span><span class="chat-composer-label">Ask for approval<span class="chat-composer-description">Review each action before it runs.</span></span><span data-check><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
<button class="popover-menu-item chat-composer-menu-option" type="button" data-permission="Approve for me" aria-pressed="false"><span class="popover-menu-item-icon"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m12 3 8 4v5c0 5-8 9-8 9s-8-4-8-9V7l8-4Z"/><path d="m9 12 2 2 4-4"/></svg></span><span class="chat-composer-label">Approve for me<span class="chat-composer-description">Request review for sensitive actions.</span></span><span data-check hidden><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
<button class="popover-menu-item chat-composer-menu-option chat-composer-menu-option-warning" type="button" data-permission="Full access" aria-pressed="false"><span class="popover-menu-item-icon"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m12 3 8 4v5c0 5-8 9-8 9s-8-4-8-9V7l8-4Z"/><path d="m9 12 2 2 4-4"/></svg></span><span class="chat-composer-label">Full access<span class="chat-composer-description">Allow actions without an approval prompt.</span></span><span data-check hidden><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
</div>
<div class="popover popover-menu chat-composer-menu chat-composer-menu-end" id="demo-composer-plain-settings" popover aria-label="Model and reasoning" style="position-anchor: --demo-composer-plain-settings">
<button class="popover-menu-item" type="button" popovertarget="demo-composer-plain-models"><span class="chat-composer-label">Model<span class="chat-composer-description" data-current-model>Model A</span></span><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m9 6 6 6-6 6"/></svg></button>
<div class="chat-composer-menu-row"><label for="demo-composer-plain-effort">Reasoning effort</label><span data-current-effort>Medium</span></div>
<div class="chat-composer-menu-field"><input class="range range-sm" id="demo-composer-plain-effort" type="range" min="0" max="3" step="1" value="1" aria-valuetext="Medium" data-effort /></div>
<div class="chat-composer-menu-row"><span class="chat-composer-description">Low → Maximum</span><button class="btn btn-ghost btn-xs btn-circle" type="button" aria-label="Reset reasoning effort" data-reset-effort><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M3 11a9 9 0 1 1 2.6 7.4M3 4v7h7"/></svg></button></div>
</div>
<div class="popover popover-menu chat-composer-menu chat-composer-menu-end" id="demo-composer-plain-models" popover aria-label="Choose a model" style="position-anchor: --demo-composer-plain-settings">
<div class="chat-composer-group">Model</div>
<button class="popover-menu-item chat-composer-menu-option" type="button" data-model="Model A" aria-pressed="true"><span class="chat-composer-label">Model A</span><span data-check><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
<button class="popover-menu-item chat-composer-menu-option" type="button" data-model="Model B" aria-pressed="false"><span class="chat-composer-label">Model B</span><span data-check hidden><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
<button class="popover-menu-item chat-composer-menu-option" type="button" data-model="Model C" aria-pressed="false"><span class="chat-composer-label">Model C</span><span data-check hidden><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
</div>
<div class="popover popover-menu chat-composer-menu" id="demo-composer-plain-sources" popover aria-label="Source references" style="position-anchor: --demo-composer-plain-add">
<div class="chat-composer-group">components /</div>
<button class="popover-menu-item" type="button" data-source="components/chat.css"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8Z"/><path d="M14 2v6h6M8 13h8M8 17h5"/></svg><span>chat.css</span></button>
<button class="popover-menu-item" type="button" data-source="components/chat.ts"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8Z"/><path d="M14 2v6h6M8 13h8M8 17h5"/></svg><span>chat.ts</span></button>
</div>
<div class="popover chat-composer-menu" id="demo-composer-plain-help" popover aria-label="Composer help" style="position-anchor: --demo-composer-plain-add">
<div class="popover-body">Ctrl/⌘+Enter sends. Enter adds a new line. Add files with +, change approval with the shield, and choose a model or reasoning effort on the right. These controls use local demo state; files stay in your browser.</div>
</div>
<div id="demo-composer-plain-add-tip" class="tooltip" popover="hint" role="tooltip" style="position-anchor: --demo-composer-plain-add; position-area: top">Add files and more</div>
<div id="demo-composer-plain-permissions-tip" class="tooltip" popover="hint" role="tooltip" style="position-anchor: --demo-composer-plain-permissions; position-area: top">Approval mode: Ask for approval</div>
<div id="demo-composer-plain-send-tip" class="tooltip" popover="hint" role="tooltip" style="position-anchor: --demo-composer-plain-send; position-area: top">Send · Ctrl/⌘+Enter</div>
<span class="sr-only" role="status" aria-live="polite" data-composer-status></span>
<template data-attachment-template><li class="chat-composer-attachment chat-composer-attachment-tile" data-state="ready">
<img class="chat-composer-preview" src="/duskmoon-web/core/images/data-display-after.jpg" alt="Mountain landscape attachment" data-preview />
<button class="btn btn-ghost btn-xs btn-circle chat-composer-attachment-remove" type="button" aria-label="Remove landscape.jpg" data-remove-attachment><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m6 6 12 12M6 18 18 6"/></svg></button>
</li></template>
</form>
</div>Keep the editor above one toolbar: add and approval icons on the left, model and reasoning configuration on the right, followed by a circular Send/Stop action. The configuration label truncates at narrow widths so the icon controls stay available. Menus use native Popovers anchored to their triggers; Escape and outside clicks dismiss them. Usage instructions live under + → Composer help.
This demo uses Enter for a newline and Ctrl/⌘+Enter for submission. The Waiting Queue demo above uses Enter to queue and Ctrl/⌘+Enter to steer. Core does not impose either policy. Action descriptions must match the application’s shortcuts, and IME composition must never submit a draft. Empty or whitespace-only drafts keep Send disabled without a native validation bubble. An attached file also counts as draft content. Sending switches the arrow to Stop; stopping returns to Send and preserves any newly typed draft.
Model names, reasoning levels, approval choices, and available add-menu actions come from the application. These sample choices only change local demo state. Core supplies layout and presentation without granting permissions or calling providers.
Settings Trigger Styles
Compose native buttons with .chat-composer-access (pushes following controls toward the end),
.chat-composer-model (rounded surface pill), and .chat-composer-effort (muted effort text).
Set data-active="true" on the access trigger for a warning foreground when a dangerous
permission is active. The application supplies labels and values; opening a menu or
choosing an item does not grant permission or change a setting in Core.
Public Settings Triggers
<form class="chat-composer">
<textarea class="chat-composer-input" aria-label="Message" placeholder="Ask a question"></textarea>
<div class="chat-composer-actions">
<button class="btn btn-ghost btn-sm chat-composer-access" type="button" data-active="true" popovertarget="demo-chat-access" style="anchor-name: --demo-chat-access">Full access</button>
<button class="btn btn-ghost btn-sm chat-composer-config chat-composer-model" type="button" popovertarget="demo-chat-model" style="anchor-name: --demo-chat-model">
<span class="chat-composer-label">Model A <span class="chat-composer-effort">Medium</span></span><span aria-hidden="true">⌄</span>
</button>
<button class="btn btn-primary btn-sm" type="button">Send</button>
</div>
</form>
<div class="popover popover-menu chat-composer-menu" id="demo-chat-access" popover style="position-anchor: --demo-chat-access" aria-label="Access choices">
<button class="popover-menu-item chat-composer-menu-option" type="button" aria-pressed="false"><span class="chat-composer-label">Ask first<span class="chat-composer-description">Review actions before they run.</span></span></button>
<button class="popover-menu-item chat-composer-menu-option chat-composer-menu-option-warning" type="button" aria-pressed="true"><span class="chat-composer-label">Full access<span class="chat-composer-description">Allow actions without individual approval.</span></span><span aria-hidden="true">✓</span></button>
</div>
<div class="popover popover-menu chat-composer-menu chat-composer-menu-end" id="demo-chat-model" popover style="position-anchor: --demo-chat-model" aria-label="Model and effort">
<button class="popover-menu-item" type="button">Model A</button>
<div class="chat-composer-menu-row"><label for="demo-chat-effort">Effort</label><button class="btn btn-ghost btn-xs" type="button">Reset</button></div>
<div class="chat-composer-menu-field"><input class="range range-sm" id="demo-chat-effort" type="range" min="0" max="3" value="1" /></div>
</div>Use the same triggers in .chat-composer-toolbar-compact; the model label truncates
via .chat-composer-config and .chat-composer-label. Native Popovers retain their
anchor positioning, Escape dismissal, and keyboard focus behavior. The host owns
choice selection, nested model menus, slider commits, reset behavior, and announcements.
Attached Context Bar
Place .chat-composer-context as the first direct child of .chat-composer,
above the editor. It shares the composer’s surface and top corners; its inset follows
--chat-composer-inset (1rem by default, 0.625rem with .chat-composer-compact).
The compact shell also uses the medium radius. .chat-composer-ghost retains its
transparent border, including when combined with compact.
Composer With Attached Context
<form class="chat-composer chat-composer-compact chat-composer-ghost">
<div class="chat-composer-context" role="group" aria-label="Session context">
<span class="chat-composer-context-item" title="workspace/project/src">
<svg class="chat-composer-context-icon" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M1 3h5l2 2h7v9H1z" /></svg>
<span class="chat-composer-context-label">workspace/project/src</span>
</span>
<div class="chat-composer-context-end">
<span class="chat-composer-context-item"><span class="chat-composer-context-label">Plan mode</span><button class="btn btn-ghost btn-xs" type="button" aria-label="Clear plan mode">×</button></span>
<span class="chat-composer-connection" data-state="connected" role="status">Connected</span>
</div>
</div>
<textarea class="chat-composer-input" aria-label="Contextual message" placeholder="Continue in this workspace"></textarea>
<div class="chat-composer-actions"><button class="btn btn-primary btn-sm" type="button">Send</button></div>
</form>Items use .chat-composer-context-item, optional .chat-composer-context-icon, and
.chat-composer-context-label for truncation. Retain the full value in the DOM and
provide a title or another accessible way to inspect truncated values. Put trailing
items in .chat-composer-context-end; both groups wrap at narrow widths. Optional
actions are native labelled buttons. .chat-composer-connection[data-state] supports
connected, connecting, and disconnected; always include a visible text label,
and use role="status" for host-driven polite updates. Core never changes connection state.
Attachment Previews
Composer With An Attachment
<div class="chat-input-area" style="width: min(48rem, 100%)">
<form class="chat-composer chat-composer-ghost" data-compact-composer="composer-files">
<ul class="chat-composer-attachments chat-composer-thumbnails" role="list" aria-label="Draft attachments" data-attachments>
<li class="chat-composer-attachment chat-composer-attachment-tile" data-state="ready">
<img class="chat-composer-preview" src="/duskmoon-web/core/images/data-display-after.jpg" alt="Mountain landscape attachment" data-preview />
<button class="btn btn-ghost btn-xs btn-circle chat-composer-attachment-remove" type="button" aria-label="Remove landscape.jpg" data-remove-attachment><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m6 6 12 12M6 18 18 6"/></svg></button>
</li>
</ul>
<label class="sr-only" for="demo-composer-files-message">Message</label>
<textarea class="chat-composer-input" id="demo-composer-files-message" rows="1" placeholder="Describe the next change…"></textarea>
<input type="file" multiple hidden aria-label="Attach files" data-file-input />
<div class="chat-composer-toolbar chat-composer-toolbar-compact">
<button class="btn btn-ghost btn-sm btn-circle" type="button" aria-label="Add files and more" popovertarget="demo-composer-files-add" interestfor="demo-composer-files-add-tip" aria-describedby="demo-composer-files-add-tip" style="anchor-name: --demo-composer-files-add"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M12 5v14M5 12h14"/></svg></button>
<button class="btn btn-ghost btn-sm btn-circle" type="button" aria-label="Approval mode: Ask for approval" data-permission-trigger popovertarget="demo-composer-files-permissions" interestfor="demo-composer-files-permissions-tip" aria-describedby="demo-composer-files-permissions-tip" style="anchor-name: --demo-composer-files-permissions"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m12 3 8 4v5c0 5-8 9-8 9s-8-4-8-9V7l8-4Z"/><path d="m9 12 2 2 4-4"/></svg></button>
<div class="chat-composer-actions">
<button class="btn btn-ghost btn-sm chat-composer-config" type="button" aria-label="Model and reasoning: Model A, Medium" data-config-trigger popovertarget="demo-composer-files-settings" style="anchor-name: --demo-composer-files-settings"><span class="chat-composer-label" data-config-label>Model A · Medium</span><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m6 9 6 6 6-6"/></svg></button>
<button class="btn btn-primary btn-sm btn-circle" type="submit" aria-label="Send message" aria-keyshortcuts="Control+Enter Meta+Enter" data-send interestfor="demo-composer-files-send-tip" aria-describedby="demo-composer-files-send-tip" style="anchor-name: --demo-composer-files-send" disabled><span data-send-icon><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M12 19V5m-7 7 7-7 7 7"/></svg></span><span data-stop-icon hidden><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><rect x="6" y="6" width="12" height="12" rx="1" fill="currentColor" stroke="none"/></svg></span></button>
</div>
</div>
<div class="popover popover-menu chat-composer-menu" id="demo-composer-files-add" popover aria-label="Add files and more" style="position-anchor: --demo-composer-files-add">
<div class="chat-composer-group">Add</div>
<button class="popover-menu-item" type="button" data-attach-files><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m8 12 7-7a3 3 0 0 1 4 4L9 19a5 5 0 0 1-7-7L12 2m-7 12 9-9"/></svg><span>Files</span></button>
<button class="popover-menu-item" type="button" popovertarget="demo-composer-files-sources"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8Z"/><path d="M14 2v6h6M8 13h8M8 17h5"/></svg><span>Source reference</span></button>
<button class="popover-menu-item" type="button" popovertarget="demo-composer-files-help"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><circle cx="12" cy="12" r="9"/><path d="M12 11v6M12 7h.01"/></svg><span>Composer help</span></button>
</div>
<div class="popover popover-menu chat-composer-menu" id="demo-composer-files-permissions" popover aria-label="Approval mode" style="position-anchor: --demo-composer-files-permissions">
<div class="chat-composer-group">Approval mode</div>
<button class="popover-menu-item chat-composer-menu-option" type="button" data-permission="Ask for approval" aria-pressed="true"><span class="popover-menu-item-icon"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m12 3 8 4v5c0 5-8 9-8 9s-8-4-8-9V7l8-4Z"/><path d="m9 12 2 2 4-4"/></svg></span><span class="chat-composer-label">Ask for approval<span class="chat-composer-description">Review each action before it runs.</span></span><span data-check><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
<button class="popover-menu-item chat-composer-menu-option" type="button" data-permission="Approve for me" aria-pressed="false"><span class="popover-menu-item-icon"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m12 3 8 4v5c0 5-8 9-8 9s-8-4-8-9V7l8-4Z"/><path d="m9 12 2 2 4-4"/></svg></span><span class="chat-composer-label">Approve for me<span class="chat-composer-description">Request review for sensitive actions.</span></span><span data-check hidden><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
<button class="popover-menu-item chat-composer-menu-option chat-composer-menu-option-warning" type="button" data-permission="Full access" aria-pressed="false"><span class="popover-menu-item-icon"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m12 3 8 4v5c0 5-8 9-8 9s-8-4-8-9V7l8-4Z"/><path d="m9 12 2 2 4-4"/></svg></span><span class="chat-composer-label">Full access<span class="chat-composer-description">Allow actions without an approval prompt.</span></span><span data-check hidden><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
</div>
<div class="popover popover-menu chat-composer-menu chat-composer-menu-end" id="demo-composer-files-settings" popover aria-label="Model and reasoning" style="position-anchor: --demo-composer-files-settings">
<button class="popover-menu-item" type="button" popovertarget="demo-composer-files-models"><span class="chat-composer-label">Model<span class="chat-composer-description" data-current-model>Model A</span></span><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m9 6 6 6-6 6"/></svg></button>
<div class="chat-composer-menu-row"><label for="demo-composer-files-effort">Reasoning effort</label><span data-current-effort>Medium</span></div>
<div class="chat-composer-menu-field"><input class="range range-sm" id="demo-composer-files-effort" type="range" min="0" max="3" step="1" value="1" aria-valuetext="Medium" data-effort /></div>
<div class="chat-composer-menu-row"><span class="chat-composer-description">Low → Maximum</span><button class="btn btn-ghost btn-xs btn-circle" type="button" aria-label="Reset reasoning effort" data-reset-effort><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M3 11a9 9 0 1 1 2.6 7.4M3 4v7h7"/></svg></button></div>
</div>
<div class="popover popover-menu chat-composer-menu chat-composer-menu-end" id="demo-composer-files-models" popover aria-label="Choose a model" style="position-anchor: --demo-composer-files-settings">
<div class="chat-composer-group">Model</div>
<button class="popover-menu-item chat-composer-menu-option" type="button" data-model="Model A" aria-pressed="true"><span class="chat-composer-label">Model A</span><span data-check><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
<button class="popover-menu-item chat-composer-menu-option" type="button" data-model="Model B" aria-pressed="false"><span class="chat-composer-label">Model B</span><span data-check hidden><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
<button class="popover-menu-item chat-composer-menu-option" type="button" data-model="Model C" aria-pressed="false"><span class="chat-composer-label">Model C</span><span data-check hidden><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 4 4L19 6"/></svg></span></button>
</div>
<div class="popover popover-menu chat-composer-menu" id="demo-composer-files-sources" popover aria-label="Source references" style="position-anchor: --demo-composer-files-add">
<div class="chat-composer-group">components /</div>
<button class="popover-menu-item" type="button" data-source="components/chat.css"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8Z"/><path d="M14 2v6h6M8 13h8M8 17h5"/></svg><span>chat.css</span></button>
<button class="popover-menu-item" type="button" data-source="components/chat.ts"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8Z"/><path d="M14 2v6h6M8 13h8M8 17h5"/></svg><span>chat.ts</span></button>
</div>
<div class="popover chat-composer-menu" id="demo-composer-files-help" popover aria-label="Composer help" style="position-anchor: --demo-composer-files-add">
<div class="popover-body">Ctrl/⌘+Enter sends. Enter adds a new line. Add files with +, change approval with the shield, and choose a model or reasoning effort on the right. These controls use local demo state; files stay in your browser.</div>
</div>
<div id="demo-composer-files-add-tip" class="tooltip" popover="hint" role="tooltip" style="position-anchor: --demo-composer-files-add; position-area: top">Add files and more</div>
<div id="demo-composer-files-permissions-tip" class="tooltip" popover="hint" role="tooltip" style="position-anchor: --demo-composer-files-permissions; position-area: top">Approval mode: Ask for approval</div>
<div id="demo-composer-files-send-tip" class="tooltip" popover="hint" role="tooltip" style="position-anchor: --demo-composer-files-send; position-area: top">Send · Ctrl/⌘+Enter</div>
<span class="sr-only" role="status" aria-live="polite" data-composer-status></span>
<template data-attachment-template><li class="chat-composer-attachment chat-composer-attachment-tile" data-state="ready">
<img class="chat-composer-preview" src="/duskmoon-web/core/images/data-display-after.jpg" alt="Mountain landscape attachment" data-preview />
<button class="btn btn-ghost btn-xs btn-circle chat-composer-attachment-remove" type="button" aria-label="Remove landscape.jpg" data-remove-attachment><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m6 6 12 12M6 18 18 6"/></svg></button>
</li></template>
</form>
</div>Selected images appear as thumbnail tiles above the editor. Use + → Files to preview local files and the tile’s icon to remove one. The strip scrolls horizontally when full; it does not displace the toolbar or impose an editor height. The sample landscape uses the documentation site’s existing local image asset.
The application supplies file policy, picker/paste/drop intake, upload progress,
retry, cancellation, and removal. File rows still support validating, uploading,
ready, error, and cancelled states; show the states relevant to the current
attachment. Use the existing .progress component for an actual upload value.
A restored filename is not proof that an upload is ready. Keep pending admission
separate from attachment progress and announce relevant updates through one polite status region.
Native Suggestion Surface
The compact demo’s + → Source reference opens a native Popover and inserts a
sample source name into the draft. Real source lookup and directory navigation
belong to the host. Use .chat-composer-completions for editor completion results,
with .chat-composer-option, .chat-composer-group, and .chat-composer-breadcrumb
for options and navigation. Core supplies viewport bounds and anchor flip fallbacks.
For a real editor completion, retain native textarea semantics and use
aria-haspopup="listbox", aria-controls, and aria-activedescendant while the
listbox is open. Keep the active option’s ID and aria-selected synchronized,
ignore unavailable rows, and consume suggestion-selection keys before submission
keys. Do not add role="combobox" to a textarea. Loading, empty, or failed provider
results can use .chat-composer-status; do not expose loading text as a selectable result.
Pending Admission And Queue Mutations
Apply queue row data-state="editing", "stale", "conflict", or "consuming"
only when the application’s current state calls for it. The interactive Waiting
Queue above shows the ordinary queue flow.
An unknown submission outcome is separate from rejection. Do not automatically
resend it, clear its snapshot, or invent a confirmed queue item. Keep the editor
available while checking the earlier submission. Use .chat-composer-status
with data-state="pending", "unknown", or "error" and a relevant status or
recovery action. Connect validation text to the editor with aria-describedby
and expose aria-invalid="true" when the draft is invalid. Server admission and
queue mutations remain authoritative.
Compatibility And Delivery
The base composer parts and state attributes shipped in Core 1.21.0. The compact
toolbar, configuration menu, thumbnail modifiers, and content-sized textarea shown
here are development changes and require the matching Core build; they are not
in the published 1.21.0 package.
Existing class names remain supported. The toolbar wraps by default; the compact
modifier opts into a single row. Textarea autosizing uses field-sizing: content;
applications targeting browsers without it need their own textarea height handler.
All parts ship through the aggregate CSS, component CSS, generated component ESM
stylesheet, and standalone plugin outputs. With the package’s token-only
@duskmoon-dev/core/plugin entry, also import Core CSS as before. The generated
@duskmoon-dev/core/components/chat module exports CSS text and a nullable
constructable stylesheet, so server-side consumers can import it without a
browser CSSStyleSheet implementation. No editor runtime is included in Core.
Scroll-Driven Indicators
.chat-scroll hoists named view timelines with timeline-scope (--chat-1 … --chat-24). Pair agent / assistant rows only (.chat-start) with matching indicators: .chat[data-chat-tl="N"] declares view-timeline-name, and .chat-scroll-indicator[data-chat-tl="N"] binds animation-timeline + animation-range: entry 0% exit 100%.
User turns stay in the transcript but do not get ticks. Click an indicator to jump to that agent response inside .chat-scroll — use button + data-chat-target (not bare href="#…"), otherwise the document will scroll. Docs demos wire the click handler; app code should call scroller.scrollTo(...) the same way.
The dashes keep their visual spacing, while adjacent buttons have continuous hover and click areas. Moving through the space between dashes still selects an indicator.
Requires a browser that supports Scroll-Driven Animations. Unsupported browsers still scroll smoothly; indicators stay in the idle style.
Keep .chat-input-area outside .chat-scroll so the composer stays visible while
browsing replies. Connect the Send button to your application’s message handler.
Scroll-Driven Chat Indicators
<div id="demo-chat-scroll-layout" style="width: min(48rem, 100%); display: flex; flex-direction: column; gap: 1rem;">
<div id="demo-chat-scroll" class="chat-scroll" style="height: 22rem;">
<div class="chat-scroll-track" aria-label="Assistant replies">
<button type="button" class="chat-scroll-indicator" data-chat-tl="1" data-chat-target="demo-chat-agent-1" aria-label="Jump to assistant reply 1"></button>
<button type="button" class="chat-scroll-indicator" data-chat-tl="2" data-chat-target="demo-chat-agent-2" aria-label="Jump to assistant reply 2"></button>
<button type="button" class="chat-scroll-indicator" data-chat-tl="3" data-chat-target="demo-chat-agent-3" aria-label="Jump to assistant reply 3"></button>
<button type="button" class="chat-scroll-indicator" data-chat-tl="4" data-chat-target="demo-chat-agent-4" aria-label="Jump to assistant reply 4"></button>
<button type="button" class="chat-scroll-indicator" data-chat-tl="5" data-chat-target="demo-chat-agent-5" aria-label="Jump to assistant reply 5"></button>
<button type="button" class="chat-scroll-indicator" data-chat-tl="6" data-chat-target="demo-chat-agent-6" aria-label="Jump to assistant reply 6"></button>
<button type="button" class="chat-scroll-indicator" data-chat-tl="7" data-chat-target="demo-chat-agent-7" aria-label="Jump to assistant reply 7"></button>
<button type="button" class="chat-scroll-indicator" data-chat-tl="8" data-chat-target="demo-chat-agent-8" aria-label="Jump to assistant reply 8"></button>
</div>
<div class="chat-scroll-body">
<div id="demo-chat-agent-1" class="chat chat-start chat-agent" data-chat-tl="1">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-primary">AI</div>
</div>
<div class="chat-header">Agent - 2:00 PM</div>
<div class="chat-content">Welcome back. The left ticks mark each assistant reply — scroll or click a tick to jump to that response.</div>
</div>
<div class="chat chat-end">
<div class="chat-avatar">
<div class="avatar avatar-sm">GA</div>
</div>
<div class="chat-header">You - 2:01 PM</div>
<div class="chat-bubble chat-bubble-primary">Can we use Scroll-Driven Animations for the rail?</div>
</div>
<div id="demo-chat-agent-2" class="chat chat-start chat-agent" data-chat-tl="2">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-primary">AI</div>
</div>
<div class="chat-header">Agent - 2:01 PM</div>
<div class="chat-content">Yes. Each agent row exposes a named view-timeline. The parent raises timeline-scope so indicators can bind animation-timeline without living in the same subtree.</div>
</div>
<div class="chat chat-end">
<div class="chat-avatar">
<div class="avatar avatar-sm">GA</div>
</div>
<div class="chat-header">You - 2:02 PM</div>
<div class="chat-bubble chat-bubble-primary">Should user messages also get ticks?</div>
</div>
<div id="demo-chat-agent-3" class="chat chat-start chat-agent" data-chat-tl="3">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-primary">AI</div>
</div>
<div class="chat-header">Agent - 2:02 PM</div>
<div class="chat-content">No. Ticks only navigate to the start of an agent response. User turns stay in the transcript but are skipped by the rail.</div>
</div>
<div class="chat chat-end">
<div class="chat-avatar">
<div class="avatar avatar-sm">GA</div>
</div>
<div class="chat-header">You - 2:03 PM</div>
<div class="chat-bubble chat-bubble-primary">What about animation-range?</div>
</div>
<div id="demo-chat-agent-4" class="chat chat-start chat-agent" data-chat-tl="4">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-primary">AI</div>
</div>
<div class="chat-header">Agent - 2:03 PM</div>
<div class="chat-content">Indicators use entry 0% exit 100%, so they brighten while the paired assistant message is in view and fade as it leaves.</div>
</div>
<div class="chat chat-end">
<div class="chat-avatar">
<div class="avatar avatar-sm">GA</div>
</div>
<div class="chat-header">You - 2:04 PM</div>
<div class="chat-bubble chat-bubble-primary">Why not use href hash links for the ticks?</div>
</div>
<div id="demo-chat-agent-5" class="chat chat-start chat-agent" data-chat-tl="5">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-primary">AI</div>
</div>
<div class="chat-header">Agent - 2:04 PM</div>
<div class="chat-content">Hash navigation scrolls the document. For an overflow panel, use a button with data-chat-target and scroll the .chat-scroll container itself.</div>
</div>
<div class="chat chat-end">
<div class="chat-avatar">
<div class="avatar avatar-sm">GA</div>
</div>
<div class="chat-header">You - 2:05 PM</div>
<div class="chat-bubble chat-bubble-primary">Can clicks land exactly on the agent row start?</div>
</div>
<div id="demo-chat-agent-6" class="chat chat-start chat-agent" data-chat-tl="6">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-primary">AI</div>
</div>
<div class="chat-header">Agent - 2:05 PM</div>
<div class="chat-content">Yes. The handler computes the target offset inside the scroller and calls scrollTo with smooth behavior, aligning to the agent row top (plus scroll-margin).</div>
</div>
<div class="chat chat-end">
<div class="chat-avatar">
<div class="avatar avatar-sm">GA</div>
</div>
<div class="chat-header">You - 2:06 PM</div>
<div class="chat-bubble chat-bubble-primary">Add one more long answer so the list actually overflows.</div>
</div>
<div id="demo-chat-agent-7" class="chat chat-start chat-agent" data-chat-tl="7">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-primary">AI</div>
</div>
<div class="chat-header">Agent - 2:06 PM</div>
<div class="chat-content">Here is a denser turn for scrolling practice: timeline-scope lifts --chat-N names, view-timeline-name is set on each agent .chat, and indicators stay sticky in .chat-scroll-track while .chat-scroll-body carries the messages.</div>
</div>
<div class="chat chat-end">
<div class="chat-avatar">
<div class="avatar avatar-sm">GA</div>
</div>
<div class="chat-header">You - 2:07 PM</div>
<div class="chat-bubble chat-bubble-primary">Great — last tick should jump to that reply.</div>
</div>
<div id="demo-chat-agent-8" class="chat chat-start chat-agent" data-chat-tl="8">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-primary">AI</div>
</div>
<div class="chat-header">Agent - 2:07 PM</div>
<div class="chat-content">Done. Click the last dash to return to this agent response start without moving the page behind the panel.</div>
</div>
</div>
</div>
<div class="chat-input-area">
<div class="chat-composer chat-composer-ghost">
<label class="sr-only" for="demo-chat-scroll-message">Message</label>
<textarea class="chat-composer-input" id="demo-chat-scroll-message" name="message" rows="1" placeholder="Message the agent…"></textarea>
<div class="chat-composer-toolbar chat-composer-toolbar-compact">
<div class="chat-composer-actions">
<button class="btn btn-primary btn-sm btn-circle" type="button" aria-label="Send message" disabled>
<svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m5 12 7-7 7 7M12 19V5"/></svg>
</button>
</div>
</div>
</div>
</div>
</div>Bubble Variants
User bubble color variants use soft container tones by default. Add .chat-bubble-filled when a saturated bubble is needed.
Bubble Colors
<div id="demo-chat-colors" style="width: min(42rem, 100%); display: flex; flex-direction: column; gap: 0.75rem;">
<div class="chat chat-end">
<div class="chat-bubble">Default bubble</div>
</div>
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-primary">Primary bubble</div>
</div>
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-secondary">Secondary bubble</div>
</div>
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-tertiary">Tertiary bubble</div>
</div>
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-info">Info bubble</div>
</div>
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-success">Success bubble</div>
</div>
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-warning">Warning bubble</div>
</div>
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-error">Error bubble</div>
</div>
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-primary chat-bubble-filled">Filled primary bubble</div>
</div>
</div>Right-To-Left Chat
Set dir="rtl" on the transcript. Agent rows start on the right and user bubbles move to the left; optional avatars follow the same direction.
RTL User And Agent Alignment
<div id="demo-chat-rtl" dir="rtl" lang="ar" style="width: min(42rem, 100%); display: flex; flex-direction: column; gap: 1rem;">
<div class="chat chat-start chat-agent">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-primary">AI</div>
</div>
<div class="chat-header">المساعد</div>
<div class="chat-content">كيف يمكنني مساعدتك اليوم؟</div>
</div>
<div class="chat chat-end">
<div class="chat-avatar">
<div class="avatar avatar-sm">GA</div>
</div>
<div class="chat-header">أنت</div>
<div class="chat-bubble chat-bubble-primary">أرني مثالاً للمحادثة.</div>
</div>
</div>Bubble Sizes
Use user bubble size modifiers for dense history views or larger conversational layouts.
Bubble Sizes
<div id="demo-chat-sizes" style="width: min(42rem, 100%); display: flex; flex-direction: column; gap: 0.75rem;">
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-xs">Extra small transcript bubble</div>
</div>
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-sm">Small dense chat bubble</div>
</div>
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-md">Medium default chat bubble</div>
</div>
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-lg">Large accessible chat bubble</div>
</div>
</div>LLM Chat
Put reasoning and tool calls in an agent row, optionally grouping them in .chat-work-body. Streaming tool calls may nest inside .chat-reasoning-body. Put the final answer in a separate .chat-content block so closing work records does not hide it.
Reasoning, Tool Call, and Streaming
Working · 2 tool calls · 0 failed
Thinking (3s)
get_weather Running...
{"city":"Tokyo"}
get_weather Done
{"city":"Tokyo"}
{"temperature":"18 C","condition":"cloudy"}
<div id="demo-llm-chat" style="width: min(48rem, 100%); display: flex; flex-direction: column; gap: 1rem;">
<div class="chat chat-start chat-agent" aria-live="polite">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-info">AI</div>
</div>
<div class="chat-header">Agent - 2:18 PM</div>
<details class="chat-work" open>
<summary class="chat-work-summary">Working · 2 tool calls · 0 failed</summary>
<div class="chat-work-body">
<details class="chat-reasoning" open>
<summary>Thinking (3s)</summary>
<div class="chat-reasoning-body">
<div>I should call the weather tool, then summarize the result in one sentence.</div>
<details class="chat-tool chat-tool-running" open>
<summary class="chat-tool-header">
<span>get_weather</span>
<span class="chat-tool-status">Running...</span>
</summary>
<div class="chat-tool-call">
<div class="code-block code-block-compact">
<div class="code-header">
<span class="code-title">Call</span>
<span class="code-language">json</span>
</div>
<div class="code-content">
<pre><code>{"city":"Tokyo"}</code></pre>
</div>
</div>
</div>
</details>
<div>Tool returned cloudy at 18 C. Drafting the final answer.</div>
</div>
</details>
<details class="chat-tool chat-tool-success" open>
<summary class="chat-tool-header">
<span>get_weather</span>
<span class="chat-tool-status">Done</span>
</summary>
<div class="chat-tool-call">
<div class="code-block code-block-compact">
<div class="code-header">
<span class="code-title">Call</span>
<span class="code-language">json</span>
</div>
<div class="code-content">
<pre><code>{"city":"Tokyo"}</code></pre>
</div>
</div>
</div>
<div class="chat-tool-result">
<div class="code-block code-block-compact">
<div class="code-header">
<span class="code-title">Result</span>
<span class="code-language">json</span>
</div>
<div class="code-content">
<pre><code>{"temperature":"18 C","condition":"cloudy"}</code></pre>
</div>
</div>
</div>
</details>
</div>
</details>
<div class="chat-content chat-streaming">It is 18 C and cloudy in Tokyo right now.</div>
<div class="chat-footer">Streaming</div>
</div>
</div>Live States
Use .chat-typing inside .chat-content while waiting for the first token. Add .chat-streaming to .chat-content while message text is still arriving. The existing .chat-bubble-streaming modifier remains a compatibility alias.
Typing and Streaming
<div id="demo-chat-live-states" style="width: min(42rem, 100%); display: flex; flex-direction: column; gap: 1rem;">
<div class="chat chat-start chat-agent" aria-live="polite">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-secondary">AI</div>
</div>
<div class="chat-content" aria-label="Agent is typing">
<span class="chat-typing"></span>
</div>
</div>
<div class="chat chat-start chat-agent" aria-live="polite">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-secondary">AI</div>
</div>
<div class="chat-content chat-streaming">Generating a response</div>
</div>
</div>Message Status And Actions
Place .chat-status below agent content or a user bubble to show generation state, token speed, and token count. Group each metric in .chat-status-item and emphasize its number with .chat-status-value. Metrics wrap on narrow screens and use tabular numerals.
Use .chat-actions for a row of existing buttons. Add .chat-actions-hover to reveal the actions when the message is hovered or contains keyboard focus. Actions remain visible on devices without hover. Omit the modifier when actions should always be visible.
Use square icon buttons with descriptive aria-label attributes. Pair each button with a native Tooltip through interestfor and aria-describedby to show its action name.
The application supplies status text and metric values and handles each action. The buttons below demonstrate styling; they do not edit, retry, copy, or stop a response.
Token Metrics and Message Actions
<div id="demo-chat-status-actions" style="width: min(42rem, 100%); display: flex; flex-direction: column; gap: 1rem;">
<div class="chat chat-end">
<div class="chat-avatar">
<div class="avatar avatar-sm">GA</div>
</div>
<div class="chat-header">You</div>
<div class="chat-bubble chat-bubble-primary">Summarize the deployment checks.</div>
<div class="chat-status">
<span class="chat-status-item">Sent</span>
<span class="chat-status-item"><span class="chat-status-value">12</span> tokens</span>
</div>
<div class="chat-actions chat-actions-hover">
<button type="button" class="btn btn-ghost btn-xs btn-square" aria-label="Edit your deployment question" interestfor="demo-chat-edit-tip" aria-describedby="demo-chat-edit-tip" style="anchor-name: --demo-chat-edit">
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="m16 3 5 5-12 12H4v-5Z"/><path d="m14 5 5 5"/></svg>
</button>
<div id="demo-chat-edit-tip" popover="hint" class="tooltip" role="tooltip" style="position-anchor: --demo-chat-edit">Edit</div>
</div>
</div>
<div class="chat chat-start chat-agent">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-secondary">AI</div>
</div>
<div class="chat-header">Agent · Generating</div>
<div class="chat-content chat-streaming">Checking the build and smoke-test results</div>
<div class="chat-status">
<span class="chat-status-item">Generating</span>
<span class="chat-status-item"><span class="chat-status-value">42</span> token/s</span>
<span class="chat-status-item"><span class="chat-status-value">256</span> tokens</span>
</div>
<div class="chat-actions">
<button type="button" class="btn btn-ghost btn-xs btn-square" aria-label="Stop generating the deployment summary" interestfor="demo-chat-stop-tip" aria-describedby="demo-chat-stop-tip" style="anchor-name: --demo-chat-stop">
<svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" focusable="false"><rect x="5" y="5" width="14" height="14" rx="2"/></svg>
</button>
<div id="demo-chat-stop-tip" popover="hint" class="tooltip" role="tooltip" style="position-anchor: --demo-chat-stop">Stop</div>
</div>
</div>
<div class="chat chat-start chat-agent">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-primary">AI</div>
</div>
<div class="chat-header">Agent · Completed</div>
<div class="chat-content">The build completed and all deployment smoke tests passed.</div>
<div class="chat-status">
<span class="chat-status-item">Completed</span>
<span class="chat-status-item"><span class="chat-status-value">42</span> token/s</span>
<span class="chat-status-item"><span class="chat-status-value">1,248</span> tokens</span>
</div>
<div class="chat-actions chat-actions-hover">
<button type="button" class="btn btn-ghost btn-xs btn-square" aria-label="Retry the deployment summary" interestfor="demo-chat-retry-tip" aria-describedby="demo-chat-retry-tip" style="anchor-name: --demo-chat-retry">
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><path d="M3 11a9 9 0 1 1 2.6 7.4"/><path d="M3 4v7h7"/></svg>
</button>
<div id="demo-chat-retry-tip" popover="hint" class="tooltip" role="tooltip" style="position-anchor: --demo-chat-retry">Retry</div>
<button type="button" class="btn btn-ghost btn-xs btn-square" aria-label="Copy the deployment summary" interestfor="demo-chat-copy-tip" aria-describedby="demo-chat-copy-tip" style="anchor-name: --demo-chat-copy">
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><rect x="8" y="8" width="13" height="13" rx="2"/><path d="M16 8V5a2 2 0 0 0-2-2H5a2 2 0 0 0-2 2v9a2 2 0 0 0 2 2h3"/></svg>
</button>
<div id="demo-chat-copy-tip" popover="hint" class="tooltip" role="tooltip" style="position-anchor: --demo-chat-copy">Copy</div>
</div>
</div>
</div>Tool Status
Tool blocks use status modifiers so state is visible in both color and text.
Tool Statuses
search_docs Pending
run_query Running...
get_profile Done
deploy_preview Failed
<div id="demo-chat-tool-statuses" style="width: min(42rem, 100%); display: flex; flex-direction: column; gap: 0.75rem;">
<details class="chat-tool chat-tool-pending" open>
<summary class="chat-tool-header">
<span>search_docs</span>
<span class="chat-tool-status">Pending</span>
</summary>
</details>
<details class="chat-tool chat-tool-running" open>
<summary class="chat-tool-header">
<span>run_query</span>
<span class="chat-tool-status">Running...</span>
</summary>
</details>
<details class="chat-tool chat-tool-success" open>
<summary class="chat-tool-header">
<span>get_profile</span>
<span class="chat-tool-status">Done</span>
</summary>
</details>
<details class="chat-tool chat-tool-error" open>
<summary class="chat-tool-header">
<span>deploy_preview</span>
<span class="chat-tool-status">Failed</span>
</summary>
</details>
</div>Timeline Approval Requests
Use .chat-approval inside a .chat-agent .chat-content timeline, alongside .chat-tool.
The host supplies command, file, and reason children in .chat-approval-details, and
sets data-state to pending, approved, approved-for-session, declined, expired,
or answer-elsewhere. These are presentation states; Core never resolves a request.
Timeline Approval Request
Run checks
Allow this command?
Awaiting approvalnpm testRuns the project's test suite in the workspace.
<div class="chat chat-start chat-agent">
<div class="chat-content">
<details class="chat-tool" open><summary class="chat-tool-header">Run checks</summary><div class="chat-tool-call">npm test</div></details>
<section class="chat-approval" data-state="pending" aria-labelledby="demo-chat-approval-title">
<div class="chat-approval-header"><h3 class="chat-approval-title" id="demo-chat-approval-title">Allow this command?</h3><span class="chat-approval-status" role="status">Awaiting approval</span></div>
<div class="chat-approval-details"><pre tabindex="0" role="region" aria-label="Requested command"><code>npm test</code></pre><p>Runs the project's test suite in the workspace.</p></div>
<div class="chat-approval-actions">
<button class="btn btn-primary btn-sm" type="button">Approve</button>
<button class="btn btn-outlined btn-sm" type="button">Approve for session</button>
<button class="btn btn-error btn-sm" type="button">Decline</button>
</div>
</section>
</div>
</div>.chat-approval-header contains the title and a text status. .chat-approval-actions
keeps host DOM order and wraps responsively; reuse .btn-primary for the primary
decision and .btn-error for a danger action. While awaiting a decision acknowledgment,
set aria-busy="true" on the request and native disabled on every decision button.
An attribute alone does not disable interaction. Keep data-state="pending" until
the host confirms the outcome. The following example deliberately has disabled actions.
Decision Awaiting Host Confirmation
<section class="chat-approval" data-state="pending" aria-busy="true" aria-label="Test command approval">
<div class="chat-approval-header"><strong class="chat-approval-title">Run npm test</strong><span class="chat-approval-status" role="status">Sending decision…</span></div>
<div class="chat-approval-actions"><button class="btn btn-primary btn-sm" type="button" disabled>Approve</button><button class="btn btn-error btn-sm" type="button" disabled>Decline</button></div>
</section>Resolved and unanswerable examples retain request details in the timeline. Omit actions
when no decision is available. answer-elsewhere also hides an accidentally retained
action group; provide an explanation of where the user must answer.
Approval Outcomes
npm testThe host accepted this command.
npm testThe host accepted this permission for this session.
npm testThe command will not run.
npm testThis request is no longer valid.
npm testRespond in the terminal where this command was requested.
<section class="chat-approval" data-state="approved" aria-label="Approved request">
<div class="chat-approval-header"><strong class="chat-approval-title">Run npm test</strong><span class="chat-approval-status" role="status">Approved</span></div>
<div class="chat-approval-details"><code>npm test</code><p>The host accepted this command.</p></div>
</section>
<section class="chat-approval" data-state="approved-for-session" aria-label="Approved for session request">
<div class="chat-approval-header"><strong class="chat-approval-title">Run npm test</strong><span class="chat-approval-status" role="status">Approved for session</span></div>
<div class="chat-approval-details"><code>npm test</code><p>The host accepted this permission for this session.</p></div>
</section>
<section class="chat-approval" data-state="declined" aria-label="Declined request">
<div class="chat-approval-header"><strong class="chat-approval-title">Run npm test</strong><span class="chat-approval-status" role="status">Declined</span></div>
<div class="chat-approval-details"><code>npm test</code><p>The command will not run.</p></div>
</section>
<section class="chat-approval" data-state="expired" aria-label="Expired request">
<div class="chat-approval-header"><strong class="chat-approval-title">Run npm test</strong><span class="chat-approval-status" role="status">Expired</span></div>
<div class="chat-approval-details"><code>npm test</code><p>This request is no longer valid.</p></div>
</section>
<section class="chat-approval" data-state="answer-elsewhere" aria-label="Answer elsewhere request">
<div class="chat-approval-header"><strong class="chat-approval-title">Run npm test</strong><span class="chat-approval-status" role="status">Answer elsewhere</span></div>
<div class="chat-approval-details"><code>npm test</code><p>Respond in the terminal where this command was requested.</p></div>
</section>Give horizontally scrollable command blocks tabindex="0", role="region", and an accessible name so keyboard users can inspect long commands.
The host owns callbacks, pending enforcement, polite announcements, and focus restoration
when actions disappear. Do not autofocus a new request or steal focus from the composer.
Use .chat-approval-status[role="status"] for updates, and keep an accessible name on
each request and action. Core supplies no networking, permission decisions, or focus scripts.
With Markdown
Use .chat-content.markdown-body directly in the agent row for a rich answer. Agent content handles available width and long text; markdown supplies typography without enclosing the answer in a bubble.
Agent Markdown Answer
Summary: the deployment is ready.
- Build completed
- Smoke test passed
<div id="demo-chat-markdown" style="width: min(42rem, 100%);">
<div class="chat chat-start chat-agent">
<div class="chat-avatar">
<div class="avatar avatar-sm avatar-tertiary">AI</div>
</div>
<div class="chat-content markdown-body">
<p><strong>Summary:</strong> the deployment is ready.</p>
<ul>
<li>Build completed</li>
<li>Smoke test passed</li>
</ul>
</div>
</div>
</div>For user messages, nest .markdown-body inside .chat-bubble. Prose, links and quotations inherit the bubble foreground in tonal and filled variants; code, keyboard keys and table surfaces keep their matching surface foreground.
User Bubble with Markdown
Please review the deployment summary.
Keep the public API compatible.
console.log("Ready to deploy");
Press Enter to continue.
<div class="chat chat-end">
<div class="chat-bubble chat-bubble-primary chat-bubble-filled">
<div class="markdown-body">
<p>Please review <a href="#demo-chat-markdown">the deployment summary</a>.</p>
<blockquote><p>Keep the public API compatible.</p></blockquote>
<pre><code>console.log("Ready to deploy");</code></pre>
<p>Press <kbd>Enter</kbd> to continue.</p>
</div>
</div>
</div>API Reference
Structure
| Class / Attribute | Description |
|---|---|
.chat-scroll |
Scrollable transcript (overflow-y: auto, scroll-behavior: smooth, timeline-scope for --chat-1…--chat-24) |
.chat-scroll-track |
Sticky indicator rail (use aria-hidden="true" when indicators are decorative/duplicative) |
.chat-scroll-body |
Message column that holds .chat rows |
.chat-scroll-indicator |
Visually spaced dash with a continuous hover/click area beside adjacent indicators; bind with data-chat-tl="N" + data-chat-target="message-id" (prefer <button>, not hash links) |
[data-chat-tl="N"] |
Shared slot 1–24 on agent .chat rows and their indicators |
[data-chat-target] |
Message id to scroll to inside .chat-scroll (docs demo wires the click handler) |
.chat |
Row wrapper for avatar and message stack |
.chat-start |
Row aligned to the inline start (left in LTR, right in RTL); compose with .chat-agent for agent output |
.chat-end |
User row aligned to the inline end (right in LTR, left in RTL) |
.chat-agent |
Full-width agent row with top-aligned optional avatar; uses one column when the avatar is omitted |
.chat-content |
Transparent unboxed agent answer or progress block; compose with .markdown-body for rich text |
.chat-streaming |
Streaming caret for .chat-content; respects reduced motion |
.chat-avatar |
Optional avatar slot; compose with the existing .avatar component |
.chat-header |
Small muted metadata above the message stack |
.chat-footer |
Small muted metadata below the message stack |
.chat-status |
Wrapping muted status and metrics row below the message body, with tabular numerals |
.chat-status-item |
Inline group for one state label or metric |
.chat-status-value |
Emphasized number within a metric |
.chat-actions |
Always-visible action row; compose with existing button classes |
.chat-actions-hover |
Modifier for .chat-actions; reveals on message hover or keyboard focus and stays visible on devices without hover |
.chat-bubble |
Rounded user message bubble; agent output uses .chat-content |
.chat-bubble-content |
Text slot for a collapsible sent user message |
.chat-bubble-collapsible |
Opt-in sent user bubble; limits its direct .chat-bubble-content child to six rendered lines until expanded |
.chat-bubble-toggle |
Native Show more / Show less button; connect its aria-controls to the content ID and synchronize aria-expanded |
Waiting Queue
| Class | Description |
|---|---|
.chat-input-area |
Structural stack attaching an inset waiting-message tray above the rounded composer |
.chat-queue |
Subdued waiting-message tray above the composer; supports the native hidden attribute |
.chat-queue-header |
Queue heading/count wrapper; use .sr-only for the attached-strip layout |
.chat-queue-title |
Queue heading; use it to name the section with aria-labelledby |
.chat-queue-count |
Optional queue count; keep it visually hidden in the attached strip and announce counts through status text |
.chat-queue-list |
Vertical list with one full-width message per row; use <ol role="list"> and a named keyboard scroll target |
.chat-queue-item |
One unboxed waiting-message row with inline actions; respects hidden |
.chat-queue-item-active |
Next message to dispatch; the application updates this state marker after queue changes |
.chat-queue-icon |
Decorative leading queue glyph |
.chat-queue-attachment |
Optional small image thumbnail; the caller supplies media and alternative text |
.chat-queue-number |
Current ordered position; use .sr-only in the attached-strip layout |
.chat-queue-content |
Single-line message preview; preserve the full text and provide a native title |
.chat-queue-actions |
Queue action group; compose with .chat-actions and existing button classes |
.chat-queue-steer |
Plain Steer action with a curved-arrow icon; compose with .btn.btn-ghost.btn-sm |
.chat-queue-remove |
Remove icon action; compose with a ghost square button and a specific accessible name |
.chat-composer |
Message form or container with a labelled editor and adjacent submission/steering actions; see Composer Parts for optional anatomy |
.chat-composer-{primary,secondary,tertiary,info,success,warning,error} |
Semantic composer color variants; focus treatment follows the chosen color |
.chat-composer-ghost |
Transparent composer border |
.chat-composer-input |
Native borderless textarea that grows with content up to 16rem, then scrolls; no resize handle. .chat-composer-editor adds the same surface for textarea or contenteditable use |
.chat-composer-actions |
Wrapping icon-button action group for Send/Queue and Steer, with accessible names and native Popover descriptions |
.chat-composer-hint |
Compact native <kbd> shortcut hint inside a composer action |
Bubble Modifiers
| Class | Description |
|---|---|
.chat-bubble-primary |
Primary color bubble |
.chat-bubble-secondary |
Secondary color bubble |
.chat-bubble-tertiary |
Tertiary color bubble |
.chat-bubble-info |
Info color bubble |
.chat-bubble-success |
Success color bubble |
.chat-bubble-warning |
Warning color bubble |
.chat-bubble-error |
Error color bubble |
.chat-bubble-filled |
Saturated filled style for color variants |
.chat-bubble-xs |
Extra small bubble |
.chat-bubble-sm |
Small bubble |
.chat-bubble-md |
Medium bubble, explicit alias of the base size |
.chat-bubble-lg |
Large bubble |
.chat-bubble-streaming |
Existing streaming caret modifier; compatibility alias on agent content (prefer .chat-streaming) |
LLM Classes
| Class | Description |
|---|---|
.chat-work |
Native <details> activity disclosure in an agent row; place before an answer or after a progress update |
.chat-work-summary |
Compact native <summary> with application-supplied work labels/counts and a disclosure chevron |
.chat-work-body |
Stack of disclosed work records, reasoning, and tool calls |
.chat-reasoning |
Collapsible reasoning trace using <details> in an agent row or its work body |
.chat-reasoning-body |
Reasoning content stack; may nest streaming .chat-tool blocks |
.chat-tool |
Collapsible tool call block using <details> in an agent row, its work body, or reasoning |
.chat-tool-header |
Summary content for tool name and status text |
.chat-tool-call |
Tool call payload slot |
.chat-tool-result |
Tool result payload slot |
.chat-tool-pending |
Pending tool status |
.chat-tool-running |
Running tool status with activity indicator |
.chat-tool-success |
Successful tool status |
.chat-tool-error |
Failed tool status |
.chat-typing |
Typing indicator dots |
Accessibility
- Use visible text for tool statuses such as
Pending,Running...,Done, andFailed. - Add
aria-label="Agent is typing"to the content that contains.chat-typing, or let the application announce the state through a polite status region. - Use native
<details>and<summary>for activity, reasoning, and tool records so keyboard interaction works without custom JavaScript. Keep work counts and failures readable as text; keep the final answer outside the disclosure. - Use native buttons for message actions, with descriptive accessible names when repeated labels need context. Hover actions reveal when a button receives keyboard focus; they remain visible on touch devices without hover.
- Keep status and token metrics readable as text. Let the application choose which state changes to announce; avoid announcing every token-count update.
- Use a native Show more / Show less button for long sent messages, with
aria-expandedandaria-controlssynchronized to the controlled content. Hide it for six or fewer rendered lines; move focus to the content before hiding a focused toggle after remeasurement. - Name the waiting queue and its list. Keep
role="list"when list markers are removed, and usetabindex="0"with an accessible name on the scrollable list so keyboard users can scroll it. - Give repeated Steer and icon-only Remove buttons names that identify their waiting message. Keep all row actions reachable, including rows after the next message to dispatch. After consuming or removing a focused queue row, move focus to a surviving row action or the message textarea.
- Announce queue transitions and the waiting count through one polite
role="status"region. Avoid announcing the same change through a live transcript as well. - Label the native textarea or rich textbox. Show keyboard hints and expose configured shortcuts through
aria-keyshortcuts; retain ordinary multiline editing and never dispatch during IME composition. The Waiting Queue demo uses Enter to send and Shift+Enter for a newline; the existing React default uses Enter for a newline. Render user input as text, such as withtextContent, instead of interpolating it into HTML. - Composer state styling does not implement disabled/read-only semantics, reference selection, or a listbox keyboard model. The host maintains native control attributes, active-descendant relationships, focus restoration, and complete semantic data behind truncated previews. Keep attachment Retry/Remove and queue actions available without hover.
- Give bounded quote or suggestion content a named
tabindex="0"scroll target when it has no keyboard-focusable descendant. A suggestion list with onlytabindex="-1"options still needs a reachable scroll target; alternatively, an application-managed roving-focus model keeps its active option keyboard-focusable. .chat-scrollrespectsprefers-reduced-motionby switchingscroll-behaviortoautoand disabling indicator animations. Give the scroll container a reachable height. Map ticks only to agent reply starts. Prefer<button data-chat-target>over hash links so navigation stays inside the panel; give each indicator anaria-label.
Related Components
- Avatar - user and assistant identity slots
- Code Block - tool call and result payloads
- Markdown Body - rich assistant message typography