# Message

Displays a message in a conversation, with optional avatar, header, footer, and alignment.

Source: https://webjs.dev/ui/docs/components/message

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { avatarClass, avatarFallbackClass, avatarImageClass } from '#components/ui/avatar.ts';
import {
  bubbleClass, bubbleContentClass, bubbleGroupClass, bubbleReactionsClass,
} from '#components/ui/bubble.ts';
import { markerClass, markerContentClass } from '#components/ui/marker.ts';
import {
  messageClass, messageAvatarClass, messageContentClass, messageFooterClass,
} from '#components/ui/message.ts';

// Radix's Avatar shows the image once it loads and the fallback otherwise.
// With no script the two are stacked instead: the fallback fills the circle
// and the image paints over it, so a missing image leaves the initials.
const avatar = (src: string, fallback: string) => html`
  <span data-slot="avatar" data-size="default" class=${avatarClass()}>
    <span data-slot="avatar-fallback" class=${cn(avatarFallbackClass(), 'absolute inset-0')}>${fallback}</span>
    <img data-slot="avatar-image" src=${src} alt="" class=${cn(avatarImageClass(), 'relative')}>
  </span>
`;

export default function MessageDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-6 py-12">
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-avatar" class=${messageAvatarClass()}>
          ${avatar('/avatars/10.png', 'ME')}
        </div>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="default" data-align="start" class=${bubbleClass()}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>Deploying to prod real quick.</div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-avatar" class=${messageAvatarClass()}>
          ${avatar('/avatars/02.png', 'R')}
        </div>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>It's 4:55 PM. On a Friday.</div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-avatar" class=${messageAvatarClass()}>
          ${avatar('/avatars/10.png', 'ME')}
        </div>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="default" data-align="start" class=${bubbleClass()}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>It's a one-line change.</div>
          </div>
          <div data-slot="message-footer" class=${messageFooterClass()}>Delivered</div>
        </div>
      </div>
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-avatar" class=${messageAvatarClass()}>
          ${avatar('/avatars/02.png', 'R')}
        </div>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble-group" class=${bubbleGroupClass()}>
            <div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
              <div data-slot="bubble-content" class=${bubbleContentClass()}>
                It's always a one-line change 😭.
              </div>
            </div>
            <div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
              <div data-slot="bubble-content" class=${bubbleContentClass()}>Alright, let me take a look.</div>
              <div data-slot="bubble-reactions" data-align="end" data-side="bottom" aria-label="Reactions: thumbs up" class=${bubbleReactionsClass()}>
                <span>👍</span>
              </div>
            </div>
          </div>
        </div>
      </div>
      <div data-slot="marker" data-variant="default" role="status" class=${markerClass()}>
        <span data-slot="marker-content" class=${cn(markerContentClass(), 'shimmer')}>
          <span class="font-medium">Oliver</span> is typing...
        </span>
      </div>
    </div>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add message
