Virtuoso API Reference

All properties are optional - by default, the component will render empty. Under the hood, both Virtuoso and GroupedVirtuoso are the same component - the only difference is that they have different TypeScript interfaces applied. All Virtuoso props work for GroupedVirtuoso, but the properties in the GroupedVirtuoso section work only in grouped mode.

If you are using TypeScript and want to use correctly typed component ref, you can use the VirtuosoHandle and the GroupedVirtuosoHandle types.

import { Virtuoso, VirtuosoHandle } from 'react-virtuoso'
//...
const ref = useRef<VirtuosoHandle>(null)
//...
<Virtuoso ref={ref} /*...*/ />

Virtuoso Properties

"components".VirtuosoProps

Type parameters

Name
D

Hierarchy

  • {}

    VirtuosoProps

Properties

alignToBottom

Optional alignToBottom: boolean

Defined in components.tsx:189

Setting alignToBottom to true aligns the items to the bottom of the list if the list is shorter than the viewport. Use followOutput property to keep the list aligned when new items are appended.


atBottomStateChange

Optional atBottomStateChange: (atBottom: boolean) => void

Defined in components.tsx:168

Called with true / false when the list has reached the bottom / gets scrolled up. Can be used to load newer items, like tail -f.


atTopStateChange

Optional atTopStateChange: (atTop: boolean) => void

Defined in components.tsx:173

Called with true / false when the list has reached the top / gets scrolled down.


components

Optional components: Components

Defined in components.tsx:67

Use the components property for advanced customization of the elements rendered by the list.


computeItemKey

Optional computeItemKey: ComputeItemKey<D>

Defined in components.tsx:77

If specified, the component will use the function to generate the key property for each list item.


data

Optional data: readonly D[]

Defined in components.tsx:30

The data items to be rendered. If data is set, the total count will be inferred from the length of the array.


defaultItemHeight

Optional defaultItemHeight: number

Defined in components.tsx:88

By default, the component assumes the default item height from the first rendered item (rendering it as a "probe").

If the first item turns out to be an outlier (very short or tall), the rest of the rendering will be slower, as multiple passes of rendering should happen for the list to fill the viewport.

Setting defaultItemHeight causes the component to skip the "probe" rendering and use the property value as default height instead.


endReached

Optional endReached: (index: number) => void

Defined in components.tsx:152

Gets called when the user scrolls to the end of the list. Receives the last item index as an argument. Can be used to implement endless scrolling.


firstItemIndex

Optional firstItemIndex: number

Defined in components.tsx:141

Use when implementing inverse infinite scrolling - decrease the value this property in combination with data or totalCount to prepend items to the top of the list.

Warning: the firstItemIndex should be a positive number, based on the total amount of items to be displayed.


fixedItemHeight

Optional fixedItemHeight: number

Defined in components.tsx:101

Can be used to improve performance if the rendered items are of known size. Setting it causes the component to skip item measurements.


followOutput

Optional followOutput: FollowOutput

Defined in components.tsx:128

If set to true, the list automatically scrolls to bottom if the total count is changed. Set to "smooth" for an animated scrolling.

By default, followOutput scrolls down only if the list is already at the bottom. To implement an arbitrary logic behind that, pass a function:

<Virtuoso
followOutput={(isAtBottom: boolean) => {
if (expression) {
return 'smooth' // can be 'auto' or false to avoid scrolling
} else {
return false
}
}} />

headerFooterTag

Optional headerFooterTag: string

Defined in components.tsx:133

Set to customize the wrapper tag for the header and footer components (default is div).


initialItemCount

Optional initialItemCount: number

Defined in components.tsx:62

Use for server-side rendering - if set, the list will render the specified amount of items regardless of the container / item size.


initialScrollTop

Optional initialScrollTop: number

Defined in components.tsx:56

Set this value to offset the initial location of the list. Warning: using this property will still run a render cycle at the scrollTop: 0 list window. If possible, avoid using it and stick to initialTopMostItemIndex instead.


initialTopMostItemIndex

Optional initialTopMostItemIndex: number

