Skip to main content

Chat

ChatHeader

The bar above an open chat: who it is with, and what you can do there. A one-to-one chat shows the person's avatar with their presence dot, their name and what the dot says. A group chat shows the group's avatar, drawn from its members as Avatar's members draws it, its name, "Captain Nemo and 3 others", and a button with the member count that opens the member list. The title is a heading (<h2> by default), so screen readers can jump to the chat; actions holds the chat's own buttons, such as a call, and onBack adds a back button for phones.

Chat

Launch crew

Ana Lind and 3 others

On this site

This site's own pages use ChatHeader too. Open one with X-ray pointing it out: The Nautilus's story

Install

Hand it to your agent
Add ChatHeader from Ouro UI to this app. Read https://ui.ouroboros.bot/docs/chat-header.md first and follow it.

Or by hand. Once per app, with Tailwind CSS v4 and an @/* path alias (Ouro HX is built on Base UI, so --base base; skip -t in an existing app):

npx shadcn@latest init --base base --preset nova --yes --no-monorepo
npx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.3.344

Then the component. From v0.8.0 it installs only the helpers it imports and never touches your stylesheet (Installing):

npx shadcn@latest add ourostack/ouro-ui/chat-header#v1.3.344

Or, with the @ouro namespace set up:

npx shadcn@latest add @ouro/ouro-base @ouro/chat-header

Its tests, stories and Playwright spec are optional. They need Vitest 4.1.11 or later, and from v0.8.0 never change a version your app has (Testing):

npx shadcn@latest add ourostack/ouro-ui/chat-header#v1.3.344 ourostack/ouro-ui/chat-header-tests#v1.3.344
import { ChatHeader } from "@/components/ouro/chat-header/chat-header";

Paths use shadcn's default @/ alias; the CLI rewrites them to yours.

Example

<ChatHeader title="The whole crew" members={crew.map((person) => ({ name: person.name, src: person.photoUrl, presence: person.presence, presenceLabel: person.status }))} />
<ChatHeader title="Ana Lind" members={[{ name: "Ana Lind", src: ana.photoUrl, presence: "busy", presenceLabel: "In a meeting" }]} onBack={() => setOpenId(null)} />

Use instead when

  • Use PageHeader instead for the top of a page that is not a chat, and ThreadRail's own header for a thread.

Props

Type: ChatHeaderProps.

actions
Type: ReactNode
Buttons at the end of the header, such as a call button or a menu.
avatar
Type: string
The group's own picture, in place of its members' faces once it loads. Read only for a group chat.
backLabel
Type: string
Default: "Back"
What screen readers hear for the back button, for other languages.
className
Type: string
Layout only: margins, padding, width (px-4 py-2). Appearance classes warn in development.
level
Type: 1 | 2 | 3 | 4
Default: 2
The title's heading level: 2 in a page that has its own <h1>, 1 when the chat is the page, and 3 or 4 for a chat inside a section with its own heading.
members (required)
Type: readonly ChatMember[]
Who the chat is with, not counting the reader. One member makes a one-to-one chat: their avatar with their presence dot, and what the dot says under the title. Two or more make a group chat: the group's avatar drawn from its members (Avatar's members), "Captain Nemo and 3 others" under the title, and a button with the count that opens the member list, each with their face, name, note and presence.
membersLabel
Type: ((count: number) => string)
Default: (count) => `${count} members`
What screen readers hear for the member list's button, from the count, for other languages.
membersTitle
Type: string
Default: "Members"
The member list's title, for other languages.
onBack
Type: ((event: MouseEvent<HTMLButtonElement>) => void)
Shows a back button at the start, for a phone layout where the chat covers the list of chats. It is called when the button is pressed.
othersLabel
Type: ((names: readonly string[]) => string)
Default: the first name, then "and" the second, or the rest's count ("Captain Nemo and 3 others")
The line under a group chat's title, from its members' names, for other languages.
ref
Type: Ref<HTMLDivElement>
Reaches the rendered element.
subtitle
Type: ReactNode
The line under the title, in place of the presence or "Captain Nemo and 3 others", such as "Ned Land is writing…".
title (required)
Type: string
The chat's name: the person's name in a one-to-one chat, the group's in a group chat. It is the header's heading.

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.

  • description: Not a prop. The line under the title is subtitle: <ChatHeader subtitle="Planning the voyage" />.
  • name: Not a prop. The chat's name is title: <ChatHeader title="The whole crew" />.
  • participants: Not a prop. The chat's people are members: <ChatHeader title="Crew" members={[{ name: "Ana Lind" }]} />.
  • people: Not a prop. The chat's people are members: <ChatHeader title="Crew" members={[{ name: "Ana Lind" }]} />.

className is for layout only

Pass margins, width and grid placement (mt-4, w-full, col-span-2).

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

AvatarMember

One member of a group chat, as Avatar's members takes them.

interface AvatarMember {
  /** The member's name: their initial comes from it, and screen readers hear it in the group's name. */
  name: string;
  /** The member's picture. Until it loads, and if it fails, their initial shows in their hue. */
  src?: string | undefined;
  /** What their hue is picked from, when it should not be `name`, as Avatar's `idForColor`. */
  idForColor?: string | undefined;
  /** The letters to take their initial from, when it should not come from `name`. */
  initials?: string | undefined;
}