```

### Copy and paste the following code into your project.

````ts title="components/ui/message.ts"
/**
 * Message: one entry in a conversation (a chat bubble with its avatar,
 * header and footer), and the group that stacks several. Tier-1 class
 * helper; compose with plain elements, and pair with the bubble helpers for
 * the speech bubble itself.
 *
 * shadcn parity:
 *   MessageGroup     → messageGroupClass()
 *   Message          → messageClass(), with data-align="start" | "end"
 *   MessageAvatar    → messageAvatarClass()
 *   MessageContent   → messageContentClass()
 *   MessageHeader    → messageHeaderClass()
 *   MessageFooter    → messageFooterClass()
 *
 * `data-align="end"` on the message mirrors it to the inline end (the user's
 * own messages), and the footer follows. Alignment is logical, so it flips
 * under `dir="rtl"`.
 *
 * A11y (required for accessible output): render the conversation as a list
 * (`<ol>` of messages, or `role="log"` on the container when new messages
 * arrive live, which also makes them announced). Each message should say who
 * sent it in text a screen reader reaches, the header or a visually hidden
 * name, and an avatar image needs `alt` (or `alt=""` when the name is
 * already in the header).
 *
 * Design tokens used: --muted, --muted-foreground.
 *
 * @example
 * ```html
 * <ol class=${messageGroupClass()} role="log" aria-label="Conversation">
 *   <li class=${messageClass()} data-align="end">
 *     <div class=${messageContentClass()}>
 *       <div class=${messageHeaderClass()}>You</div>
 *       <p>Can you ship it today?</p>
 *     </div>
 *   </li>
 * </ol>
 * ```
 */

/** The stack of messages. */
export function messageGroupClass(): string {
  return 'gap-2 flex min-w-0 flex-col';
}

/** One message row. `data-align="end"` mirrors it to the inline end. */
export function messageClass(): string {
  return 'gap-2 text-sm group/message relative flex w-full min-w-0 data-[align=end]:flex-row-reverse';
}

/** The sender's avatar beside the message. */
export function messageAvatarClass(): string {
  return 'min-w-8 group-has-data-[slot=message-footer]/message:-translate-y-8 flex w-fit shrink-0 items-center justify-center self-end overflow-hidden rounded-full bg-muted';
}

/** The column holding the header, the bubble and the footer. */
export function messageContentClass(): string {
  return 'gap-2.5 group-data-[align=end]/message:*:data-slot:self-end flex w-full min-w-0 flex-col wrap-break-word';
}

/** The sender name and time above the bubble. */
export function messageHeaderClass(): string {
  return 'px-3 text-xs font-medium text-muted-foreground group-has-data-[variant=ghost]/message:px-0 flex max-w-full min-w-0 items-center';
}

/** Actions or status below the bubble. */
export function messageFooterClass(): string {
  return 'px-3 text-xs font-medium text-muted-foreground group-has-data-[variant=ghost]/message:px-0 flex max-w-full min-w-0 items-center group-data-[align=end]/message:justify-end';
}
````

### Update the import paths to match your project setup.

## Usage

```ts
import { avatarClass, avatarFallbackClass, avatarImageClass } from '#components/ui/avatar.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { messageClass, messageAvatarClass, messageContentClass } from '#components/ui/message.ts';
```

```ts
<div data-slot="message" data-align="start" class=${messageClass()}>
  <div data-slot="message-avatar" class=${messageAvatarClass()}>
    <span data-slot="avatar" class=${avatarClass()}>
      <img data-slot="avatar-image" src="/avatars/vivek.jpg" alt="@vivek" class=${avatarImageClass()}>
    </span>
  </div>
  <div data-slot="message-content" class=${messageContentClass()}>
    <div data-slot="bubble" data-variant="default" class=${bubbleClass()}>
      <div data-slot="bubble-content" class=${bubbleContentClass()}>How can I help you today?</div>
    </div>
  </div>
</div>
```

**Note:** the message owns the row layout: avatar, alignment, header, and footer. Render the visible message surface inside it with [Bubble](https://webjs.dev/ui/docs/components/bubble). For the scroll container around a conversation, use [Message Scroller](https://webjs.dev/ui/docs/components/message-scroller).

## Composition

Use the following composition to build a message:

```text
messageClass()
├── messageAvatarClass()
└── messageContentClass()
    ├── messageHeaderClass()
    ├── bubbleClass()
    └── messageFooterClass()
```

Use `messageGroupClass()` to stack consecutive messages from the same sender:

```text
messageGroupClass()
├── messageClass()
└── messageClass()
```

## Features

- Start and end alignment for sender and receiver rows via the `data-align` attribute
- Avatar slot that anchors to the bottom of the message and stays clear of the footer
- Header and footer slots for sender names, status, and message actions
- Footer follows the message side; actions stay aligned on `data-align="end"` rows
- Group wrapper for stacking consecutive messages from the same sender
- Customizable styling by merging classes into each helper's result with `cn`

## Avatar

Use `messageAvatarClass()` to render an avatar next to the message. Set `data-align="end"` on the message to align the avatar to the end of the message.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { avatarClass, avatarFallbackClass, avatarImageClass } from '#components/ui/avatar.ts';
import { bubbleClass, bubbleContentClass, bubbleGroupClass } from '#components/ui/bubble.ts';
import { messageClass, messageAvatarClass, messageContentClass } from '#components/ui/message.ts';

// The fallback fills the circle and the image paints over it, so a missing
// image leaves the initials.
const avatar = (src: string, fallback: string) => html`
  <span data-slot="avatar" data-size="default" class=${avatarClass()}>
    <span data-slot="avatar-fallback" class=${cn(avatarFallbackClass(), 'absolute inset-0')}>${fallback}</span>
    <img data-slot="avatar-image" src=${src} alt="@avatar" class=${cn(avatarImageClass(), 'relative')}>
  </span>
