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-onlyVirtuoso Properties
Type parameters
Name |
---|
D |
C |
Hierarchy
↳
VirtuosoProps
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
Name | Type |
---|---|
atBottom | boolean |
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
Name | Type |
---|---|
atTop | boolean |
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
Name | Type |
---|---|
index | number |
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-onlyDefined 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
Name | Type |
---|---|
isScrolling | boolean |
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
Name | Type |
---|---|
items | ListItem <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
Name | Type |
---|---|
range | ListRange |
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
Name | Type |
---|---|
ref | null | 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
Name | Type |
---|---|
index | number |
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
Name | Type |
---|---|
height | number |
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
Name | Type |
---|---|
atBottom | boolean |
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
Name | Type |
---|---|
atTop | boolean |
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
Name | Type |
---|---|
index | number |
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-onlyInherited 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
Name | Type |
---|---|
isScrolling | boolean |
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
Name | Type |
---|---|
items | ListItem <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
Name | Type |
---|---|
range | ListRange |
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
Name | Type |
---|---|
ref | null | 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
Name | Type |
---|---|
index | number |
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
Name | Type |
---|---|
height | number |
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
Name | Type |
---|---|
stateCb | StateCallback |
Returns
void
Defined in
dist/index.d.ts:876
scrollBy
▸ scrollBy(location
): void
Scrolls the component with the specified amount. See ScrollToOptions (MDN)
Parameters
Name | Type |
---|---|
location | ScrollToOptions |
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
Name | Type |
---|---|
location | FlatScrollIntoViewLocation |
Returns
void
Defined in
dist/index.d.ts:860
scrollTo
▸ scrollTo(location
): void
Scrolls the component to the specified location. See ScrollToOptions (MDN)
Parameters
Name | Type |
---|---|
location | ScrollToOptions |
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
Name | Type |
---|---|
location | number | FlatIndexLocationWithAlign |
Returns
void
Defined in
dist/index.d.ts:856