AvatarPresence

A person's presence, drawn as a dot with its own shape: a check (available), a solid dot (busy), a bar (do not disturb), a clock (away), a ring with a cross (offline) and a ring with an arrow (out of office), so it never relies on color alone.

type AvatarPresence = "available" | "busy" | "away" | "do-not-disturb" | "offline" | "out-of-office";

ChatHeaderOwnProps

The props ChatHeader adds to the <div> attributes it passes through.

interface ChatHeaderOwnProps {
  /** The chat's name: the person's name in a one-to-one chat, the group's in a group chat. It is the header's heading. */
  title: string;
  /**
   * Who the chat is with, not counting the reader. One member makes a one-to-one chat: their avatar with their
   * presence dot, and what the dot says under the title. Two or more make a group chat: the group's avatar drawn
   * from its members (Avatar's `members`), "Captain Nemo and 3 others" under the title, and a button with the
   * count that opens the member list, each with their face, name, note and presence.
   */
  members: readonly ChatMember[];
  /** The group's own picture, in place of its members' faces once it loads. Read only for a group chat. */
  avatar?: string | undefined;
  /** The line under the title, in place of the presence or "Captain Nemo and 3 others", such as "Ned Land is writing…". */
  subtitle?: ReactNode;
  /** Buttons at the end of the header, such as a call button or a menu. */
  actions?: ReactNode;
  /**
   * Shows a back button at the start, for a phone layout where the chat covers the list of chats. It is called when
   * the button is pressed.
   */
  onBack?: ((event: MouseEvent<HTMLButtonElement>) => void) | undefined;
  /** What screen readers hear for the back button, for other languages. @default "Back" */
  backLabel?: string | undefined;
  /**
   * The title's heading level: `2` in a page that has its own `<h1>`, `1` when the chat is the page, and `3` or `4` for a
   * chat inside a section with its own heading. @default 2
   */
  level?: 1 | 2 | 3 | 4 | (number & { 'Use 1, 2, 3 or 4': never }) | undefined;
  /**
   * The line under a group chat's title, from its members' names, for other languages.
   * @default the first name, then "and" the second, or the rest's count ("Captain Nemo and 3 others")
   */
  othersLabel?: ((names: readonly string[]) => string) | undefined;
  /** What screen readers hear for the member list's button, from the count, for other languages. @default (count) => `${count} members` */
  membersLabel?: ((count: number) => string) | undefined;
  /** The member list's title, for other languages. @default "Members" */
  membersTitle?: string | undefined;
  /** Layout only: margins, padding, width (`px-4 py-2`). Appearance classes warn in development. */
  className?: string | undefined;
  ref?: Ref<HTMLDivElement> | undefined;

  /** Not a prop. The chat's people are `members`: `<ChatHeader title="Crew" members={[{ name: "Ana Lind" }]} />`. */
  participants?: { 'Use members={[{ name, src }]}': never };
  /** Not a prop. The chat's people are `members`: `<ChatHeader title="Crew" members={[{ name: "Ana Lind" }]} />`. */
  people?: { 'Use members={[{ name, src }]}': never };
  /** Not a prop. The line under the title is `subtitle`: `<ChatHeader subtitle="Planning the voyage" />`. */
  description?: { 'Use subtitle="..."': never };
  /** Not a prop. The chat's name is `title`: `<ChatHeader title="The whole crew" />`. */
  name?: { 'Use title="The whole crew"': never };
}

ChatHeaderProps

Props for ChatHeader: its own props and the <div> attributes it passes through.

type ChatHeaderProps = Omit<HTMLAttributes<HTMLDivElement>, keyof ChatHeaderOwnProps> & ChatHeaderOwnProps;

ChatMember

Someone in a chat, as ChatHeader takes them: an Avatar's member, with their presence and a note.

type ChatMember = AvatarMember & {
  /** A short line under their name in the member list, such as their role ("the harpooner"). */
  note?: string | undefined;
} & (ChatMemberPresence | ChatMemberNoPresence);

ChatMemberNoPresence

A member without a presence dot.

interface ChatMemberNoPresence {
  /** Leave it out for no dot; pass it with `presenceLabel` to show one. */
  presence?: undefined;
  /** Read only with `presence`. */
  presenceLabel?: string | undefined;
}

ChatMemberPresence

A member with a presence dot and the words it says.

interface ChatMemberPresence {
  /** Their presence, as a dot on their avatar in a one-to-one chat's header and in the member list. */
  presence: AvatarPresence;
  /**
   * What the dot says ("In a meeting"): a one-to-one chat's header shows it under the title. Required with `presence`, so no dot is silent.
   */
  presenceLabel: string;
}