Conversation List React component for Tailwind CSS v4

Add to a project

Requirements: React 19 and Tailwind CSS v4, in Next.js (App Router or Pages), Vite or React Router. Installation guide · Next.js setup · Vite setup

Conversation List is part of Pro, with 298 more Pro items: $8 a month or $150 once. 14-day refund before you download any Pro item. See plans

Usage

Import ConversationList from @/components/ui/conversation-list.

import { useState } from "react"
import { Share2 } from "lucide-react"
import { ConversationList, type ConversationItem } from "@/components/ui/conversation-list"

// your own wording over the English defaults (DEFAULT_CONVERSATION_LIST_LABELS)
const LABELS = {
  nav: "Assistant chats",
  pinned: "Starred",
  deleteTitle: (title: string) => `Delete “${title}” for good?`,
}

export function ChatHistory({ initial }: { initial: ConversationItem[] }) {
  const [chats, setChats] = useState(initial)
  const [open, setOpen] = useState(initial[0]?.id ?? "")
  const patch = (id: string, change: Partial<ConversationItem>) =>
    setChats((list) => list.map((chat) => (chat.id === id ? { ...chat, ...change } : chat)))

  return (
    <aside className="h-dvh w-72 bg-card">
      <ConversationList
        conversations={chats}
        value={open}
        onValueChange={setOpen}
        onNewChat={() => {
          const id = crypto.randomUUID()
          setChats((list) => [{ id, title: "", updatedAt: Date.now() }, ...list])
          setOpen(id)
        }}
        onRename={async (id, title) => {
          await fetch(`/api/chats/${id}`, { method: "PATCH", body: JSON.stringify({ title }) })
          patch(id, { title })
        }}
        onPinChange={(id, pinned) => patch(id, { pinned })}
        onArchive={(id) => patch(id, { archived: true })}
        onDelete={(id) => setChats((list) => list.filter((chat) => chat.id !== id))}
        getActions={(chat) => [{ id: "share", label: "Share", icon: <Share2 />, onSelect: () => navigator.clipboard.writeText(`/chat/${chat.id}`) }]}
        newChatShortcut="shift+mod+o"
        showTime
        locale="en-US"
        labels={LABELS}
      />
    </aside>
  )
}

// server search: control the text, show the server's results as they come, and keep them unfiltered
// <ConversationList conversations={results} searchValue={query} onSearchChange={setQuery} searching={pending} filter={false} />
// long histories: hasMore + onLoadMore (a promise keeps Load more spinning; it also runs when it scrolls into view)

Props

• conversations*
  ConversationItem[]

  The history: { id, title, updatedAt, preview?, pinned?, unread?, streaming?, archived?, href?, icon?, model? }. updatedAt (a Date, an ISO string or ms) sorts and groups them; a missing or invalid one goes to Earlier at the end. An empty title shows labels.untitled. Keep the objects immutable: a new object only for the chat that changed.

• value
  string

  The open conversation's id (controlled). Without it, rows with an href follow the current page of a LinkProvider (currentPath), and otherwise the last clicked row stays open. An id that is not in the list highlights nothing.

• defaultValuedefault ""
  string

  The conversation open on the first render while uncontrolled. Empty in the playground opens Overdue invoices, September.

• onValueChange
  (id: string, item: ConversationItem) => void

  A row was chosen (a click, a tap or Enter). Rows with an href also navigate.

• onNewChat
  () => void

  Shows the New chat button at the top (and makes newChatShortcut work).

• onRename
  (id: string, title: string) => (void | Promise<unknown>)

  Enables Rename in the menu, F2 and a double click with a mouse. The new title (trimmed, never empty) shows at once; a returned promise keeps the row busy, and a rejection brings the old title back and announces the error.

• onPinChange
  (id: string, pinned: boolean) => (void | Promise<unknown>)

  Enables Pin / Unpin. The chat slides into (or out of) Pinned at once and rolls back if the promise rejects.

• onArchive
  (id: string) => (void | Promise<unknown>)

  Enables Archive. The chat leaves the list at once (unless showArchived) and comes back if the promise rejects.

• onDelete
  (id: string) => (void | Promise<unknown>)

  Enables Delete (the menu, Delete or Backspace on a focused row). After the confirmation the chat leaves at once and focus moves to the next chat, or New chat; a rejection brings it back.

• getActions
  (item: ConversationItem) => MenuEntry[]

  Extra dropdown-menu entries above the built-in ones (Share, Move to project, a submenu). Called each time a menu opens, so they can depend on the app's state.

• searchdefault true
  boolean

  The search field under New chat. Its text still filters the list when you hide it and pass searchValue yourself.

