<!-- Generated by scripts/gen-docs.mts from the JSDoc in registry/. Do not edit; run `pnpm run docs`. -->

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

## Install

Once per app, with Tailwind CSS v4 and an `@/*` path alias (skip `init` in an existing shadcn app), then the component:

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

More: [Installing](https://ui.ouroboros.bot/docs/installing.md).

```tsx
import { ChatHeader } from "@/components/ouro/chat-header/chat-header";
```

## Example

```tsx
<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`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions` | `ReactNode` |  | Buttons at the end of the header, such as a call button or a menu. |
| `avatar` | `string` |  | The group's own picture, in place of its members' faces once it loads. Read only for a group chat. |
| `backLabel` | `string` | `"Back"` | What screen readers hear for the back button, for other languages. |
| `className` | `string` |  | Layout only: margins, padding, width (`px-4 py-2`). Appearance classes warn in development. |
| `level` | `1 \| 2 \| 3 \| 4` | `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) | `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` | `((count: number) => string)` | `` (count) => `${count} members` `` | What screen readers hear for the member list's button, from the count, for other languages. |
| `membersTitle` | `string` | `"Members"` | The member list's title, for other languages. |
| `onBack` | `((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` | `((names: readonly string[]) => string)` | 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` | `Ref<HTMLDivElement>` |  | Reaches the rendered element. |
| `subtitle` | `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) | `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.

```ts
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.

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

### `ChatHeaderOwnProps`

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

```ts
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.

```ts
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.

```ts
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.

```ts
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.

```ts
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;
}
```
