Skip to main content

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} /*...*/

Read-only

Virtuoso Properties

Type parameters

Name
D
C

Hierarchy

Properties

alignToBottom

Optional alignToBottom: boolean

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.

Defined in

dist/index.d.ts:1054


atBottomStateChange

Optional atBottomStateChange: (atBottom: boolean) => void

Type declaration

▸ (atBottom): void

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

Parameters
NameType
atBottomboolean
Returns

void

Defined in

dist/index.d.ts:1037


atBottomThreshold

Optional atBottomThreshold: number

The property accepts pixel values.

By default 4. Redefine to change how much away from the bottom the scroller can be before the list is not considered not at bottom.

Defined in

dist/index.d.ts:1078


atTopStateChange

Optional atTopStateChange: (atTop: boolean) => void

Type declaration

▸ (atTop): void

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

Parameters
NameType
atTopboolean
Returns

void

Defined in

dist/index.d.ts:1041


atTopThreshold

Optional atTopThreshold: number

The property accepts pixel values.

By default 0. Redefine to change how much away from the top the scroller can be before the list is not considered not at top.

Defined in

dist/index.d.ts:1072


components

Optional components: Components<D, C>

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

Defined in

dist/index.d.ts:950


computeItemKey

Optional computeItemKey: ComputeItemKey<D, C>

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

Defined in

dist/index.d.ts:958


context

Optional context: C

Additional context available in the custom components and content callbacks

Defined in

dist/index.d.ts:898


customScrollParent

Optional customScrollParent: HTMLElement

Pass a reference to a scrollable parent element, so that the list won't wrap in its own.

Defined in

dist/index.d.ts:1062


data

Optional data: readonly D[]

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

Defined in

dist/index.d.ts:894


defaultItemHeight

Optional defaultItemHeight: number

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.

Defined in

dist/index.d.ts:968


endReached

Optional endReached: (index: number) => void

Type declaration

▸ (index): void

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.

Parameters
NameType
indexnumber
Returns

void

Defined in

dist/index.d.ts:1024


firstItemIndex

Optional firstItemIndex: number

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.

Defined in

dist/index.d.ts:1015


fixedItemHeight

Optional fixedItemHeight: number

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

Defined in

dist/index.d.ts:979


followOutput

Optional followOutput: FollowOutput

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
   }
 }} />
Read-only

Defined in

dist/index.d.ts:1004


headerFooterTag

Optional headerFooterTag: string

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

Defined in

dist/index.d.ts:1008


increaseViewportBy

Optional increaseViewportBy: number | { bottom: number ; top: number }

The property accepts pixel values.

Set the increaseViewportBy property to artificially increase the viewport size, causing items to be rendered before outside of the viewport. The property causes the component to render more items than the necessary, but can help with slow loading content. Using { top?: number, bottom?: number } lets you set the increase for each end separately.

Defined in

dist/index.d.ts:921


initialItemCount

Optional initialItemCount: number

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

Defined in

dist/index.d.ts:946


initialScrollTop

Optional initialScrollTop: number

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.

Defined in

dist/index.d.ts:941


initialTopMostItemIndex

Optional initialTopMostItemIndex: number | IndexLocationWithAlign

Set to a value between 0 and totalCount - 1 to make the list start scrolled to that item. Pass in an object to achieve additional effects similar to scrollToIndex.

Defined in

dist/index.d.ts:935


isScrolling

Optional isScrolling: (isScrolling: boolean) => void

Type declaration

▸ (isScrolling): void

Called when the list starts/stops scrolling.

Parameters
NameType
isScrollingboolean
Returns

void

Defined in

dist/index.d.ts:1019


itemContent

Optional itemContent: ItemContent<D, C>

Set the callback to specify the contents of the item.

Defined in

dist/index.d.ts:954


itemSize

Optional itemSize: SizeFunction

Allows customizing the height/width calculation of Item elements.

The default implementation reads el.getBoundingClientRect().height and el.getBoundingClientRect().width.

Defined in

dist/index.d.ts:974


itemsRendered

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

Type declaration

▸ (items): void

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

Parameters
NameType
itemsListItem<D>[]
Returns

