# Chat List View

A sidebar list of past conversations with preview and timestamp.

- Category: AI & Agents
- Page: https://wunderui.com/components/chat-list-view
- Tier: Core and Pro

## Install

Chat List View ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```tsx
import { ChatListView, ChatListRow, ChatListRowState, ConversationItem } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { useState } from "react"
import { ChatListView } from "@wunderui/react"

const history = [
  { id: "q3", title: "Q3 report summary", preview: "Revenue grew 12% to $1,842,000", timestamp: "2 min ago" },
  { id: "churn", title: "Churn by plan", preview: "Churn fell from 2.4% to 1.8%", timestamp: "1 hr ago" },
]

export function History() {
  const [activeId, setActiveId] = useState("q3")
  return (
    <nav aria-label="Chat history" className="w-80">
      <ChatListView
        items={history.map((item) => ({ ...item, active: item.id === activeId }))}
        onSelect={(item) => setActiveId(item.id)}
      />
    </nav>
  )
}
```

Expected result: You see two rows with a title, a time and a one-line preview, and the first has a grey fill. Press the second and the fill moves to it, and press Tab once, then arrow keys, to move between rows.

## When to use

### Use Chat List View for

- The history of conversations in a sidebar or a panel, with a title, a preview and a time per entry
- A list where one conversation is open and the others open on a click, with a mark on the ones with new messages
- A short list of recent chats under a New chat button

### Use something else

