@virtuoso.dev/message-list

VirtuosoMessageList is a virtualized list purpose-built for human and AI chat: stick-to-bottom behavior, streaming responses that grow without scroll jumps, history prepending that preserves the visual position, and scroll position tracking. Use it instead of plain Virtuoso when building conversation UIs — these behaviors are built in rather than hand-assembled.

Licensing

The package is commercial (annual, per-developer). Every instance must be wrapped in VirtuosoMessageListLicense:

<VirtuosoMessageListLicense licenseKey={licenseKey}>
  <VirtuosoMessageList ... />
</VirtuosoMessageListLicense>

An empty licenseKey="" is licensed for 30-day non-production evaluation: it keeps rendering in development with a console reminder, while production without a valid key renders an error. Validation is local — no network requests. Surface this to the user when introducing the package into a project; keys come from https://virtuoso.dev/pricing/. Prefer an app-level wrapper that reads from the normal public client-side environment configuration.

Core mental model: data updates carry scroll instructions

Instead of separate imperative scroll calls, each data update includes a scrollModifier describing how the viewport should react:

const [data, setData] = useState<VirtuosoMessageListProps<Message, null>['data']>(() => ({
  data: initialMessages,
  scrollModifier: { type: 'item-location', location: { index: 'LAST', align: 'end' } },
}))

<VirtuosoMessageList<Message, null> style={{ height: '100%' }} data={data} computeItemKey={({ data }) => data.key} ItemContent={ItemContent} />

ItemContent is a component receiving { data, index, context } props (not positional arguments like react-virtuoso). Extract it outside the parent render function unless it needs to close over local state.

External row state is different from data updates. If context, side maps, expansion state, reactions, approvals, or loading flags can change row height without changing the data array, call notifyItemsChanged({ scrollToBottom }) on the message-list ref after updating that state.

Scroll modifier reference

In callback form, returning a behavior or item location scrolls even when atBottom is false. Return false to preserve the viewport for a scrolled-up user.

Common patterns

Receiving messages (auto-scroll when at bottom)

import { scrollToBottomIfAtBottom } from '@virtuoso.dev/message-list'

setData((current) => ({
  data: [...current.data, incoming],
  scrollModifier: {
    type: 'auto-scroll-to-bottom',
    autoScroll: scrollToBottomIfAtBottom,
  },
}))

Use scrollToBottomIfAtBottom for remote messages. It returns 'smooth' when the list is already at the bottom or already scrolling there, otherwise false. If the app needs an unseen-message counter, use the inline callback form and increment the counter before returning false.

Sending local messages (force bottom)

import { scrollToBottomAlways } from '@virtuoso.dev/message-list'

setData((current) => ({
  data: [...current.data, optimisticLocalMessage],
  scrollModifier: {
    type: 'auto-scroll-to-bottom',
    autoScroll: scrollToBottomAlways,
  },
}))

Use scrollToBottomAlways for local current-user actions where the new last item should become visible even if the user was scrolled up. If a realtime socket echoes the same optimistic message back, reconcile it by localId or another client-generated identity and treat it as confirmation, not a new incoming remote message.

Streaming an AI response

Append an empty assistant message, then grow it as tokens arrive:

setData((current) => ({
  data: current.data.map((msg) => (msg.key === botKey ? { ...msg, text: msg.text + chunk } : msg)),
  scrollModifier: { type: 'items-change', behavior: 'smooth' },
}))

items-change keeps the view pinned to the bottom while the message grows, without jumping if the user scrolled up. See ai-chatbot and gemini (question pinned to top, answer streams below).

Live tail with spliced records

For @virtuoso.dev/message-list 1.18.0 and later, combine a replacement anchor with a retargetable smooth-scroll behavior when live updates can insert or reorder records above the tail:

const liveTailScroll = () => ({
  animationFrameCount: 15,
  easing: (progress: number) => 1 - (1 - progress) * (1 - progress),
  retarget: true,
})

