ChatHistory – Design

​

Options

ChatHistory renders a typed items array — each chat carries a required label and timestamp, and can flag itself as unread.

​

Selected State

Selection is locked to single — at most one chat is ever active. The selected row keeps a persistent tint and bolds its title; drive it with selectedKeys / onSelectionChange (controlled) or defaultSelectedKeys (uncontrolled), the same way you would a Menu.

​

Unread

Set unread on a chat to render a dot at the end of its title row (announced as “Unread” to assistive tech). Unread is independent of selection — a chat can be both unread and active.

​

Time stamp

subtitle is rendered verbatim — Carto doesn’t compute relative time. Pass whatever stamp fits the moment: a relative duration, a clock time, a day name, or an absolute date. The consumer owns the formatting and any policy for when it changes.

​

Behavior

Rows respond to the standard interaction states and truncate or scroll rather than reflow the rail.

​

Visual States

Unselected rows stay neutral — transparent at rest, with a subtle fill on hover and press. The selected row keeps that fill persistently. Keyboard focus shows the ring only, and a disabled chat (via disabledKeys) can’t be focused, selected, or activated.

​

Truncation

A title or subtitle longer than the rail’s width truncates to a single line with a trailing ellipsis — the row never wraps or grows taller.

​

Overflow

A history longer than the rail’s height scrolls within it; the “New Chat” button stays pinned above the list.

​

Usage Guidelines

​

When to Use

Use the Chat History when:

• Resuming earlier conversations – Users need to see prior chats and return to one.
• Filling the shell’s left rail – The App Shell or Window needs its history rail, with New Chat pinned above the list.
• Showing the active and unread chats – One chat is marked as active while others flag unread activity.

​

When not to use

Avoid using the Chat History for:

• Selecting several items at once – Selection is locked to a single active chat.
• Presenting actions or options from a trigger – Use the Menu instead.
• Switching between related views in the supporting workspace – Use the Tabbed Layout instead.

​

Keyboard Interaction

Users can navigate and select chats using standard keyboard controls.

​

Patterns that use this component

• Agentic Experience Shell — Provides access to previous conversations