• searchValue
  string

  The search text (controlled). Pair it with onSearchChange for a server search, then pass the results as conversations and filter={false}.

• defaultSearchValuedefault ""
  string

  The search text on the first render while uncontrolled.

• onSearchChange
  (value: string) => void

  Every keystroke in the search, and the clear.

• searchingdefault false
  boolean

  The search icon turns into a spinner while your server looks for results.

• searchShortcutdefault ""
  string

  A key combo in mod+k notation that focuses the search from anywhere, shown as a hint in the empty field. "" binds nothing.

• filterdefault true
  boolean

  Filters titles, previews and model names locally while searching (case and diacritics ignored, best matches first). false keeps conversations as given, for results that come from a server.

• groupBydefault "date"
  "date" | "none"

  date: Pinned, Today, Yesterday, Previous 7 days, Previous 30 days, then one group per month, each under a sticky label. none: one list, pinned chats first with a pin glyph.

• showPreviewdefault false
  boolean

  A second line with the last message; rows grow to 52 / 56px.

• showTimedefault false
  boolean

  A trailing time: "4:35 PM" today, "Yesterday" yesterday, "Sep 22" this year, the full date before. With a mouse the ⋯ takes its place on hover.

• showArchiveddefault false
  boolean

  Lists archived chats too, muted and with an archive glyph (the demo has one from August).

• sizedefault "md"
  "sm" | "md"

  Rows 36 / 40px (44px on touch), with New chat and the search at the same height.

• radiusdefault "md"
  "none" | "sm" | "md" | "lg" | "full"

  The rows' corners, the button's radius at the row size (8 / 10px at md); full makes pills.

• tonedefault "neutral"
  "neutral" | "brand" | "success" | "warning" | "danger" | "info"

  Colors the open row (a gray tint for neutral, the tone's soft fill otherwise), the unread dot and the streaming spinner.

• colordefault ""
  string

  Any CSS color. Replaces the tone for the open row, the dot and the spinner. Leave empty to use the tone.

• actionsVisibilitydefault "hover"
  "hover" | "always"

  hover: with a mouse the ⋯ shows on hover and keyboard focus (it is always there on touch and on the open chat). always: on every row, which keeps room for it.

• confirmDeletedefault true
  boolean

  Asks in an alert dialog before onDelete. false deletes at once.

• newChatShortcutdefault ""
  string

  A key combo in mod+k notation that calls onNewChat from anywhere, shown on the button (⇧⌘O on a Mac, Ctrl+Shift+O elsewhere) and hidden on touch. "" binds nothing; the demo uses shift+mod+o.

• loadingdefault false
  boolean

  Skeleton rows with the real row shape (two lines with showPreview) and aria-busy, while the history loads.

• skeletonCountdefault 8
  number

  How many skeleton rows loading shows.

• hasMoredefault false
  boolean

  Load more at the end of the list; it also runs onLoadMore when it scrolls into view (once per new page, never while searching).

• onLoadMore
  () => (void | Promise<unknown>)

  Loads the next page of older chats; a returned promise keeps Load more spinning until it settles.

• loadingMoredefault false
  boolean

  Keeps Load more spinning, for apps that track the request themselves.

• emptyState
  ReactNode

  Replaces the empty state (a chat icon, labels.empty and labels.emptyDescription). A search with no match shows its own, with Clear search.

• linkComponent
  (props: LinkComponentProps) => ReactNode

  Renders rows that have an href: next/link's Link, react-router's Link. Defaults to the LinkProvider's, then a plain <a>.

• now
  Date | number

  The reference time for the day groups and times; default useNow(), which ticks each minute. Without it the list shows skeleton rows on the server and during hydration, so pass a server time to render the real list there.

• localedefault ""
  string

  Formats times, month groups and the result count ("en-US"). Empty uses the UIProvider's locale, then the browser's.

• labels
  Partial<ConversationListLabels>

  Every visible and spoken string, English by default (DEFAULT_CONVERSATION_LIST_LABELS): group names, the menu, the delete confirmation, the rename sheet, the empty states and the announcements. Counted and titled ones are functions: results(count, formatted), actions(title), deleteTitle(title), renamed(title). Pass a stable object.

• classNames
  Partial<Record<"header" | "newChat" | "search" | "scroller" | "group" | "groupLabel" | "list" | "item" | "row" | "icon" | "title" | "preview" | "indicator" | "time" | "actions" | "rename" | "more" | "empty" | "skeleton", string>>

  Extra classes for the inner parts.

• className
  string

  Extra classes for the root <nav>. It inherits its parent's background so the sticky day labels cover the rows; give it one (bg-card) when the parent is transparent.

Parts

FAQ

Used in

More React AI components