ConversationList

Install

import { ConversationList } from "@/components/ouro/conversation-list/conversation-list";

Example

<ConversationList label="Conversations" items={conversations} selectedId={openId} onSelect={setOpenId} />

Use instead when

• Use ItemGroup instead for a static list with nothing open, and Tabs for a handful of views that switch in place.

Props

Type: ConversationListProps.

className

Type: string

Layout only: width, margins, grid placement (w-80). Appearance classes warn in development.

density

Type: "comfortable" | "compact"

Default: "comfortable"

compact drops the preview line and uses a smaller avatar.

empty

Type: ReactNode

Default: "Nothing here yet"

What shows when items is empty.

items (required)

Type: readonly ConversationListItem[]

The conversations, in the order they show.

label (required)

Type: string

What the list is, for screen readers ("Conversations"). Required, so the list has a name.

onSelect (required)

Type: (id: string) => void

Called with a row's id when it is chosen by a click, a tap, Enter or Space.

ref

Type: Ref<HTMLDivElement>

Reaches the rendered element.

selectedId

Type: string | null

The id of the open conversation. Its row is highlighted and marked aria-current.

unreadLabel

Type: string

Default: "Unread"

What screen readers hear for an unread row's dot, for other languages.

Native attributes

Also accepts the attributes in React's HTMLAttributes (id, aria-*, event handlers), passed to the rendered element, except those named on this page.

Don't use

These are not props. Passing one fails the type check with the fix in the error, and in development a console message names the fix.

• conversations: Not a prop. The rows are items: <ConversationList items={conversations}>.
• onValueChange: Not a prop. A chosen row calls onSelect: <ConversationList onSelect={(id) => open(id)}>.
• selected: Not a prop. The open conversation is selectedId: <ConversationList selectedId={openId}>.
• value: Not a prop. The open conversation is selectedId: <ConversationList selectedId={openId}>.

className is for layout only

Pass margins, width and grid placement (mt-4, w-full, col-span-2). Your classes always win over Ouro UI's: ConversationList merges className last with cn (tailwind-merge), so a class that conflicts with its own replaces it.^{layout-classes}

Appearance comes from props, not classes. In development, a class that sets appearance logs one warning per component instance, naming the prop to use instead. A class sets appearance when, after its variants (hover:, sm:) and any ! are removed, it starts with bg-, text-, border-, rounded-, shadow-, font-, ring-, from-, via-, to-, fill- or stroke-, or is border, rounded, shadow or ring, or has a dark: variant. Text wrapping, overflow and table layout classes (text-wrap, text-ellipsis, border-collapse) are layout and do not warn.

Alignment classes (text-center) warn too: set alignment on a parent element.

Types

ConversationListItem

One conversation in a ConversationList.

interface ConversationListItem {
  /** Identifies the conversation; `onSelect` receives it. */
  id: string;
  /** The conversation's name: a person, a group or a topic. The avatar's initials come from it. */
  title: string;
  /** A second line under the title, such as the group a topic belongs to. */
  subtitle?: string | undefined;
  /** The latest message, cut to one line. `density="compact"` hides it. */
  preview?: ReactNode;
  /** When the latest message arrived, already formatted ("9:41", `<RelativeTime>`). */
  time?: ReactNode;
  /** There are messages the person has not read: the title is bold and a dot shows. */
  unread?: boolean | undefined;
  /** Small marks after the title, such as a `<Badge>`. */
  badges?: ReactNode;
  /** The avatar's picture URL. Without it the avatar shows initials; `false` hides the avatar. */
  avatar?: string | false | undefined;
}