Imperative API

DataMethods

Methods for manipulating the data in the list.

Type Parameters

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

Properties

append()

append: (data, scrollToBottom?) => void

Appends additional items to the existing data in the list, while optionally updating the scroll position. See the AutoscrollToBottom type for more information.

Parameters

Parameter	Type	Description
data	Data[]	The data to append.
scrollToBottom?	AutoscrollToBottom<Data, Context>	Specifies the behavior when the list is scrolled to the bottom. You can pass a boolean, a ScrollBehavior, or a function that returns a ScrollBehavior.

Returns

void

---

batch()

batch: (callback, scrollToBottom?) => void

Batches the data operations in the provided callback in a single render cycle.

Parameters

Parameter	Type	Description
callback	() => void	The callback that performs the data operations.
scrollToBottom?	AutoscrollToBottom<Data, Context>	Specifies the behavior when the list is scrolled to the bottom. You can pass a boolean, a ScrollBehavior, or a function that returns a ScrollBehavior.

Returns

void

---

deleteRange()

deleteRange: (offset, count) => void

Deletes a range of items from the list data.

Parameters

Parameter	Type	Description
offset	number	The index of the first item to delete.
count	number	The number of items to delete.

Returns

void

---

find()

find: (predicate) => Data | undefined

Finds the first item that matches the predicate. If no elements satisfy the testing function, undefined is returned.

Parameters

Parameter	Type	Description
predicate	(item, index, data) => boolean	A function that returns true for the item being searched for.

Returns

Data | undefined

---

findAndDelete()

findAndDelete: (predicate) => void

Deletes items from the list data that match the predicate.

Parameters

Parameter	Type	Description
predicate	(item, index) => boolean	A function that returns true for items that should be deleted.

Returns

void

---

findIndex()

findIndex: (predicate) => number

Finds the index of the first item that matches the predicate. If no elements satisfy the testing function, -1 is returned.

Parameters

Parameter	Type	Description
predicate	(item, index, data) => boolean	A function that returns true for the item being searched for.

Returns

number

---

get()

get: () => Data[]

Gets a shallow copy of the current data in the list.

Returns

Data[]

---

getCurrentlyRendered()

getCurrentlyRendered: () => Data[]

Gets the currently rendered data items.

Returns

Data[]

---

insert()

insert: (data, offset, scrollToBottom?) => void

Inserts the provided data at the specified offset, optionally updating the scroll position.

Parameters

Parameter	Type	Description
data	Data[]	The data to insert.
offset	number	The index that the first item in the data will be inserted at. e.g. [1,2,3] with offset 10 will insert the data at index 10, 11, and 12 and shift the rest of the existing data.
scrollToBottom?	AutoscrollToBottom<Data, Context>	Specifies the behavior when the list is scrolled to the bottom. You can pass a boolean, a ScrollBehavior, or a function that returns a ScrollBehavior.

Returns

void

---

map()

map: (callbackfn, autoscrollToBottomBehavior?) => void

Updates the data in the list by applying a mapping function to each item. Optionally, you can specify a scroll behavior if the state change displaces the list (for example, if the item size increases).

Parameters

Parameter	Type	Description
callbackfn	(data, index) => Data	A function that maps the data items.
autoscrollToBottomBehavior?	ScrollBehavior | { location: () => ItemLocation | null | undefined; }	Specifies the behavior to use to scroll to the bottom if necessary.

Returns

void

---

mapWithAnchor()

mapWithAnchor: (callbackfn, anchorItemIndex) => void

Updates the data in the list by applying a mapping function to each item, while keeping the specified item anchored in the viewport. This is useful when the size of some items change, and you want to avoid displacing the scroll position.

Parameters

Parameter	Type	Description
callbackfn	(data, index) => Data	A function that maps the data items.
anchorItemIndex	number	the index of the item to keep anchored in the viewport.

Returns

void

---

prepend()

prepend: (data) => void

Prepends additional items to the existing data in the list, while preserving the scroll position.

Parameters

Parameter	Type	Description
data	Data[]	The data to prepend.

Returns

void

---

removeFromStart()

removeFromStart: (count) => void

Removes the specified amount of items from the start of the list.

Parameters

Parameter	Type	Description
count	number	The number of items to remove.

Returns

void

---

replace()

replace: (data, options?) => void

Completely replaces the data in the list with the new data. Optionally, you can specify an initial scroll location after the data has been replaced. See the ItemLocation type for more information. Setting the purgeItemSizes flag to true will clear the item size cache and force the list to remeasure the items. The suppressItemMeasure flag will prevent the list from measuring the items after the data has been replaced.

Parameters

Parameter	Type	Description
data	Data[]	The data to replace.
options?	{ initialLocation?: ItemLocation; purgeItemSizes?: boolean; suppressItemMeasure?: boolean; }	The location to scroll to after the data has been replaced and whether to purge the item sizes.
options.initialLocation?	ItemLocation	-
options.purgeItemSizes?	boolean	-
options.suppressItemMeasure?	boolean	-

Returns

void

---

VirtuosoMessageListMethods

The imperative API of the message list component. You can access it with a ref, or by using the `useVirtuosoMethods()` hook from a child component.

Type Parameters

Type Parameter	Default type	Description
Data	any	The type of the data items in the list. Specifying this type gives you correct typing in the data methods.
Context	any	The type of the context passed to the list. Specifying this type gives you correct typing in the data methods.

Properties

cancelSmoothScroll()

cancelSmoothScroll: () => void

Cancels the current smooth scroll operation, if any.

Returns

void

---

data

DataMethods<Data, Context>

A set of methods to manipulate the data in the list.

---

getScrollLocation()

getScrollLocation: () => ListScrollLocation

Retrieves the current scroll location

Returns

ListScrollLocation

---

height()

height: (item) => number

Gets the known height of the item.

Parameters

Parameter	Type
item	Data

Returns

number

---

scrollerElement()

scrollerElement: () => HTMLDivElement | null

Lets you obtain a reference to the component’s scroller DOM element.

Returns

HTMLDivElement | null

---

scrollIntoView()

scrollIntoView: (location) => void

Scrolls the specified item into view if necessary. See ItemLocation for possible location details. Passing a number scrolls to the item at the specified index.

Parameters

Parameter	Type
location	ItemLocation

Returns

void

---

scrollToItem()

scrollToItem: (location) => void

Scrolls the list to the specified item. See ItemLocation for possible location details. Passing a number scrolls to the item at the specified index aligned to the top.

Parameters

Parameter	Type
location	ItemLocation

Returns

void