# Chat

The thread. Message Scroller keeps your place while the reply streams.

Source: https://webjs.dev/ui/docs/ai-elements/chat

```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 {
  codeBlockClass, codeBlockContentClass, codeBlockCodeClass,
} from '#components/ui/code-block.ts';
import {
  inputGroupClass, inputGroupAddonClass, inputGroupButtonClass, inputGroupTextareaClass,
} from '#components/ui/input-group.ts';
import { messageClass, messageContentClass } from '#components/ui/message.ts';
import {
  traceClass, traceLineClass, traceIconClass, traceTitleClass,
  traceCollapsibleClass, traceCollapsibleTriggerClass, traceCollapsibleContentClass,
} from '#components/ui/trace.ts';
import {
  ArrowUpIcon, ChevronRightIcon, CircleCheckIcon, GlobeIcon, PaperclipIcon,
  PlusIcon, RotateCwIcon, TelescopeIcon, TerminalIcon,
} from '#lib/ui/lucide.ts';

type Step =
  | { type: 'reasoning'; text: string }
  | { type: 'tool'; command: string; stdout: string };

type Turn = { question: string; steps: Step[]; reply: unknown };

const code = (text: string) => html`<code class="rounded-md bg-muted px-1 py-0.5 font-mono text-[0.85em]">${text}</code>`;

const codeBlock = (text: string) => html`
  <div data-slot="code-block" data-variant="default" data-size="sm" class=${codeBlockClass()}>
    <pre data-slot="code-block-content" tabindex="0" dir="ltr" style="counter-reset: line 0" class=${codeBlockContentClass()}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${text}</code></pre>
  </div>`;

// shadcn's scripted conversation, settled. The replies are Markdown in
// shadcn's demo; the kit has no Markdown renderer, so they are written out
// as the HTML it would produce.
const turns: Turn[] = [
  {
    question: 'Add a dark mode toggle to the settings page.',
    steps: [
      { type: 'reasoning', text: 'I need to know how themes are set up before I add a toggle. If next-themes is already in the layout, the toggle only has to call setTheme.' },
      { type: 'tool', command: 'rg -l ThemeProvider app', stdout: 'app/layout.tsx' },
    ],
    reply: html`
      <p>next-themes is already set up in ${code('app/layout.tsx')}, so the toggle only has to call ${code('setTheme')}.</p>
      <p><strong>Changes</strong></p>
      <ul class="list-disc space-y-1 ps-5">
        <li>Added ${code('components/mode-toggle.tsx')} with a Light and Dark option.</li>
        <li>Put ${code('<ModeToggle />')} next to the Appearance heading in ${code('app/settings/page.tsx')}.</li>
      </ul>
      ${codeBlock('const { setTheme } = useTheme()')}`,
  },
  {
    question: 'Make it follow the system setting by default.',
    steps: [
      { type: 'reasoning', text: 'The default theme lives on the ThemeProvider. I should check what it is set to now.' },
      { type: 'tool', command: 'rg -n defaultTheme app/layout.tsx', stdout: '12:  <ThemeProvider attribute="class" defaultTheme="light">' },
    ],
    reply: html`
      <p>It was set to ${code('light')}. I updated the ${code('ThemeProvider')} in ${code('app/layout.tsx')}:</p>
      ${codeBlock('<ThemeProvider attribute="class" defaultTheme="system" enableSystem>')}
      <p>New visitors now get the theme from their OS. The toggle also has a <strong>System</strong> option, so anyone who picked Light or Dark can switch back.</p>`,
  },
  {
    question: 'Run the build before I ship it.',
    steps: [
      { type: 'tool', command: 'pnpm build', stdout: '▲ Next.js 16.0.0\n\n✓ Compiled successfully in 4.2s\n✓ Linting and checking validity of types\n✓ Generating static pages (12/12)' },
    ],
    reply: html`
      <p>The build passes, so it is ready to ship.</p>
      <ul class="list-disc space-y-1 ps-5">
        <li>Compiled in <strong>4.2s</strong>.</li>
        <li>No lint or type errors.</li>
        <li>Generated all <strong>12</strong> static pages.</li>
      </ul>`,
  },
];

const chevron = () => html`<span data-slot="trace-icon" aria-hidden="true" class=${cn(traceIconClass(), 'transition-transform group-open/trace-collapsible:rotate-90')}>${ChevronRightIcon()}</span>`;

function stepRow(step: Step) {
  if (step.type === 'reasoning') {
    return html`
      <details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
        <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
          <span data-slot="trace-line" class=${traceLineClass()}>
            <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${CircleCheckIcon()}</span>
            <span data-slot="trace-title" class=${traceTitleClass()}>Thought</span>
          </span>
          ${chevron()}
        </summary>
        <div data-slot="trace-collapsible-content" class=${cn(traceCollapsibleContentClass(), 'whitespace-pre-wrap')}>${step.text}</div>
      </details>`;
  }
  return html`
    <details data-slot="trace-collapsible" class=${cn(traceCollapsibleClass(), 'group/trace-collapsible')}>
      <summary data-slot="trace-collapsible-trigger" class=${traceCollapsibleTriggerClass()}>
        <span data-slot="trace-line" class=${traceLineClass()}>
          <span data-slot="trace-icon" aria-hidden="true" class=${traceIconClass()}>${TerminalIcon()}</span>
          <span data-slot="trace-title" class=${traceTitleClass()}>Ran ${step.command}</span>
        </span>
        ${chevron()}
      </summary>
      <div data-slot="trace-collapsible-content" class=${traceCollapsibleContentClass()}>
        <div data-slot="code-block" data-variant="default" data-size="sm" class=${codeBlockClass()}>
          <pre data-slot="code-block-content" data-wrap tabindex="0" dir="ltr" style="counter-reset: line 0" class=${cn(codeBlockContentClass(), 'max-h-64')}><code data-slot="code-block-code" class=${codeBlockCodeClass()}>${step.stdout}</code></pre>
        </div>
      </div>
    </details>`;
}

function turn(t: Turn, i: number) {
  return html`
    <ui-message-scroller-item message-id=${`user-${i}`} scroll-anchor>
      <div data-slot="message" data-align="end" class=${messageClass()}>
        <div data-slot="message-content" class=${messageContentClass()}>
          <div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
            <div data-slot="bubble-content" class=${bubbleContentClass()}>${t.question}</div>
          </div>
        </div>
      </div>
    </ui-message-scroller-item>
    <ui-message-scroller-item message-id=${`assistant-${i}`}>
      <div data-slot="message" data-align="start" class=${messageClass()}>
        <div data-slot="message-content" class=${cn(messageContentClass(), 'gap-3')}>
          <div data-slot="trace" class=${traceClass()}>${t.steps.map(stepRow)}</div>
          <div class="flex flex-col gap-3">${t.reply}</div>
        </div>
      </div>
    </ui-message-scroller-item>`;
}

// The thread once every scripted turn has been sent: the scroller opens at
// the newest message. Sending, Reset and the add menu's items are the
// reader's to wire (see the AI SDK helper page).
export default function ChatDemo() {
  return html`
    <div class="relative flex w-full flex-col gap-4 [[data-slot=preview]:has(&)]:bg-background [[data-slot=preview]:has(&)>div]:p-0!">
      <div class="flex h-200 w-full flex-col gap-4">
        <div class="flex items-start justify-between gap-4 p-8 pb-4">
          <div class="flex flex-col gap-1">
            <div class="font-medium">New Thread</div>
            <div class="text-sm text-muted-foreground">Ask the agent to change your code.</div>
          </div>
          <ui-tooltip>
            <ui-tooltip-trigger>
              <button type="button" data-slot="button" data-variant="outline" data-size="icon" aria-label="Reset conversation" class=${buttonClass({ variant: 'outline', size: 'icon' })}>${RotateCwIcon()}</button>
            </ui-tooltip-trigger>
            <ui-tooltip-content><p>Reset</p></ui-tooltip-content>
          </ui-tooltip>
        </div>
        <div class="min-h-0 flex-1">
          <ui-message-scroller>
            <ui-message-scroller-viewport>
              <ui-message-scroller-content aria-label="Conversation" class="gap-6 px-8 py-0">
                ${turns.map(turn)}
              </ui-message-scroller-content>
            </ui-message-scroller-viewport>
            <ui-message-scroller-button></ui-message-scroller-button>
          </ui-message-scroller>
        </div>
        <div class="p-8 pt-0">
          <form class="w-full">
            <div data-slot="input-group" role="group" class=${inputGroupClass()}>
              <textarea data-slot="input-group-control" name="text" placeholder="Ask the agent..." aria-label="Message" class=${cn(inputGroupTextareaClass(), 'min-h-14')}></textarea>
              <div role="group" data-slot="input-group-addon" data-align="block-end" class=${cn(inputGroupAddonClass({ align: 'block-end' }), 'pt-1')}>
                <ui-dropdown-menu>
                  <ui-dropdown-menu-trigger>
                    <button type="button" aria-label="Add context" data-slot="button" data-variant="outline" data-size="icon-sm" class=${inputGroupButtonClass({ variant: 'outline', size: 'icon-sm' })}>${PlusIcon()}</button>
                  </ui-dropdown-menu-trigger>
                  <ui-dropdown-menu-content align="start" side="top" class="w-44">
                    <ui-dropdown-menu-item>${PaperclipIcon()}Add Photos &amp; Files</ui-dropdown-menu-item>
                    <ui-dropdown-menu-separator></ui-dropdown-menu-separator>
                    <ui-dropdown-menu-item>${TelescopeIcon()}Deep Research</ui-dropdown-menu-item>
                    <ui-dropdown-menu-item>${GlobeIcon()}Web Search</ui-dropdown-menu-item>
                  </ui-dropdown-menu-content>
                </ui-dropdown-menu>
                <button type="submit" disabled data-slot="button" data-variant="default" data-size="icon-sm" class=${cn(inputGroupButtonClass({ variant: 'default', size: 'icon-sm' }), 'ml-auto')}>
                  ${ArrowUpIcon()}<span class="sr-only">Send</span>
                </button>
              </div>
            </div>
          </form>
        </div>
      </div>
    </div>
  `;
}
```