<VirtuosoMessageList
  ref={ref}
  computeItemKey={({ data }) => data.id}
  itemIdentity={(item) => item.id}
  ItemContent={ItemContent}
/>

ref.current.data.batch(
  () => {
    ref.current.data.replace(nextData, { anchor: { index: 'LAST', position: 'preserve' } })
  },
  ({ atBottom, scrollInProgress }) =>
    atBottom || scrollInProgress
      ? {
          index: 'LAST',
          align: 'end',
          behavior: liveTailScroll,
        }
      : false
)

The anchor keeps the previous last record at its viewport position during replacement. Retargeting updates the active animation's destination instead of restarting it as the bottom moves. The old and new requests must both use a behavior with retarget: true. Return false when the user has scrolled away from the live tail.

itemIdentity must return a stable identity when updates recreate record objects. Default object identity cannot match recreated wrappers, so the anchor becomes a no-op in that case.

External row state changed size

Use notifyItemsChanged when row content changes size without changing the data array:

import { scrollToBottomIfAtBottom, type VirtuosoMessageListMethods } from '@virtuoso.dev/message-list'

const messageListRef = useRef<VirtuosoMessageListMethods<Message, MessageListContext>>(null)

setExpandedMessages((current) => new Map(current).set(messageId, expanded))
messageListRef.current?.notifyItemsChanged({ scrollToBottom: scrollToBottomIfAtBottom })

ResizeObserver measures the rows; notifyItemsChanged supplies the scroll policy. Use it for expansion state in context, side maps for reactions or approvals, activity loading, or any other external row state.

Loading older messages on scroll-up

<VirtuosoMessageList
  onScroll={(location) => {
    if (location.listOffset > -100 && !loading) {
      loadOlder().then((older) => setData((current) => ({ data: [...older, ...current.data], scrollModifier: 'prepend' })))
    }
  }}
/>

No firstItemIndex bookkeeping is needed (unlike plain Virtuoso) — 'prepend' preserves the position automatically.

Scroll-to-bottom button

StickyFooter renders fixed at the bottom of the viewport; combine with the location hook:

const StickyFooter = () => {
  const location = useVirtuosoLocation()
  const methods = useVirtuosoMethods()
  if (location.bottomOffset <= 200) return null
  return <button onClick={() => methods.scrollToItem({ index: 'LAST', align: 'end', behavior: 'auto' })}>▼</button>
}

Switching channels

Keep one data object per channel and swap with replace/item-location + purgeItemSizes: true, so size caches from the previous channel don't distort the new one. See multiple-channels.

Controlled mode recipe

For controlled data prop usage, keep DataWithScrollModifier<Message> behind app-owned actions such as replaceMessages, appendIncoming, appendLocal, confirmLocal, updateStreamingMessage, and rowChromeChanged. This is a recipe layer in app code, not an official exported hook and not a replacement for the imperative data.* API.

• replaceMessages: channel or thread switch with { type: 'item-location', location: { index: 'LAST', align: 'end' }, purgeItemSizes: true }.
• appendIncoming: remote messages with scrollToBottomIfAtBottom.
• appendLocal: optimistic local sends with scrollToBottomAlways.
• confirmLocal: match the socket/server acknowledgement by localId and update the existing row.
• updateStreamingMessage: map the existing message and use { type: 'items-change', behavior: 'smooth' }.
• rowChromeChanged: update external row state and call notifyItemsChanged({ scrollToBottom: scrollToBottomIfAtBottom }).

Do not invent or recommend a public useVirtuosoMessageListData hook before trying this recipe-level controlled state in app code. See controlled-mode-recipes.

Imperative API

Via ref={useRef<VirtuosoMessageListMethods<Message>>(null)} from outside, or useVirtuosoMethods() from components rendered inside the list:

• data.append(items, scrollToBottom?), data.prepend(items)
• data.map(fn, autoscrollBehavior?) — update items (reactions, edits, streaming)
• data.mapWithAnchor(fn, anchorItemIndex) — update item sizes while keeping one current item at its viewport position (since 1.15.0)
• data.findAndDelete(predicate), data.deleteRange(start, length)
• data.replace(data, { anchor?, initialLocation?, purgeItemSizes?, suppressItemMeasure? }) — replace records, optionally preserving an existing item (replacement anchors require 1.18.0)
• data.find(predicate), data.findIndex(predicate), data.get(), data.getCurrentlyRendered()
• notifyItemsChanged({ scrollToBottom }) — use after context or side-state changes that can resize rendered rows without changing the data array
• scrollToItem({ index: number | 'LAST', align, behavior })

The declarative data prop and the imperative data.* methods are alternative ways to drive the same list — pick one as the primary mechanism per component to avoid fighting updates.

Key props and hooks

• ItemContent: ({ data, index, context }) => JSX — message renderer
• context — shared state (current user, loading flags) available to ItemContent and all custom slots; avoids prop drilling
• computeItemKey({ data }) — stable message key; required for prepending/streaming to work without remounts
• itemIdentity(item) — stable item identity for controlled prepend/remove-from-start and anchored replacement matching when updates recreate item objects
• Slots: Header, Footer (scroll with content), StickyHeader, StickyFooter (fixed, measured to avoid overlap), EmptyPlaceholder
• initialLocation: { index: 'LAST', align: 'end' } — start at the bottom
• Hooks (inside the list): useVirtuosoMethods(), useVirtuosoLocation() (isAtBottom, bottomOffset, listOffset, lastVisibleItemIndex, lastItemBottomOffset), useCurrentlyRenderedData(); the last-visible fields require 1.16.0

Pitfalls

• No height → nothing renders. The component needs a real height (style={{ height: '100%' }} with a sized parent).
• Missing license wrapper → runtime error. Wrap with VirtuosoMessageListLicense; an empty key is only for non-production evaluation.
• Missing computeItemKey causes remounts and scroll jumps on prepend and streaming updates.
• Missing itemIdentity can break controlled prepend/remove-from-start matching and anchored replacement when updates recreate item objects.
• Margins on measured message rows break height measurement because ResizeObserver excludes margins. Use padding or inner wrappers.
• Implicit scroll policy causes chat regressions. Decide per source: local send usually forces bottom, remote receive preserves scrolled-up users, streaming uses items-change, and context-only row growth uses notifyItemsChanged.
• "ResizeObserver loop" errors are benign — filter them in dev overlays and error tracking; see resize-observer-errors.
• JSDOM tests need mocked measurements via VirtuosoMessageListTestingContext.Provider value={{ itemHeight, viewportHeight }} plus a ResizeObserver polyfill; prefer Playwright for scroll behavior. See testing.

Migration checklist from a plain mapped chat list

• Add the VirtuosoMessageListLicense wrapper and decide how the key is supplied.
• Give the list a real height through a sized parent or direct style.
• Extract ItemContent and pass shared state through context.
• Add stable computeItemKey for message ids and local optimistic ids.
• Add itemIdentity when controlled data recreates objects and uses prepend/trimming.
• Remove margins from measured rows; use padding or inner wrappers for spacing.
• Choose an explicit scroll policy for local sends, remote receives, streaming updates, socket echoes, and external row growth.
• Use Playwright/browser tests for scroll behavior where possible; use the testing context for JSDOM unit tests.

References

• references/README.md — overview and live example
• references/2.tutorial/ — step-by-step chat build: intro, message-list, loading-older-messages, scroll-to-bottom-button, receive-messages, send-messages, multiple-channels
• references/3.examples/ — messaging, ai-chatbot, gemini, reactions, date-separators, scroll-to-reply, grouped-messages
• Feature guides: headers-footers, context, item-keys, hooks, custom-scrollbar, scrolling-to-item, smooth-scrolling, imperative-data-api, scroll-modifier, controlled-mode-recipes, testing, licensing

Full API reference: https://virtuoso.dev/message-list/