`;

export default function MessageAvatarDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-6 py-12">
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-avatar" class=${messageAvatarClass()}>
          ${avatar('/avatars/03.png', 'R')}
        </div>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>
              The build failed during dependency installation.
            </div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-avatar" class=${messageAvatarClass()}>
          ${avatar('/avatars/10.png', 'R')}
        </div>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="default" data-align="start" class=${bubbleClass()}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>Can you share the exact error?</div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-avatar" class=${messageAvatarClass()}>
          ${avatar('/avatars/03.png', 'R')}
        </div>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble-group" class=${bubbleGroupClass()}>
            <div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
              <div data-slot="bubble-content" class=${bubbleContentClass()}>Here's the error from the logs</div>
            </div>
            <div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
              <div data-slot="bubble-content" class=${bubbleContentClass()}>
                Something went wrong with the build. The libraries are not
                installed correctly. Try running the build again.
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  `;
}
```

| data-align | Description |
| --- | --- |
| `start` | Align the message to the start of the conversation. |
| `end` | Align the message to the end of the conversation. |

## Group

Use `messageGroupClass()` to stack consecutive messages from the same sender. Render an empty avatar slot on the earlier messages to keep them aligned with the avatar on the last one.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { avatarClass, avatarFallbackClass, avatarImageClass } from '#components/ui/avatar.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import {
  messageClass, messageAvatarClass, messageContentClass, messageGroupClass,
} from '#components/ui/message.ts';

export default function MessageGroupDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-6 py-12">
      <div data-slot="message-group" class=${messageGroupClass()}>
        <div data-slot="message" data-align="start" class=${messageClass()}>
          <div data-slot="message-avatar" class=${messageAvatarClass()}></div>
          <div data-slot="message-content" class=${messageContentClass()}>
            <div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
              <div data-slot="bubble-content" class=${bubbleContentClass()}>I checked the registry addresses.</div>
            </div>
          </div>
        </div>
        <div data-slot="message" data-align="start" class=${messageClass()}>
          <div data-slot="message-avatar" class=${messageAvatarClass()}>
            <span data-slot="avatar" data-size="default" class=${avatarClass()}>
              <span data-slot="avatar-fallback" class=${cn(avatarFallbackClass(), 'absolute inset-0')}>CN</span>
              <img data-slot="avatar-image" src="/avatars/02.png" alt="@avatar" class=${cn(avatarImageClass(), 'relative')}>
            </span>
          </div>
          <div data-slot="message-content" class=${messageContentClass()}>
            <div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
              <div data-slot="bubble-content" class=${bubbleContentClass()}>
                The component and example JSON now live under the UI registry.
              </div>
            </div>
          </div>
        </div>
      </div>
    </div>
  `;
}
```

## Header and Footer

Use `messageHeaderClass()` for a sender name and `messageFooterClass()` for metadata such as a delivery or read status.

```ts
import { html } from '@webjsdev/core';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import {
  messageClass, messageContentClass, messageFooterClass, messageHeaderClass,
} from '#components/ui/message.ts';

export default function MessageHeaderFooterDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-8 py-12">
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="message-header" class=${messageHeaderClass()}>Olivia</div>
          <div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>I already checked the logs.</div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="default" data-align="start" class=${bubbleClass()}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>
              Send the report to the team. Ping @vivek if you need help.
            </div>
          </div>
          <div data-slot="message-footer" class=${messageFooterClass()}>
            <div>
              Read <span class="font-normal">Yesterday</span>
            </div>
          </div>
        </div>
      </div>
    </div>
  `;
}
```

## Actions

Place message-level actions in the footer, such as copy, retry, or feedback buttons.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import { messageClass, messageContentClass, messageFooterClass } from '#components/ui/message.ts';
import { CopyIcon, RefreshCcwIcon, ThumbsDownIcon, ThumbsUpIcon } from '#lib/ui/lucide.ts';

export default function MessageActionsDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-8 py-12">
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>
              The install failure is coming from the workspace package.
            </div>
          </div>
          <div data-slot="message-footer" class=${messageFooterClass()}>
            <button type="button" data-slot="button" data-variant="ghost" data-size="icon" aria-label="Copy" title="Copy" class=${buttonClass({ variant: 'ghost', size: 'icon' })}>
              ${CopyIcon()}
            </button>
            <button type="button" data-slot="button" data-variant="ghost" data-size="icon" aria-label="Like" title="Like" class=${buttonClass({ variant: 'ghost', size: 'icon' })}>
              ${ThumbsUpIcon()}
            </button>
            <button type="button" data-slot="button" data-variant="ghost" data-size="icon" aria-label="Dislike" title="Dislike" class=${buttonClass({ variant: 'ghost', size: 'icon' })}>
              ${ThumbsDownIcon()}
            </button>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="default" data-align="start" class=${bubbleClass()}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>Okay drop me a link. Taking a look...</div>
          </div>
          <div data-slot="message-footer" class=${cn(messageFooterClass(), 'gap-2')}>
            <span class="font-normal text-destructive">Failed to send</span>
            <button type="button" data-slot="button" data-variant="ghost" data-size="icon-xs" title="Retry" aria-label="Retry" class=${buttonClass({ variant: 'ghost', size: 'icon-xs' })}>
              ${RefreshCcwIcon()}
            </button>
          </div>
        </div>
      </div>
    </div>
  `;
}
```