Chat is the thread of a conversation with the agent. Each turn is a [Message](https://webjs.dev/ui/docs/ai-elements/message) inside [Message Scroller](https://webjs.dev/ui/docs/components/message-scroller). The person's message is the scroll anchor, so a new question settles near the top and the reply streams in under it. The field is a [Prompt Input](https://webjs.dev/ui/docs/ai-elements/prompt-input).

## Installation

Chat is built with the [Message Scroller](https://webjs.dev/ui/docs/components/message-scroller), [Message](https://webjs.dev/ui/docs/components/message), [Bubble](https://webjs.dev/ui/docs/components/bubble), and [Input Group](https://webjs.dev/ui/docs/components/input-group) components.

```bash
npx @webjsdev/ui add message-scroller message bubble input-group
```

### Install the following dependencies:

```bash
npx @webjsdev/ui add message-scroller message bubble input-group
```

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

````ts title="components/ui/message-scroller.ts"
/**
 * Message scroller: the scroll container for a chat transcript. Tier-2. A
 * port of shadcn's MessageScroller (the headless primitive in
 * `@shadcn/react`, styled): it opens at the newest message, follows new ones
 * while the reader is at the end, leaves them where they are once they have
 * scrolled up, and offers a button back to the end.
 *
 * shadcn parity:
 *   MessageScroller.Provider + MessageScroller
 *                            → <ui-message-scroller auto-scroll default-scroll-position
 *                                scroll-edge-threshold scroll-previous-item-peek>
 *   MessageScrollerViewport  → <ui-message-scroller-viewport>
 *   MessageScrollerContent   → <ui-message-scroller-content> (a role="log")
 *   MessageScrollerItem (messageId, scrollAnchor)
 *                            → <ui-message-scroller-item message-id scroll-anchor>
 *   MessageScrollerButton direction, children
 *                            → <ui-message-scroller-button direction="end" | "start" label>,
 *                              its children in place of the arrow
 *   useMessageScroller()     → the element: scrollToEnd(), scrollToStart(), scrollToMessage(id)
 *   useMessageScrollerScrollable()
 *                            → `scrollable` ({ start, end }) and `ui-scrollable-change`
 *   useMessageScrollerVisibility()
 *                            → `visibleMessageIds` and `ui-visibility-change`
 *
 * `default-scroll-position` is where it opens: "end" (the default), "start",
 * or "last-anchor", the last item marked `scroll-anchor` at the top (a new
 * question with the answer streaming in under it). The transcript is always
 * served visible, so it reads with JavaScript off (the opening position is
 * then the start, the browser's own). A scroller the browser builds on the
 * client, which has never painted, is held invisible until that position
 * applies, so the reader never sees a jump; one the server rendered moves
 * to it once its script runs.
 * After that, an item that ARRIVES marked `scroll-anchor` (the question a
 * reader just sent) settles near the top with `scroll-previous-item-peek`
 * pixels (64 by default, shadcn's) of the previous turn still in view, and stays there while the reply streams in below it: a
 * tail spacer at the end of the list makes the room, and shrinks as the
 * reply grows. Once the reply fills the viewport, `auto-scroll` follows it.
 * Messages added at the top keep the reader's place through the browser's
 * own scroll anchoring. `scroll-edge-threshold` (8 pixels by default,
 * shadcn's) is how near an edge counts as being at it: what keeps the
 * scroller following, and what shows the button.
 *
 * A11y (handled by the element, plus your part): the content is a
 * `role="log"` that announces additions, and the button is named "Scroll to
 * end" / "Scroll to start" (or its `label`) and is inert while there is
 * nowhere to go. Your
 * part: label the transcript (`aria-label` on `<ui-message-scroller-content>`).
 *
 * @example
 * ```html
 * <ui-message-scroller auto-scroll class="h-96">
 *   <ui-message-scroller-viewport>
 *     <ui-message-scroller-content aria-label="Conversation">
 *       <ui-message-scroller-item message-id="m1">Hello</ui-message-scroller-item>
 *       <ui-message-scroller-item message-id="m2" scroll-anchor>What is WebJs?</ui-message-scroller-item>
 *     </ui-message-scroller-content>
 *   </ui-message-scroller-viewport>
 *   <ui-message-scroller-button></ui-message-scroller-button>
 * </ui-message-scroller>
 * ```
 */
import { WebComponent, html, prop, signal, nothing } from '@webjsdev/core';
import { cn, takeAuthoredClass } from '../lib/utils.ts';
import { buttonClass, type ButtonVariant, type ButtonSize } from './button.ts';

/** The frame's classes (the element applies them). */
export const messageScrollerClass = (): string =>
  'group/message-scroller relative flex size-full min-h-0 flex-col overflow-hidden';
/** The scrolling viewport (the element applies them). */
export const messageScrollerViewportClass = (): string =>
  'size-full min-h-0 min-w-0 scroll-fade-b scrollbar-thin scrollbar-gutter-stable overflow-y-auto overscroll-contain contain-content data-autoscrolling:scrollbar-thumb-transparent data-autoscrolling:scrollbar-track-transparent data-[pending-scroll]:invisible';
/** The message list (the element applies them). */
export const messageScrollerContentClass = (): string =>
  'gap-6 flex h-max min-h-full flex-col';
/** One message (the element puts them on the item itself). */
export const messageScrollerItemClass = (): string =>
  'min-w-0 shrink-0 [contain-intrinsic-size:auto_10rem] [content-visibility:auto]';
/** The scroll button (the element applies them). */
export const messageScrollerButtonClass = (): string =>
  'absolute inset-s-1/2 -translate-x-1/2 border-border bg-background text-foreground transition-[translate,scale,opacity] duration-200 hover:bg-muted hover:text-foreground data-[active=false]:pointer-events-none data-[active=false]:scale-95 data-[active=false]:opacity-0 data-[active=false]:duration-400 data-[active=false]:ease-[cubic-bezier(0.7,0,0.84,0)] data-[active=true]:translate-y-0 data-[active=true]:scale-100 data-[active=true]:opacity-100 data-[active=true]:ease-[cubic-bezier(0.23,1,0.32,1)] data-[direction=end]:bottom-4 data-[direction=end]:data-[active=false]:translate-y-full data-[direction=start]:top-4 data-[direction=start]:data-[active=false]:-translate-y-full rtl:translate-x-1/2 data-[direction=start]:[&_svg]:rotate-180';

const ROOT = 'ui-message-scroller';
// How near an edge counts as being at it, in pixels, and how much of the
// previous turn stays in view above a newly anchored one: shadcn's defaults
// (DEFAULT_SCROLL_EDGE_THRESHOLD and DEFAULT_SCROLL_PREVIOUS_ITEM_PEEK).
const EDGE = 8;
const PEEK = 64;

// shadcn's className lands on the element each part renders (the frame, the
// viewport, the list, the button), so each host hands its authored class to
// that element and becomes display: contents. A block host would otherwise
// sit between the frame's flex column and the viewport, the viewport would
// grow to its content, and nothing would scroll.
function takeAuthored(part: HTMLElement): string | null {
  return takeAuthoredClass(part, 'contents');
}

function rootOf(el: Element): UiMessageScroller | null {
  return (typeof el.closest === 'function' ? el.closest(ROOT) : null) as UiMessageScroller | null;
}

// --------------------------------------------------------------------------
// <ui-message-scroller>
// --------------------------------------------------------------------------

export class UiMessageScroller extends WebComponent({
  autoScroll: prop(Boolean, { attribute: 'auto-scroll' }),
  defaultScrollPosition: prop<'end' | 'start' | 'last-anchor'>(String, { attribute: 'default-scroll-position' }),
  scrollEdgeThreshold: prop(Number, { attribute: 'scroll-edge-threshold' }),
  scrollPreviousItemPeek: prop(Number, { attribute: 'scroll-previous-item-peek' }),
}) {
  // Served visible: a transcript must read with JavaScript off.
  readonly pending = signal(false);
  /** The edges the viewport can still scroll toward. */
  scrollable = { start: false, end: false };
  /** The messages on screen, by `message-id`. */
  visibleMessageIds: string[] = [];
  _following = true;
  _opened = false;
  _resize: ResizeObserver | null = null;
  _visible: IntersectionObserver | null = null;
  _shown = new Set<string>();
  // Turn anchoring: the anchored items already placed, the one being held,
  // the scroll position that holds it, and the tail spacer's height.
  _anchored = new WeakSet<Element>();
  _held: Element | null = null;
  _heldTop = 0;
  _spacerHeight = 0;
  _growFrame = 0;

  constructor() {
    super();
    this.autoScroll = false;
    this.defaultScrollPosition = 'end';
    this.scrollEdgeThreshold = EDGE;
    this.scrollPreviousItemPeek = PEEK;
  }

  connectedCallback(): void {
    // A scroller built in the browser has not painted yet, so it is held
    // invisible until its opening position applies. One the server rendered
    // has painted already (its frame is in the markup), and hiding it now
    // would blank text the reader can see, so it moves in place instead.
    if (!this._opened && typeof this.querySelector === 'function' && !this.querySelector('[data-slot="message-scroller"]')) this.pending.set(true);
    super.connectedCallback?.();
    queueMicrotask(() => this._setup());
  }

  _edge(): number {
    const n = Number(this.scrollEdgeThreshold);
    return Number.isFinite(n) && n >= 0 ? n : EDGE;
  }

  _peek(): number {
    const n = Number(this.scrollPreviousItemPeek);
    return Number.isFinite(n) && n >= 0 ? n : PEEK;
  }

  disconnectedCallback(): void {
    cancelAnimationFrame(this._growFrame);
    this._resize?.disconnect();
    this._visible?.disconnect();
    this._resize = null;
    this._visible = null;
    super.disconnectedCallback?.();
  }

  render() {
    return html`<div data-slot="message-scroller" ?data-pending-scroll=${this.pending.get()} class=${cn(messageScrollerClass(), takeAuthored(this))}><slot></slot></div>`;
  }

  viewport(): HTMLElement | null {
    return this.querySelector<HTMLElement>('[data-slot="message-scroller-viewport"]');
  }

  _content(): HTMLElement | null {
    return this.querySelector<HTMLElement>('[data-slot="message-scroller-content"]');
  }

  _items(): UiMessageScrollerItem[] {
    if (typeof this.querySelectorAll !== 'function') return [];
    return Array.from(this.querySelectorAll<UiMessageScrollerItem>('ui-message-scroller-item')).filter((i) => rootOf(i) === this);
  }

  _setup(): void {
    const viewport = this.viewport();
    const content = this._content();
    if (!viewport || !content) {
      requestAnimationFrame(() => this._setup());
      return;
    }
    viewport.addEventListener('scroll', this._onScroll, { passive: true });
    // New or growing messages: follow them if the reader is at the end.
    if (typeof ResizeObserver === 'function') {
      // Following the end is decided at once, before the next frame's scroll
      // event can read the grown list as "scrolled away". The spacer is fitted
      // a frame later, since resizing it inside the observed content would
      // otherwise loop the observer; its own resize then comes back here.
      this._resize = new ResizeObserver(() => {
        this._onGrow();
        cancelAnimationFrame(this._growFrame);
        this._growFrame = requestAnimationFrame(() => this._fitSpacer());
      });
      this._resize.observe(content);
    }
    if (typeof IntersectionObserver === 'function') {
      this._visible = new IntersectionObserver(this._onIntersect, { root: viewport });
      for (const item of this._items()) this._visible.observe(item);
    }
    requestAnimationFrame(() => this._open());
  }

  // The opening position, applied once the messages have laid out.
  _open(): void {
    const viewport = this.viewport();
    if (!viewport) return;
    const pos = this.defaultScrollPosition;
    if (pos === 'start') viewport.scrollTop = 0;
    else if (pos === 'last-anchor') {
      const anchors = this._items().filter((i) => i.hasAttribute('scroll-anchor'));
      const last = anchors[anchors.length - 1];
      if (last) this._scrollToItem(last, 'start', 'auto');
      else viewport.scrollTop = viewport.scrollHeight;
    } else viewport.scrollTop = viewport.scrollHeight;
    this._opened = true;
    // The turns present at open are placed by the opening position.
    for (const item of this._items()) if (item.hasAttribute('scroll-anchor')) this._anchored.add(item);
    this._following = this._atEnd();
    this.pending.set(false);
    // The viewport draws its own pending flag, so it redraws with it.
    this.querySelector<UiMessageScrollerViewport>('ui-message-scroller-viewport')?.requestUpdate?.();
    this._measure();
  }

  _atEnd(): boolean {
    const v = this.viewport();
    return !!v && v.scrollHeight - v.scrollTop - v.clientHeight <= this._edge();
  }

  _onScroll = (): void => {
    // A scroll the reader makes away from the end stops the following; one
    // back to the end resumes it.
    if (this._opened) this._following = this._atEnd();
    this._measure();
  };

  _onGrow = (): void => {
    if (!this._opened) return;
    if (this.autoScroll && this._following) {
      const v = this.viewport();
      if (v) {
        v.setAttribute('data-autoscrolling', '');
        v.scrollTop = v.scrollHeight;
        requestAnimationFrame(() => v.removeAttribute('data-autoscrolling'));
      }
    }
    this._measure();
  };

  _measure(): void {
    const v = this.viewport();
    if (!v) return;
    const edge = this._edge();
    const next = { start: v.scrollTop > edge, end: v.scrollHeight - v.scrollTop - v.clientHeight > edge };
    if (next.start !== this.scrollable.start || next.end !== this.scrollable.end) {
      this.scrollable = next;
      this.dispatchEvent(new CustomEvent('ui-scrollable-change', { bubbles: true, detail: { ...next } }));
    }
    for (const b of Array.from(this.querySelectorAll<UiMessageScrollerButton>('ui-message-scroller-button'))) b.requestUpdate?.();
  }

  _onIntersect = (entries: IntersectionObserverEntry[]): void => {
    for (const e of entries) {
      const id = (e.target as Element).getAttribute('message-id');
      if (!id) continue;
      if (e.isIntersecting) this._shown.add(id);
      else this._shown.delete(id);
    }
    const ids = this._items().map((i) => i.getAttribute('message-id')).filter((id): id is string => !!id && this._shown.has(id));
    this.visibleMessageIds = ids;
    this.dispatchEvent(new CustomEvent('ui-visibility-change', { bubbles: true, detail: { visibleMessageIds: ids } }));
  };

  // An item that arrives after setup is tracked too.
  _itemConnected(item: UiMessageScrollerItem): void {
    this._visible?.observe(item);
    // A new turn marked scroll-anchor settles near the top, a peek of the
    // previous turn above it, as shadcn's does. Placed once per item, since
    // an item can connect again when the list re-renders around it.
    if (this._opened && item.hasAttribute('scroll-anchor') && !this._anchored.has(item)) {
      this._anchored.add(item);
      requestAnimationFrame(() => this._anchorTurn(item));
    }
  }

  _spacer(): HTMLElement | null {
    return this.querySelector<HTMLElement>('[data-message-scroller-spacer]');
  }

  // Scroll a new anchored turn to the top, keeping the peek of the turn
  // before it, with room made below by the tail spacer when the conversation
  // is still too short to scroll that far.
  _anchorTurn(item: Element): void {
    const v = this.viewport();
    const content = this._content();
    if (!v || !content || !item.isConnected) return;
    const pad = parseFloat(getComputedStyle(content).paddingTop) || 0;
    // Where the turn sits in the layout, read through offsetTop so a
    // transform on it (an entrance sliding it up) does not move the target.
    const listTop = v.scrollTop + content.getBoundingClientRect().top - v.getBoundingClientRect().top;
    const top = listTop + (item as HTMLElement).offsetTop - content.offsetTop;
    this._held = item;
    this._heldTop = Math.max(0, top - pad - this._peek());
    this._fitSpacer();
    v.scrollTo({ top: this._heldTop, behavior: this._behavior() });
  }

  // The spacer fills exactly the room the held turn needs below it, so it
  // shrinks as the reply streams in and the turn stays where it is. Once the
  // reply fills the viewport the spacer is gone, and a following viewport
  // (auto-scroll) takes over from the end.
  _fitSpacer(): void {
    const v = this.viewport();
    const spacer = this._spacer();
    if (!v || !spacer) return;
    if (this._held && !this._held.isConnected) this._held = null;
    const natural = v.scrollHeight - this._spacerHeight;
    const next = this._held ? Math.max(0, Math.ceil(this._heldTop + v.clientHeight - natural)) : 0;
    if (next === this._spacerHeight) return;
    this._spacerHeight = next;
    if (next === 0) this._held = null;
    const content = this._content();
    const gap = content ? parseFloat(getComputedStyle(content).rowGap) || 0 : 0;
    spacer.hidden = next === 0;
    spacer.style.height = `${next}px`;
    // The list's flex gap would add itself above the spacer, so it is taken
    // back. The spacer is never the browser's scroll anchor (overflow-anchor:
    // none): it is the last thing in view, so the browser would keep IT in
    // place as the reply grows above it, pushing the held turn up a line at
    // a time.
    spacer.style.marginTop = next > 0 ? `${-gap}px` : '';
  }

  _scrollToItem(item: Element, align: 'start' | 'center' | 'end' | 'nearest', behavior: ScrollBehavior): void {
    const v = this.viewport();
    if (!v) return;
    const vr = v.getBoundingClientRect();
    const ir = item.getBoundingClientRect();
    let top = v.scrollTop + (ir.top - vr.top);
    if (align === 'end') top -= vr.height - ir.height;
    else if (align === 'center') top -= (vr.height - ir.height) / 2;
    else if (align === 'nearest') {
      if (ir.top >= vr.top && ir.bottom <= vr.bottom) return;
      if (ir.bottom > vr.bottom) top -= vr.height - ir.height;
    }
    v.scrollTo({ top, behavior });
  }

  _behavior(): ScrollBehavior {
    return typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth';
  }

  /** Scroll to the newest message, and follow new ones again. */
  scrollToEnd(): void {
    const v = this.viewport();
    if (!v) return;
    this._following = true;
    v.scrollTo({ top: v.scrollHeight, behavior: this._behavior() });
  }

  /** Scroll to the oldest message. */
  scrollToStart(): void {
    this.viewport()?.scrollTo({ top: 0, behavior: this._behavior() });
  }

  /** Scroll the message with `id` into view. */
  scrollToMessage(id: string, opts: { align?: 'start' | 'center' | 'end' | 'nearest'; behavior?: ScrollBehavior } = {}): void {
    const item = this._items().find((i) => i.getAttribute('message-id') === id);
    if (item) this._scrollToItem(item, opts.align ?? 'start', opts.behavior ?? this._behavior());
  }
}
UiMessageScroller.register('ui-message-scroller');

// --------------------------------------------------------------------------
// <ui-message-scroller-viewport> and <ui-message-scroller-content>
// --------------------------------------------------------------------------

export class UiMessageScrollerViewport extends WebComponent {
  render() {
    const pending = rootOf(this)?.pending?.get() ?? false;
    return html`<div data-slot="message-scroller-viewport" ?data-pending-scroll=${!!pending} class=${cn(messageScrollerViewportClass(), takeAuthored(this))}><slot></slot></div>`;
  }
}
UiMessageScrollerViewport.register('ui-message-scroller-viewport');

export class UiMessageScrollerContent extends WebComponent {
  render() {
    return html`<div
      data-slot="message-scroller-content"
      role="log"
      aria-relevant="additions"
      aria-label=${this.getAttribute?.('aria-label') || nothing}
      class=${cn(messageScrollerContentClass(), takeAuthored(this))}
    ><slot></slot><div data-message-scroller-spacer aria-hidden="true" hidden style="overflow-anchor: none"></div></div>`;
  }
}
UiMessageScrollerContent.register('ui-message-scroller-content');

// --------------------------------------------------------------------------
// <ui-message-scroller-item>
// --------------------------------------------------------------------------

export class UiMessageScrollerItem extends WebComponent {
  _authored: string | null = null;

  connectedCallback(): void {
    super.connectedCallback?.();
    rootOf(this)?._itemConnected(this);
  }

  // An item is a flex child of the column, so it carries its own classes.
  render() {
    this._authored = takeAuthoredClass(this);
    if (typeof this.setAttribute === 'function') {
      this.setAttribute('class', cn(messageScrollerItemClass(), this._authored));
      this.setAttribute('data-slot', 'message-scroller-item');
    }
    return html`<slot></slot>`;
  }
}
UiMessageScrollerItem.register('ui-message-scroller-item');

// --------------------------------------------------------------------------
// <ui-message-scroller-button>
// --------------------------------------------------------------------------

export class UiMessageScrollerButton extends WebComponent({
  direction: prop<'end' | 'start'>(String),
  // The button's accessible name, for a transcript in another language.
  label: String,
  variant: String,
  size: String,
}) {
  constructor() {
    super();
    this.direction = 'end';
    this.variant = 'secondary';
    this.size = 'icon-sm';
  }

  render() {
    const root = rootOf(this);
    const toStart = this.direction === 'start';
    const active = !!root && (toStart ? root.scrollable.start : root.scrollable.end);
    return html`<button
      type="button"
      data-slot="message-scroller-button"
      data-direction=${toStart ? 'start' : 'end'}
      data-variant=${this.variant}
      data-size=${this.size}
      data-active=${active ? 'true' : 'false'}
      tabindex=${active ? nothing : '-1'}
      aria-hidden=${active ? nothing : 'true'}
      class=${cn(buttonClass({ variant: this.variant as ButtonVariant, size: this.size as ButtonSize }), messageScrollerButtonClass(), takeAuthored(this))}
      @click=${() => (toStart ? root?.scrollToStart() : root?.scrollToEnd())}
      aria-label=${this.label || nothing}
    ><slot><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 5v14"></path><path d="m19 12-7 7-7-7"></path></svg>${this.label ? '' : html`<span class="sr-only">${toStart ? 'Scroll to start' : 'Scroll to end'}</span>`}</slot></button>`;
  }
}
UiMessageScrollerButton.register('ui-message-scroller-button');
````

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

## Usage

```ts
<ui-message-scroller auto-scroll>
  <ui-message-scroller-viewport>
    <ui-message-scroller-content aria-label="Conversation">
      <ui-message-scroller-item message-id=${id} scroll-anchor>
        <div data-slot="message" data-align="end" class=${messageClass()}>
          <div data-slot="message-content" class=${messageContentClass()}>
            <div data-slot="bubble" data-variant="muted" data-align="end" class=${bubbleClass({ variant: 'muted' })}>
              <div data-slot="bubble-content" class=${bubbleContentClass()}>${text}</div>
            </div>
          </div>
        </div>
      </ui-message-scroller-item>
    </ui-message-scroller-content>
  </ui-message-scroller-viewport>
  <ui-message-scroller-button></ui-message-scroller-button>
</ui-message-scroller>
```

`scroll-anchor` goes on the person's turn. `auto-scroll` follows the reply while the person stays at the live edge.

See [Message Scroller](https://webjs.dev/ui/docs/components/message-scroller).

## AI SDK Helper

To build without a model, script the conversation in a `'use server'` action that streams each turn as parts: reasoning, a tool call and a reply. Your chat component appends the parts as they arrive and renders them in the thread. See [AI SDK](https://webjs.dev/ui/docs/helpers/ai-sdk).

```ts
'use server';

export async function* scriptedReply(question: string) {
  yield { type: 'reasoning', text: 'I need to know how themes are set up first.' };
  yield { type: 'tool-runCommand', input: { command: 'rg -l ThemeProvider app' }, output: { stdout: 'app/layout.tsx' } };
  yield { type: 'text', text: 'next-themes is already set up, so I added a ModeToggle.' };
}
```

```ts
for await (const part of await scriptedReply(question)) {
  this.parts.set([...this.parts.get(), part]);
}
```

## Migrating from AI SDK Elements

If you used Conversation from [AI SDK Elements](https://elements.ai-sdk.dev), its wrapper lives in `components/ai-elements/conversation.tsx`. In a WebJs app it becomes this pattern, built from WebJs UI components. Each export of the wrapper maps onto a part:

| AI SDK Elements | WebJs UI |
| --- | --- |
| `Conversation` | `<ui-message-scroller auto-scroll>`, in place of StickToBottom. |
| `ConversationContent` | `<ui-message-scroller-viewport>` around `<ui-message-scroller-content>`. |
| `ConversationScrollButton` | `<ui-message-scroller-button>`. |
| `ConversationEmptyState` | An [Empty](https://webjs.dev/ui/docs/components/empty) in place of the scroller while there are no messages. |
| `each message` | A `<ui-message-scroller-item>` with its `message-id`, and `scroll-anchor` on the person's messages. |
