# VirtualizedMessageList

`VirtualizedMessageList` renders channel messages in a virtualized list. It is optimized for high-volume or long-lived channels by keeping only the visible items in the DOM.

Like `MessageList`, it reads messages from `ChannelStateContext` by default and renders unread and notification UI around the list.

## Best Practices

- Prefer `VirtualizedMessageList` for high-traffic channels or long histories.
- Set `defaultItemHeight` or `additionalVirtuosoProps.defaultItemHeight` if the first rendered item is much taller than the average message.
- Keep custom renderers lightweight to preserve virtualization gains.
- Use the list-level `Message` prop or `WithComponents` for message UI, not `Channel Message={...}`.
- Test unread notifications, separators, and grouping with virtualization enabled.

## Basic Usage

```tsx
import {
  Channel,
  ChannelHeader,
  MessageComposer,
  VirtualizedMessageList,
  Window,
} from "stream-chat-react";

const App = () => (
  <Channel>
    <Window>
      <ChannelHeader />
      <VirtualizedMessageList />
      <MessageComposer />
    </Window>
  </Channel>
);
```

If you need to override the rendered message array:

```tsx
<VirtualizedMessageList messages={customMessages} />
```

## Scroll Behavior

The list estimates total height from the first rendered item unless you provide a default item height. If the newest message is unusually tall, set a more representative height:

```tsx
<VirtualizedMessageList defaultItemHeight={76} />
```

## Notifications And Unread UI

The virtualized list uses the same unread and notification split as `MessageList`:

- `UnreadMessagesNotification`
- `NewMessageNotification`
- `ScrollToLatestMessageButton`
- `NotificationList`

`NotificationList` renders panel-scoped client notifications. The unread and scroll controls remain separate components, just like in `MessageList`.

## Props

`VirtualizedMessageList` forwards the same message-level props as `MessageList`, including:

- `additionalMessageComposerProps`
- `closeReactionSelectorOnClick`
- `disableQuotedMessages`
- `formatDate`
- `Message`
- `messageActions`
- `onMentionsClick`
- `onMentionsHover`
- `onUserClick`
- `onUserHover`
- `openThread`
- `reactionDetailsSort`
- `renderText`
- `retrySendMessage`
- `showAvatar`
- `sortReactions`
- `unsafeHTML`

| Prop                            | Description                                                                                                       | Type                                                   |
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `additionalVirtuosoProps`       | Additional props for the underlying `react-virtuoso` list.                                                        | `VirtuosoProps`                                        |
| `channelUnreadUiState`          | Override for unread UI state.                                                                                     | `ChannelStateContextValue["channelUnreadUiState"]`     |
| `customMessageRenderer`         | Custom per-item renderer for virtualized messages.                                                                | `VirtualizedMessageListProps["customMessageRenderer"]` |
| `defaultItemHeight`             | Default item height used for list-size estimation.                                                                | `number`                                               |
| `disableDateSeparator`          | Disables injected date separators.                                                                                | `boolean`                                              |
| `groupStyles`                   | Custom callback for message grouping.                                                                             | `VirtualizedMessageListProps["groupStyles"]`           |
| `hasMore`                       | Whether older messages can be loaded.                                                                             | `boolean`                                              |
| `hasMoreNewer`                  | Whether newer messages can be loaded.                                                                             | `boolean`                                              |
| `head`                          | Element rendered above the thread reply list. Deprecated in favor of `additionalVirtuosoProps.components.Header`. | `ReactElement`                                         |
| `hideDeletedMessages`           | Hides deleted-message bubbles.                                                                                    | `boolean`                                              |
| `hideNewMessageSeparator`       | Hides the separator inserted for unread incoming messages in watched but inactive channels.                       | `boolean`                                              |
| `highlightedMessageId`          | Message ID to center and highlight.                                                                               | `string`                                               |
| `loadMore`                      | Loads older messages.                                                                                             | `() => Promise<void>`                                  |
| `loadMoreNewer`                 | Loads newer messages.                                                                                             | `() => Promise<void>`                                  |
| `maxTimeBetweenGroupedMessages` | Maximum time window for grouping messages together.                                                               | `number`                                               |
| `messageLimit`                  | Page size used for pagination.                                                                                    | `number`                                               |
| `messages`                      | Custom message array overriding `ChannelStateContext.messages`.                                                   | `LocalMessage[]`                                       |
| `overscan`                      | Deprecated overscan prop. Prefer `additionalVirtuosoProps.overscan`.                                              | `number`                                               |
| `returnAllReadData`             | Keeps read receipts for every own message.                                                                        | `boolean`                                              |
| `reviewProcessedMessage`        | Lets you inspect and adjust processed list items.                                                                 | `ProcessMessagesParams["reviewProcessedMessage"]`      |
| `scrollSeekPlaceHolder`         | Deprecated fast-scroll placeholder config.                                                                        | `object`                                               |
| `scrollToLatestMessageOnFocus`  | Scrolls to the latest message when the window regains focus.                                                      | `boolean`                                              |
| `separateGiphyPreview`          | Renders giphy previews above the composer instead of inline in the list.                                          | `boolean`                                              |
| `shouldGroupByUser`             | Groups consecutive messages by user.                                                                              | `boolean`                                              |
| `showUnreadNotificationAlways`  | Shows unread notification even when the unread separator is not visible.                                          | `boolean`                                              |
| `stickToBottomScrollBehavior`   | Scroll behavior used when staying pinned to the latest message.                                                   | `"smooth" \| "auto"`                                   |
| `suppressAutoscroll`            | Prevents automatic scrolling when new messages arrive.                                                            | `boolean`                                              |
| `threadList`                    | Marks the list as a thread list.                                                                                  | `boolean`                                              |


---

This page was last updated at 2026-04-22T14:09:44.772Z.

For the most recent version of this documentation, visit [https://getstream.io/chat/docs/sdk/react/components/core-components/virtualized_list/](https://getstream.io/chat/docs/sdk/react/components/core-components/virtualized_list/).