Chat History

For development, import ChatHistory from @servicetitan/anvil2-ai-kit. For design, find it in the AI Kit Web Component Library file.

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.

Key	Description
Tab	Moves focus into or out of the list
Arrow Up / Arrow Down	Moves focus to the previous/next chat
Enter / Space	Selects the focused chat
Type-ahead	Jumps focus to the next chat matching the typed characters

Patterns that use this component

Agentic Experience Shell — Provides access to previous conversations

Code

Implementation
ChatHistory Props
ChatHistoryItem

Common Examples

To use the ChatHistory, pass configured conversations through items, handle selection through React Aria’s selection APIs, and use onNewChat to start a conversation.

import { ChatHistory } from "@servicetitan/anvil2-ai-kit";

function ExampleComponent() {
  return (
    <ChatHistory
      items={chats}
      selectedKeys={[activeId]}
      onSelectionChange={(keys) => openChat([...keys][0])}
      onNewChat={startChat}
    />
  );
}

Selection is fixed to single. Omit items or pass an empty array to render only the New Chat button.

Selected and unread

selectedKeys controls the active conversation. Set unread on an item to add a status dot and localized screen-reader text.

Subtitle

Every item requires a subtitle, typically a relative timestamp or last-message stamp. The component renders it verbatim; your application owns formatting and relative-time policy.

Overflow

Labels and subtitles truncate to one line. Place ChatHistory in a height-constrained container so long lists scroll instead of growing the rail.

Internationalization

ChatHistory owns these localized strings:

ai-kit.chatHistory.newChat
ai-kit.chatHistory.list
ai-kit.chatHistory.unread
ai-kit.chatHistory.recents

Localize each item’s label and subtitle before passing it. Mount AiKitIntlProvider inside CartoTheme to switch the built-in strings.

React Accessibility

React Aria supplies single-selection listbox semantics, arrow-key navigation, and typeahead.
Each item label is its accessible name; subtitle is its accessible description.
Unread items include localized hidden text. The visual status dot is decorative.
Pass aria-label or aria-labelledby to override the localized list name.

<ChatHistory
  items={chats}
  selectedKeys={[activeId]}
  onSelectionChange={setActive}
  onNewChat={startChat}
/>

`ChatHistory` Props

The ChatHistory accepts the following props and forwards remaining React Aria ListBox props except layout, orientation, selection mode, and composed children.

string

Class merged onto the rail container.

ChatHistoryItem[]

Conversations to list in display order. Omit or pass an empty array for no history.

() => void

Handles the New Chat button.

(keys: Selection) => void

Called when the selected conversation changes.

Selection

Controlled selected conversation key.

const chat: ChatHistoryItem = {
  id: "invoice-review",
  label: "Invoice review",
  subtitle: "5 minutes ago",
  unread: true,
};

`ChatHistoryItem`

Key

required

Selection key reported through listbox selection APIs.

string

required

Visible conversation title and accessible name.

string

required

Visible secondary line and accessible description. Supply formatted, localized text.

boolean

Prevents focus and selection.

boolean

default:"false"

Displays an unread indicator and adds localized hidden text.

Concepts & Guidelines

Anvil2

Resources

Chat History - Web

Options

Selected State

Unread

Time stamp

Behavior

Visual States

Truncation

Overflow

Usage Guidelines

When to Use

When not to use

Keyboard Interaction

Patterns that use this component

Code

Common Examples

Selected and unread

Subtitle

Overflow

Internationalization

React Accessibility

`ChatHistory` Props

`ChatHistoryItem`

​Options

​Selected State

​Unread

​Time stamp

​Behavior

​Visual States

​Truncation

​Overflow

​Usage Guidelines

​When to Use

​When not to use

​Keyboard Interaction

​Patterns that use this component

​Code

​Common Examples

​Selected and unread

​Subtitle

​Overflow

​Internationalization

​React Accessibility

​ChatHistory Props

​ChatHistoryItem

Options

Selected State

Unread

Time stamp

Behavior

Visual States

Truncation

Overflow

Usage Guidelines

When to Use

When not to use

Keyboard Interaction

Patterns that use this component

Code

Common Examples

Selected and unread

Subtitle

Overflow

Internationalization

React Accessibility

`ChatHistory` Props

`ChatHistoryItem`