## Attachment

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import {
  attachmentClass, attachmentMediaClass, attachmentContentClass, attachmentTitleClass,
  attachmentDescriptionClass, attachmentActionsClass, attachmentActionClass,
} from '#components/ui/attachment.ts';
import { bubbleClass, bubbleContentClass } from '#components/ui/bubble.ts';
import { buttonClass } from '#components/ui/button.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import { DownloadIcon, FileTextIcon } from '#lib/ui/lucide.ts';

export default function MessageAttachmentDemo() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-8 py-12">
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="attachment" data-state="done" data-size="default" data-orientation="vertical" class=${attachmentClass({ orientation: 'vertical' })}>
            <div data-slot="attachment-media" data-variant="image" class=${attachmentMediaClass({ variant: 'image' })}>
              <img
                src="https://images.unsplash.com/photo-1497366754035-f200968a6e72?w=900&auto=format&fit=crop&q=80"
                alt="Workspace"
              >
            </div>
          </div>
          <div data-slot="bubble" data-variant="default" data-align="start" class=${bubbleClass()}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>
              Here's the image. Can you add it to the PDF? Use it for the
              cover page.
            </div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="muted" data-align="start" class=${bubbleClass({ variant: 'muted' })}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>
              Done. Here's the PDF with the image added as the cover page.
            </div>
          </div>
          <div data-slot="attachment" data-state="done" data-size="default" data-orientation="horizontal" class=${attachmentClass()}>
            <div data-slot="attachment-media" data-variant="icon" class=${attachmentMediaClass()}>
              ${FileTextIcon()}
            </div>
            <div data-slot="attachment-content" class=${attachmentContentClass()}>
              <span data-slot="attachment-title" class=${attachmentTitleClass()}>sales-dashboard.pdf</span>
              <span data-slot="attachment-description" class=${attachmentDescriptionClass()}>PDF · 2.4 MB</span>
            </div>
            <div data-slot="attachment-actions" class=${attachmentActionsClass()}>
              <button type="button" data-slot="attachment-action" data-variant="secondary" data-size="icon-sm" title="Download" aria-label="Download" class=${cn(buttonClass({ variant: 'secondary', size: 'icon-sm' }), attachmentActionClass())}>
                ${DownloadIcon()}
              </button>
            </div>
          </div>
        </div>
      </div>
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="default" data-align="start" class=${bubbleClass()}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>Thanks. Looks good.</div>
          </div>
        </div>
      </div>
    </div>
  `;
}
```

## Accessibility

A message is a presentational layout wrapper. Accessibility comes from the content you place inside it.

### Label icon-only actions

Action buttons in the footer are usually icon-only, so give each one an `aria-label`.

```ts
<div data-slot="message-footer" class=${messageFooterClass()}>
  <button type="button" aria-label="Copy" class=${buttonClass({ variant: 'ghost', size: 'icon' })}>
    ${CopyIcon()}
  </button>
</div>
```

### Status updates

For in-progress messages, use a [Marker](https://webjs.dev/ui/docs/components/marker) with `role="status"` so assistive tech announces the update as it appears.

```ts
<div data-slot="message" data-align="start" class=${messageClass()}>
  <div data-slot="marker" data-variant="default" role="status" class=${markerClass()}>
    <span data-slot="marker-icon" aria-hidden="true" class=${markerIconClass()}>
      ${spinner({ decorative: true })}
    </span>
    <span data-slot="marker-content" class=${markerContentClass()}>Checking the logs...</span>
  </div>
</div>
```

## API Reference

Every part is a class helper that takes no options. Put its classes on a plain element, and merge your own classes into the result with `cn`.

### messageClass

The message row wrapper.

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `data-align` | `"start" \| "end"` | `"start"` | The alignment of the message in the conversation. Alignment is logical, so it flips under `dir="rtl"`. |

### messageGroupClass

Groups consecutive messages from the same sender.

### messageAvatarClass

The avatar slot, aligned to the bottom of the message. When the message has a footer, the avatar shifts up to stay aligned with the message surface instead of the footer.

### messageContentClass

Wraps the header, message surface, and footer.

### messageHeaderClass

Displays content above the message, such as a sender name. Stays aligned to the start regardless of `data-align`.

### messageFooterClass

Displays content below the message, such as status or actions. Aligns to the message side.