Defined in components.tsx:49

Set to a value between 0 and totalCount - 1 to make the list start scrolled to that item.


isScrolling

Optional isScrolling: (isScrolling: boolean) => void

Defined in components.tsx:146

Called when the list starts/stops scrolling.


itemContent

Optional itemContent: ItemContent<D>

Defined in components.tsx:72

Set the callback to specify the contents of the item.


itemSize

Optional itemSize: (el: HTMLElement, field: "offsetHeight" | "offsetWidth") => number

Defined in components.tsx:95

Allows customizing the height/width calculation of Item elements.

The default implementation reads el.offsetHeight and el.offsetWidth.


itemsRendered

Optional itemsRendered: (items: ListItem<D>[]) => void

Defined in components.tsx:183

Called with the new set of items each time the list items are rendered due to scrolling.


overscan

Optional overscan: number | { main: number ; reverse: number }

Defined in components.tsx:37

Increases the visual window which is used to calculate the rendered items with the specified amount in pixels. Effectively, this makes the component "chunk" the rendering of new items by renderng more items than the necessary, but reducing the re-renders on scroll. Setting { main: number, reverse: number } lets you extend the list in both the main and the reverse scrollable directions.


rangeChanged

Optional rangeChanged: (range: ListRange) => void

Defined in components.tsx:162

Called with the new set of items each time the list items are rendered due to scrolling.


scrollSeekConfiguration

Optional scrollSeekConfiguration: ScrollSeekConfiguration | false

Defined in components.tsx:108

Use to display placeholders if the user scrolls fast through the list.

Set components.ScrollSeekPlaceholder to change the placeholder content.


scrollerRef

Optional scrollerRef: (ref: HTMLElement | Window | null) => any

Defined in components.tsx:199

Provides access to the root DOM element


startReached

Optional startReached: (index: number) => void

Defined in components.tsx:157

Called when the user scrolls to the start of the list.


topItemCount

Optional topItemCount: number

Defined in components.tsx:44

Set the amount of items to remain fixed at the top of the list.

For a header that scrolls away when scrolling, check the components.Header property.


totalCount

Optional totalCount: number

Defined in components.tsx:25

The total amount of items to be rendered.


totalListHeightChanged

Optional totalListHeightChanged: (height: number) => void

Defined in components.tsx:178

Called when the total list height is changed due to new items or viewport resize.


useWindowScroll

Optional useWindowScroll: boolean

Defined in components.tsx:194

Uses the document scroller rather than wrapping the list in its own.

GroupedVirtuoso Properties

"components".GroupedVirtuosoProps

Type parameters

Name
D

Hierarchy

  • {}

  • {}

    GroupedVirtuosoProps

Properties

groupContent

Optional groupContent: GroupContent

Defined in components.tsx:214

Specifies how each each group header gets rendered. The callback receives the zero-based index of the group.


groupCounts

Optional groupCounts: number[]

Defined in components.tsx:209

Specifies the amount of items in each group (and, actually, how many groups are there). For example, passing [20, 30] will display 2 groups with 20 and 30 items each.


itemContent

Optional itemContent: GroupItemContent<D>

Defined in components.tsx:219

Specifies how each each item gets rendered.

Methods

"components".VirtuosoHandle

Hierarchy

  • {}

    VirtuosoHandle

Methods

scrollBy

scrollBy(location: ScrollToOptions): void

Defined in components.tsx:322

Scrolls the component with the specified amount. See ScrollToOptions (MDN)

Parameters:

NameType
locationScrollToOptions

Returns: void


scrollTo

scrollTo(location: ScrollToOptions): void

Defined in components.tsx:318

Scrolls the component to the specified location. See ScrollToOptions (MDN)

Parameters:

NameType
locationScrollToOptions

Returns: void


scrollToIndex

scrollToIndex(location: number | IndexLocationWithAlign): void

Defined in components.tsx:314

Scrolls the component to the specified item index. See {{IndexLocationWithAlign}} for more options.

Parameters:

NameType
locationnumber | IndexLocationWithAlign

Returns: void