- [List Group](https://wunderui.com/components/list-group) for rows of any other kind of record, with their own columns or actions
- [Sidebar](https://wunderui.com/components/sidebar) for navigation between the sections of an app
- [Table](https://wunderui.com/components/table) for many records that people sort, filter and compare

## Keyboard

The rows are native links with a roving tab stop: the list is one tab stop, and arrow keys move focus between its rows.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus into the list and out of it. Focus lands on the row you were on last, on the open row, or on the first row. Focus shows as an indigo border with a 2 px ring. |
| `ArrowDown` | Moves focus to the next row. It stops at the last row and does not wrap. |
| `ArrowUp` | Moves focus to the previous row. It stops at the first row and does not wrap. |
| `Home` or `End` | Moves focus to the first or the last row. |
| `Enter` | Opens the focused row: it calls `onSelect` with the item and prevents the `#` navigation. |

Arrow keys only move focus and never open a row, and modified arrows (Shift, Ctrl, Alt, Meta) go to the browser. A search field or heading above the list is a separate tab stop.

## Behavior

What the list does with a click, the open row and a long text.

- **Selection is yours:** The list holds no selection. Mark the open item active and change it in the select handler, which receives the item clicked or opened with Enter.
- **Open row:** The active item is marked as the current page and gets the subtle fill. Set it on one item only, since the list does not clear others, and it also gets the tab stop when focus enters.
- **Focus:** One row is the tab stop and the others are skipped, and the stop follows arrow keys, clicks and Tab, so Shift+Tab leaves the list. If the items change, the stop returns to the open row or the first.
- **Links without a route:** Every row is a link with a placeholder address, and the click is prevented, so the page does not jump and no new tab opens. For real routes, render your own links.
- **Unread:** An unread item shows a red dot after the preview, without a number, and a semibold title. Screen readers hear unread after the title, and the list never clears it, so reset it in the select handler.
- **Search, groups and empty state:** The component draws only the rows. Search, groups, the loading skeleton and the empty or error state are yours to add, as the Examples tab shows, and each list keeps its own tab stop.
- **Names:** A row is named by its content: title (with unread when it applies), time and preview, in that order. The list has no name, so wrap it in a nav with an aria-label such as Chat history.
- **Long text:** The title and preview stay on one line and end with an ellipsis. The time keeps its width, so the title gives way first.
- **Hover and press:** Hover fills a row with the page colour, and pressing uses the subtle fill, so a press looks like the open state. The open row does not change on hover.
- **Motion:** The fill changes with a quick colour transition. Nothing moves or scales.
- **Reduced motion:** Nothing moves, so reduced motion changes nothing. The fill still changes in the same short time.

## Anatomy

- `ChatListView`: A column of rows with 2 px between them. It handles Up, Down, Home and End, and has no role of its own, so wrap it in a nav with a name.
- `Row`: One conversation: a link with 12 px by 8 px of padding and an 8 px corner. The open one is marked as the current page and gets the subtle fill, and only one row of the list is a tab stop.
- `Title`: The title, 14 px medium, cut to one line. An unread row sets it in semibold and adds the hidden text unread.
- `Timestamp`: The timestamp, 11 px tertiary text, right of the title. It is shown as given and does not shrink.
- `Preview`: The preview, 12 px tertiary text, cut to one line under the title.
- `Unread dot`: An 8 px red dot after the preview on the right, drawn for an unread item. It has no number and is hidden from assistive technology, since the title carries the word instead.
- `ChatListRow`: One conversation of an inbox as a button: the sender's avatar, the name and time, the subject, a one-line preview and optional tags, with a border below. It replaces ConversationItem.
- `ConversationItem`
- `Chat List Item`
- `Chat List Unread`

## Best practices

### When to use

- Use ChatListView for the history of conversations in a sidebar or a panel. For navigation between app sections, use a sidebar.

### Do

- Mark only the open conversation as active, and update it in the select handler.
- Pass the timestamp already formatted, such as 2 min ago, Mon or Nov 3, in the reader's language. It renders as given.
- Wrap the list in a nav with an aria-label, and put a heading above each group when you group by day.
- Mark a conversation unread when it has new messages and clear it on select. The dot shows no count, so say how many in the preview or the conversation.
- Keep search outside the list: a field above it that filters the items you pass in, with a live region that says how many conversations are left.
- Show skeleton rows while the list loads, and an Empty State when there is nothing or the request failed.

### Don't

- Don't put a whole message into the preview. It is cut to one line, so send the first words of the last message.
- Don't show the number of unread messages in the row. The list draws a dot only, and a count belongs in a badge you place yourself.

## API reference

### ChatListView

| Prop | Type | Default | Description |
|---|---|---|---|
| items* | ChatListItem[] |  | The conversations, as `{ id, title, preview, timestamp, active?, unread? }`. `id` is the key, `timestamp` is shown as given, `active` marks the open one and `unread` adds the red dot. |
| className | string |  | Extra classes for the list, for example `w-80` to set its width or `gap-1` to open the rows up. |
| layout | "list" \| "cards" | "list" | `list` is the sidebar column, `cards` a grid of bordered cards for a start page. Groups apply to `list`. |
| onSelect | (item: ChatListItem) => void |  | Called with the item when its row is clicked or opened with Enter. The `#` navigation is prevented. Store the id and hand it back as `active`, and clear `unread` for it. |
| renderRow | (item: ChatListItem, state: ChatListRowState) => React.ReactNode |  | Builds the row yourself, for rows that hold more than a link (several chips, a menu, a count). The row is wrapped as a list item; keep the arrow-key navigation by spreading `state.props` on the focusable element. `onSelect` is not called f… |

### ChatListRow

| Prop | Type | Default | Description |
|---|---|---|---|
| person* | { name: string; initials?: string; src?: string; color?: AvatarColor } |  | The sender as `name`, and optionally `initials`, `src` and `color`. Required. |
| preview* | React.ReactNode |  | The start of the message, cut to one line. Required. |
| subject* | React.ReactNode |  | The subject, cut to one line. Required. |
| time* | React.ReactNode |  | The time at the end of the first line. Required. |
| active | boolean |  | Marks the open conversation with the subtle fill and `aria-current`. |
| className | string |  | Extra classes on the row. |
| onClick | () => void |  | Called when the row is pressed. |
| tags | { label: React.ReactNode; color?: BadgeColor }[] |  | A list of badges under the preview, each with a `label` and a `color`. |
| unread | boolean |  | Tints the row indigo and shows the red dot before the time; the dot carries the name Unread. |

### ConversationItem

| Prop | Type | Default | Description |
|---|---|---|---|
| person* | { name: string; initials?: string; src?: string; color?: AvatarColor } |  | The sender. `initials` default to the first letters of the name. |
| preview* | React.ReactNode |  |  |
| subject* | React.ReactNode |  |  |
| time* | React.ReactNode |  |  |
| active | boolean |  | The open conversation: subtle background, `aria-current`. |
| className | string |  |  |
| onClick | () => void |  |  |
| tags | { label: React.ReactNode; color?: BadgeColor }[] |  |  |
| unread | boolean |  |  |

## Examples

### Content: several rows, long text, a single row

### Row state: default, hover, pressed, selected, focus, unread

### Layout: grouped list or cards

### Inbox row: sender, subject, preview and tags

### Title-only rows and your own row

## In context

### History panel: search, groups by day, the open conversation

The list has no search or groups of its own. This panel adds a search field, one list per day and an empty result, with Up and Down between rows and Enter to open.

### States of the history: ready, loading, empty, error

The list shows only rows. While loading, show skeleton rows of the same height, and when it is empty or failed, swap in an Empty State.

## For AI agents

`get_component("chat-list-view")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
