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.
On this site
This site's own pages use ChatHeader too. Open one with X-ray pointing it out: The Nautilus's story
Install
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-monoreponpx shadcn@latest add ourostack/ouro-ui/ouro-base#v1.3.344Then 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.344Or, with the @ouro namespace set up:
npx shadcn@latest add @ouro/ouro-base @ouro/chat-headerIts 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.344import { 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
PageHeaderinstead for the top of a page that is not a chat, andThreadRail'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:
2in a page that has its own<h1>,1when the chat is the page, and3or4for 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 issubtitle:<ChatHeader subtitle="Planning the voyage" />.name: Not a prop. The chat's name istitle:<ChatHeader title="The whole crew" />.participants: Not a prop. The chat's people aremembers:<ChatHeader title="Crew" members={[{ name: "Ana Lind" }]} />.people: Not a prop. The chat's people aremembers:<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;
}