void

Defined in

dist/index.d.ts:1049


logLevel

Optional logLevel: LogLevel

set to LogLevel.DEBUG to enable various diagnostics in the console, the most useful being the item measurement reports.

Ensure that you have "all levels" enabled in the browser console too see the messages.

Defined in

dist/index.d.ts:1084


overscan

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

The property accepts pixel values.

Set the overscan property to make the component "chunk" the rendering of new items on scroll. The property causes the component to render more items than the necessary, but reduces the re-renders on scroll. Setting { main: number, reverse: number } lets you extend the list in both the main and the reverse scrollable directions. See the increaseViewportBy property for a similar behavior (equivalent to the overscan in react-window).

Defined in

dist/index.d.ts:908


rangeChanged

Optional rangeChanged: (range: ListRange) => void

Type declaration

▸ (range): void

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

Parameters
NameType
rangeListRange
Returns

void

Defined in

dist/index.d.ts:1032


restoreStateFrom

Optional restoreStateFrom: StateSnapshot

pass a state obtained from the getState() method to restore the list state - this includes the previously measured item sizes and the scroll location. Notice that you should still pass the same data and totalCount properties as before, so that the list can match the data with the stored measurements. This is useful when you want to keep the list state when the component is unmounted and remounted, for example when navigating to a different page.

Defined in

dist/index.d.ts:1090


scrollSeekConfiguration

Optional scrollSeekConfiguration: false | ScrollSeekConfiguration

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

Set components.ScrollSeekPlaceholder to change the placeholder content.

Defined in

dist/index.d.ts:985


scrollerRef

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

Type declaration

▸ (ref): any

Provides access to the root DOM element

Parameters
NameType
refnull | HTMLElement | Window
Returns

any

Defined in

dist/index.d.ts:1066


startReached

Optional startReached: (index: number) => void

Type declaration

▸ (index): void

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

Parameters
NameType
indexnumber
Returns

void

Defined in

dist/index.d.ts:1028


topItemCount

Optional topItemCount: number

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.

Defined in

dist/index.d.ts:930


totalCount

Optional totalCount: number

The total amount of items to be rendered.

Defined in

dist/index.d.ts:890


totalListHeightChanged

Optional totalListHeightChanged: (height: number) => void

Type declaration

▸ (height): void

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

Parameters
NameType
heightnumber
Returns

void

Defined in

dist/index.d.ts:1045


useWindowScroll

Optional useWindowScroll: boolean

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

Defined in

dist/index.d.ts:1058

GroupedVirtuoso Properties

Type parameters

Name
D
C

Hierarchy

  • Omit<VirtuosoProps<D, C>, "totalCount" | "itemContent">

    GroupedVirtuosoProps

Properties

alignToBottom

Optional alignToBottom: boolean

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.

Inherited from

Omit.alignToBottom

Defined in

dist/index.d.ts:1054


atBottomStateChange

Optional atBottomStateChange: (atBottom: boolean) => void

Type declaration

▸ (atBottom): void

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

Parameters
NameType
atBottomboolean
Returns

void

Inherited from

Omit.atBottomStateChange

Defined in

dist/index.d.ts:1037


atBottomThreshold

Optional atBottomThreshold: number

The property accepts pixel values.

By default 4. Redefine to change how much away from the bottom the scroller can be before the list is not considered not at bottom.

Inherited from

Omit.atBottomThreshold

Defined in

dist/index.d.ts:1078


atTopStateChange

Optional atTopStateChange: (atTop: boolean) => void

Type declaration

▸ (atTop): void

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

Parameters
NameType
atTopboolean
Returns

void

Inherited from

Omit.atTopStateChange

Defined in

dist/index.d.ts:1041


atTopThreshold

Optional atTopThreshold: number

The property accepts pixel values.

By default 0. Redefine to change how much away from the top the scroller can be before the list is not considered not at top.

Inherited from

Omit.atTopThreshold

Defined in

dist/index.d.ts:1072


components

Optional components: Components<D, C>

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

Inherited from

Omit.components

Defined in

dist/index.d.ts:950


computeItemKey

Optional computeItemKey: ComputeItemKey<D, C>

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

