Skip to content
WebJs
Menu

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

ME
Deploying to prod real quick.
R
It's 4:55 PM. On a Friday.
ME
It's a one-line change.
R
It's always a one-line change 😭.
Alright, let me take a look.
👍
Oliver is typing...
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>
  `;
}
View Code

Installation

pnpm dlx @webjsdev/ui add message

Usage

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';
<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. For the scroll container around a conversation, use Message Scroller.

Composition

Use the following composition to build a message:

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

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

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.

R @avatar
The build failed during dependency installation.
R @avatar
Can you share the exact error?
R @avatar
Here's the error from the logs
Something went wrong with the build. The libraries are not installed correctly. Try running the build again.
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>
  `;
}
View Code
data-alignDescription
startAlign the message to the start of the conversation.
endAlign 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.

I checked the registry addresses.
CN @avatar
The component and example JSON now live under the UI registry.
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>
  `;
}
View Code

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

Olivia
I already checked the logs.
Send the report to the team. Ping @vivek if you need help.
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>
  `;
}
View Code

Actions

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

The install failure is coming from the workspace package.
Okay drop me a link. Taking a look...
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>
  `;
}
View Code

Attachment

Workspace
Here's the image. Can you add it to the PDF? Use it for the cover page.
Done. Here's the PDF with the image added as the cover page.
sales-dashboard.pdf PDF · 2.4 MB
Thanks. Looks good.
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>
  `;
}
View Code

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.

<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 with role="status" so assistive tech announces the update as it appears.

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

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