Skip to content
WunderUI

Chat List View

Pro

The list of past conversations: a title, a one-line preview and a time per row, with the open one marked.

Playground

Installation

Chat List View comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

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

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 for

  • List Group for rows of any other kind of record, with their own columns or actions
  • Sidebar for navigation between the sections of an app
  • Table for many records that people sort, filter and compare

Content

Each row shows a title and a time, then a preview. Title and preview cut off at one line and the time never shrinks, so give the list a width.

Row state

Hover fills the row with the page colour, pressed and the open conversation use the subtle fill, and focus draws the indigo border with a ring. Unread adds a red dot and a semibold title.

Layout

Give rows a group and they gather under a small heading, for the day or the agent; the arrow keys still run through every row. layout="cards" turns the list into a two-column grid of bordered cards for a start page, with leading marks, a summary and a meta line.

Inbox row

ChatListRow is the taller row of an inbox: the sender's avatar, the name and time, the subject, a one-line preview and optional tags. unread adds a red dot and the indigo tint, active marks the open conversation. It is a button with its own border below, so stack the rows in a list. It replaces ConversationItem.

Title-only rows and renderRow

Without a preview and timestamp a row is only its title, grouped under day headings. renderRow builds the whole row yourself (chips, a menu, a count); spread the given props on the element that takes the focus to keep the arrow keys. Card grids use a 16 px gap.

Title-only rows and your own row

Keyboard interactions

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

TaborShiftTab
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.
HomeorEnd
Moves focus to the first or the last row.
Enter
Opens the focused row: it calls 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 and motion

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

The figure marks the list, one row and its three texts. The unread dot has no number and shows only on an unread row.

  • data-slot="chat-list-view"

    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.

  • 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.

  • The title, 14 px medium, cut to one line. An unread row sets it in semibold and adds the hidden text unread.

  • The timestamp, 11 px tertiary text, right of the title. It is shown as given and does not shrink.

  • The preview, 12 px tertiary text, cut to one line under the title.

  • Optional

    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.

  • data-slot="chat-list-item"Optional
  • data-slot="chat-list-unread"Optional
  • data-slot="chat-list-row"Optional

    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.

  • Optional

Best practices

  • Do

    Mark only the open conversation as active, and update it in the select handler.

  • Do

    Pass the timestamp already formatted, such as 2 min ago, Mon or Nov 3, in the reader's language. It renders as given.

  • Do

    Wrap the list in a nav with an aria-label, and put a heading above each group when you group by day.

  • Do

    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.

  • Do

    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.

  • Do

    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

    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 is a plain component. Each item in the items list is a ChatListItem. ChatListRow takes only the props listed under it.

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.

PropTypeDefaultDescription
items requiredChatListItem[]—The conversations, as . is the key, is shown as given, marks the open one and adds the red dot.
onSelect(item) => 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 , and clear for it.
classNamestring—Extra classes for the list, for example to set its width or to open the rows up.
layout"list" | "cards""list" is the sidebar column, a grid of bordered cards for a start page. Groups apply to .
renderRow(item, state) => 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 on the focusable element. is not called f…

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.

PropTypeDefaultDescription
person required{ name: string; initials?: string; src?: string; color?: AvatarColor }—The sender as , and optionally , and . Required.
time requiredReactNode—The time at the end of the first line. Required.
subject requiredReactNode—The subject, cut to one line. Required.
preview requiredReactNode—The start of the message, cut to one line. Required.
tags{ label: ReactNode; color?: BadgeColor }[]—A list of badges under the preview, each with a and a .
unreadboolean—Tints the row indigo and shows the red dot before the time; the dot carries the name Unread.
activeboolean—Marks the open conversation with the subtle fill and .
onClick() => void—Called when the row is pressed.
classNamestring—Extra classes on the row.

PropTypeDefaultDescription
person required{ name: string; initials?: string; src?: string; color?: AvatarColor }—The sender. default to the first letters of the name.
preview requiredReactNode—
subject requiredReactNode—
time requiredReactNode—
activeboolean—The open conversation: subtle background, .
onClick() => void—
tags{ label: ReactNode; color?: BadgeColor }[]—
unreadboolean—

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("chat-list-view")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.