Inherited from

Omit.computeItemKey

Defined in

dist/index.d.ts:958


context

Optional context: C

Additional context available in the custom components and content callbacks

Inherited from

Omit.context

Defined in

dist/index.d.ts:898


customScrollParent

Optional customScrollParent: HTMLElement

Pass a reference to a scrollable parent element, so that the list won't wrap in its own.

Inherited from

Omit.customScrollParent

Defined in

dist/index.d.ts:1062


data

Optional data: readonly D[]

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

Inherited from

Omit.data

Defined in

dist/index.d.ts:894


defaultItemHeight

Optional defaultItemHeight: number

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.

Inherited from

Omit.defaultItemHeight

Defined in

dist/index.d.ts:968


endReached

Optional endReached: (index: number) => void

Type declaration

▸ (index): void

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.

Parameters
NameType
indexnumber
Returns

void

Inherited from

Omit.endReached

Defined in

dist/index.d.ts:1024


firstItemIndex

Optional firstItemIndex: number

Use when implementing inverse infinite scrolling, decrease the value this property in combination with a change in groupCounts to prepend groups items to the top of the list. Both new groups and extending the top group is supported.

The delta of the firstItemIndex should equal the amount of new items introduced, without the group themselves. As an example, if you prepend 2 groups with 20 and 30 items each, the firstItemIndex should be decreased with 50.

You can also prepend more items to the first group, for example: { groupCounts: [20, 30], firstItemIndex: 1000 } can become { groupCounts: [10, 30, 30], firstItemIndex: 980 }

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

Overrides

Omit.firstItemIndex

Defined in

dist/index.d.ts:265


fixedItemHeight

Optional fixedItemHeight: number

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

Inherited from

Omit.fixedItemHeight

Defined in

dist/index.d.ts:979


followOutput

Optional followOutput: FollowOutput

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
   }
 }} />
Read-only

Inherited from

Omit.followOutput

Defined in

dist/index.d.ts:1004


groupContent

Optional groupContent: GroupContent<C>

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

Defined in

dist/index.d.ts:247


groupCounts

Optional groupCounts: number[]

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.

Defined in

dist/index.d.ts:243


headerFooterTag

Optional headerFooterTag: string

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

Inherited from

Omit.headerFooterTag

Defined in

dist/index.d.ts:1008


increaseViewportBy

Optional increaseViewportBy: number | { bottom: number ; top: number }

The property accepts pixel values.

Set the increaseViewportBy property to artificially increase the viewport size, causing items to be rendered before outside of the viewport. The property causes the component to render more items than the necessary, but can help with slow loading content. Using { top?: number, bottom?: number } lets you set the increase for each end separately.

Inherited from

Omit.increaseViewportBy

Defined in

dist/index.d.ts:921


initialItemCount

Optional initialItemCount: number

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

Inherited from

Omit.initialItemCount

Defined in

dist/index.d.ts:946


initialScrollTop

Optional initialScrollTop: number

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.

Inherited from

Omit.initialScrollTop

Defined in

dist/index.d.ts:941


initialTopMostItemIndex

Optional initialTopMostItemIndex: number | IndexLocationWithAlign

Set to a value between 0 and totalCount - 1 to make the list start scrolled to that item. Pass in an object to achieve additional effects similar to scrollToIndex.

Inherited from

Omit.initialTopMostItemIndex

Defined in

dist/index.d.ts:935


isScrolling

Optional isScrolling: (isScrolling: boolean) => void

Type declaration

▸ (isScrolling): void

Called when the list starts/stops scrolling.

Parameters
NameType
isScrollingboolean
Returns

void

Inherited from

Omit.isScrolling

Defined in

dist/index.d.ts:1019


itemContent

Optional itemContent: GroupItemContent<D, C>

Specifies how each each item gets rendered.

Defined in

dist/index.d.ts:251


itemSize

Optional itemSize: SizeFunction

Allows customizing the height/width calculation of Item elements.

The default implementation reads el.getBoundingClientRect().height and el.getBoundingClientRect().width.

Inherited from

Omit.itemSize

Defined in

dist/index.d.ts:974


