Components

ScrollerProps

ScrollerProps = Omit<React.HTMLProps<HTMLDivElement>, "ref" | "data" | "onScroll">

The DOM attributes that you can pass to the VirtuosoMessageList component to customize the scroll element.

---

VirtuosoMessageList

VirtuosoMessageList<Data, Context>(props): ReactElement

The React component that renders the message list. Refer to VirtuosoMessageListProps for the accepted props. The component accepts a ref that can be used to call methods on the message list. See VirtuosoMessageListMethods for the available methods.

You should wrap your message lists (either individually or at a higher level) in a VirtuosoMessageListLicense to provide the license key.

Type Parameters

Type Parameter
Data
Context

Parameters

Parameter	Type
props	VirtuosoMessageListProps<Data, Context> & object

Returns

ReactElement

---

VirtuosoMessageListLicense

VirtuosoMessageListLicense(props): Element

A component that provides a license key to the VirtuosoMessageList component. This component must wrap all VirtuosoMessageList components in your application - either individually or at a common parent.

Parameters

Parameter	Type	Description
props	{ children: ReactNode; licenseKey: string; }	VirtuosoMessageListLicenseProps
props.children	ReactNode	The child components that will have access to the license context. The message list components must be descendants of this component.
props.licenseKey	string	The license key to use for the VirtuosoMessageList component. Buy a license at https://virtuoso.dev/pricing. Leave empty for trial mode.

Returns

Element

---

VirtuosoMessageListProps

The properties accepted by the VirtuosoMessageList component. In addition to the properties listed here, you can pass any other props that are accepted by a div element. They will be passed to the root div element used for the scroll.

Extends

• ScrollerProps

Type Parameters

Type Parameter	Description
Data	The type of the data items in the list.
Context	The type of the context passed to the list.

Properties

computeItemKey?

optional computeItemKey: NoInfer<(params) => Key>

Computes the value for the React key prop for the item at the specified index. Use stable, unique keys to avoid rendering issues.

Param

The parameters to compute the key.

---

context?: Context

Any additional state that you need to use in the ItemContent, Header, Footer, etc.

---

customScrollParent?: HTMLElement | null

Pass an HTML element to use as the scroll element. This is useful when you want to include additional content in the scrollable area, or if you want to use a complex custom scroll component.

---

data?: DataWithScrollModifier<Data> | null

The data to display, and the scroll action to perform when the data changes.

---

EmptyPlaceholder?: NoInfer<ContextAwareComponent<Context>>

An optional React component to render when the list has zero data items.

---

enforceStickyFooterAtBottom?: boolean

Set to true to force the sticky footer to be always at the bottom, even if the item list is short.

---

Footer?: NoInfer<ContextAwareComponent<Context>>

An optional React component to render below the list items.

---

FooterWrapper?: FooterWrapperComponent

Pass a custom component here if you need to adjust the footer container. The default value is div element.

---

Header?: NoInfer<ContextAwareComponent<Context>>

An optional React component to render above the list items.

---

HeaderWrapper?: HeaderWrapperComponent

Pass a custom component here if you need to adjust the z-index of the header container. The default value is div with zIndex: 1.

---

increaseViewportBy?: number

Artificially extends the viewport size in both directions, causing more items to be rendered. Useful if you have relatively heavy items or want images to be loaded before the user scrolls to them. For example, setting the value to 100 would increase the viewport in both directions by 100 pixels, causing the list to render more items.

---

initialData?: Data[]

The initial data to display in the list.

Note

This property does not accept updates after the initial mount of the component. If you need to update the data, use the data property.

---

initialLocation?: ItemLocation

The initial location to scroll to. It will be applied the first time the list is rendered with data. Using this property allows you to skip rendering of the items at the top of the list.

Note

If you’re using the data prop, you should be using the scrollModifier field for the positioning of the list after the data has been updated.

---

ItemContent?: NoInfer<ItemContent<Data, Context>>

A React component that’s used to render the individual item. See ItemContent for further details on the accepted props.

---

itemIdentity()?

optional itemIdentity: (item) => unknown

Implement this if your data management logic replaces the data objects - it should return an item key, for example. This is necessary for the data prop updates to detect the prepending/appending changes correctly.

Parameters

Parameter	Type
item	Data

Returns

unknown

---

onRenderedDataChange()?

optional onRenderedDataChange: (range) => void

A callback that’s invoked when the currently visible items change

Parameters

Parameter	Type
range	Data[]

Returns

void

---

onScroll()?

optional onScroll: (location) => void

A callback that’s invoked when the list is scrolled. See ListScrollLocation for the details of the parameter received.

Parameters

Parameter	Type
location	ListScrollLocation

Returns

void

---

ScrollElement?: NoInfer<ScrollElementComponent<Context>>

An optional React component to replace the default scroller element. The default value is a div element.

---

shortSizeAlign?: ShortSizeAlign

Specifies the alignment of the items when the content of the list is smaller than the viewport height.

• 'top' (default), the items will be aligned to the top
• 'bottom', the items will be aligned to the bottom.
• 'bottom-smooth', the items will be aligned to the bottom and the scroll will be animated.

---

StickyFooter?: NoInfer<ContextAwareComponent<Context>>

An optional React component to render below the list items that remains visible at the bottom of the viewport when scrolling.

---

StickyFooterWrapper?: StickyHeaderWrapperComponent

Pass a custom component here if you need to adjust the z-index of the sticky footer container. The default value is div element with zIndex: 1.

---

StickyHeader?: NoInfer<ContextAwareComponent<Context>>

An optional React component to render above the list items that remains visible at the top of the viewport when scrolling.

---

StickyHeaderWrapper?: StickyHeaderWrapperComponent

Pass a custom component here if you need to adjust the z-index of the sticky header container. The default value is div with zIndex: 1.

---

useWindowScroll?: boolean

Set to true to make the list use the document scroller rather than wrapping in its own.