itemsRendered

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

Type declaration

▸ (items): void

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

Parameters
NameType
itemsListItem<D>[]
Returns

void

Inherited from

Omit.itemsRendered

Defined in

dist/index.d.ts:1049


logLevel

Optional logLevel: LogLevel

set to LogLevel.DEBUG to enable various diagnostics in the console, the most useful being the item measurement reports.

Ensure that you have "all levels" enabled in the browser console too see the messages.

Inherited from

Omit.logLevel

Defined in

dist/index.d.ts:1084


overscan

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

The property accepts pixel values.

Set the overscan property to make the component "chunk" the rendering of new items on scroll. The property causes the component to render more items than the necessary, but reduces the re-renders on scroll. Setting { main: number, reverse: number } lets you extend the list in both the main and the reverse scrollable directions. See the increaseViewportBy property for a similar behavior (equivalent to the overscan in react-window).

Inherited from

Omit.overscan

Defined in

dist/index.d.ts:908


rangeChanged

Optional rangeChanged: (range: ListRange) => void

Type declaration

▸ (range): void

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

Parameters
NameType
rangeListRange
Returns

void

Inherited from

Omit.rangeChanged

Defined in

dist/index.d.ts:1032


restoreStateFrom

Optional restoreStateFrom: StateSnapshot

pass a state obtained from the getState() method to restore the list state - this includes the previously measured item sizes and the scroll location. Notice that you should still pass the same data and totalCount properties as before, so that the list can match the data with the stored measurements. This is useful when you want to keep the list state when the component is unmounted and remounted, for example when navigating to a different page.

Inherited from

Omit.restoreStateFrom

Defined in

dist/index.d.ts:1090


scrollSeekConfiguration

Optional scrollSeekConfiguration: false | ScrollSeekConfiguration

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

Set components.ScrollSeekPlaceholder to change the placeholder content.

Inherited from

Omit.scrollSeekConfiguration

Defined in

dist/index.d.ts:985


scrollerRef

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

Type declaration

▸ (ref): any

Provides access to the root DOM element

Parameters
NameType
refnull | HTMLElement | Window
Returns

any

Inherited from

Omit.scrollerRef

Defined in

dist/index.d.ts:1066


startReached

Optional startReached: (index: number) => void

Type declaration

▸ (index): void

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

Parameters
NameType
indexnumber
Returns

void

Inherited from

Omit.startReached

Defined in

dist/index.d.ts:1028


topItemCount

Optional topItemCount: number

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.

Inherited from

Omit.topItemCount

Defined in

dist/index.d.ts:930


totalListHeightChanged

Optional totalListHeightChanged: (height: number) => void

Type declaration

▸ (height): void

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

Parameters
NameType
heightnumber
Returns

void

Inherited from

Omit.totalListHeightChanged

Defined in

dist/index.d.ts:1045


useWindowScroll

Optional useWindowScroll: boolean

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

Inherited from

Omit.useWindowScroll

Defined in

dist/index.d.ts:1058

Methods

Methods

autoscrollToBottom

autoscrollToBottom(): void

Use this with combination with follow output if you have images loading in the list. Listen to the image loading and call the method.

Returns

void

Defined in

dist/index.d.ts:872


getState

getState(stateCb): void

Obtains the internal size state of the component, so that it can be restored later. This does not include the data items.

Parameters

NameType
stateCbStateCallback

Returns

void

Defined in

dist/index.d.ts:876


scrollBy

scrollBy(location): void

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

Parameters

NameType
locationScrollToOptions

Returns

void

Defined in

dist/index.d.ts:868


scrollIntoView

scrollIntoView(location): void

Scrolls the item into view if necessary. See the website example for an implementation.

Parameters

NameType
locationFlatScrollIntoViewLocation

Returns

void

Defined in

dist/index.d.ts:860


scrollTo

scrollTo(location): void

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

Parameters

NameType
locationScrollToOptions

Returns

void

Defined in

dist/index.d.ts:864


scrollToIndex

scrollToIndex(location): void

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

Parameters

NameType
locationnumber | FlatIndexLocationWithAlign

Returns

void

Defined in

dist/index.d.ts:856