Table Virtuoso API Reference
All properties are optional - by default, the component will render empty.
If you are using TypeScript and want to use correctly typed component ref, you can use the VirtuosoHandle.
import { TableVirtuoso, VirtuosoHandle } from 'react-virtuoso'
//...
const ref = useRef<VirtuosoHandle>(null)
//...
<TableVirtuoso ref={ref} /*...*/
Table Virtuoso Properties
Type parameters
| Name |
|---|
D |
C |
Hierarchy
Omit<VirtuosoProps<D,C>,"components"|"headerFooterTag"|"topItemCount">↳
TableVirtuosoProps
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.
Overrides
Omit.alignToBottom
Defined in
dist/index.d.ts:693
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
Overrides
Omit.atBottomStateChange
Defined in
dist/index.d.ts:676
atBottomThreshold
• Optional atBottomThreshold: number
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.
Overrides
Omit.atBottomThreshold
Defined in
dist/index.d.ts:713
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
Overrides
Omit.atTopStateChange
Defined in
dist/index.d.ts:680
atTopThreshold
• Optional atTopThreshold: number
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.
Overrides
Omit.atTopThreshold
Defined in
dist/index.d.ts:709
components
• Optional components: TableComponents<D, C>
Use the components property for advanced customization of the elements rendered by the table.
Defined in
dist/index.d.ts:543
computeItemKey
• Optional computeItemKey: ComputeItemKey<D, C>
If specified, the component will use the function to generate the key property for each list item.
Overrides
Omit.computeItemKey
Defined in
dist/index.d.ts:601
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 table won't wrap in its own.
Overrides
Omit.customScrollParent
Defined in
dist/index.d.ts:701
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.
Overrides
Omit.data
Defined in
dist/index.d.ts:559
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.
Overrides
Omit.defaultItemHeight
Defined in
dist/index.d.ts:611
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
Overrides
Omit.endReached
Defined in
dist/index.d.ts:663
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.
Overrides
Omit.firstItemIndex
Defined in
dist/index.d.ts:654
fixedFooterContent
• Optional fixedFooterContent: FixedFooterContent
Set the contents of the table footer.
Defined in
dist/index.d.ts:551
fixedHeaderContent
• Optional fixedHeaderContent: FixedHeaderContent
Set the contents of the table header.
Defined in
dist/index.d.ts:547
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.
Overrides
Omit.fixedItemHeight
Defined in
dist/index.d.ts:622
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
}
}} />Overrides
Omit.followOutput
Defined in
dist/index.d.ts:647
increaseViewportBy
• Optional increaseViewportBy: number | { bottom: number ; top: number }
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.
Overrides
Omit.increaseViewportBy
Defined in
dist/index.d.ts:575
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.
Overrides
Omit.initialItemCount
Defined in
dist/index.d.ts:593
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.
Overrides
Omit.initialScrollTop
Defined in
dist/index.d.ts:588
initialTopMostItemIndex
• Optional initialTopMostItemIndex: number
Set to a value between 0 and totalCount - 1 to make the list start scrolled to that item.
Overrides
Omit.initialTopMostItemIndex
Defined in
dist/index.d.ts:582
isScrolling
• Optional isScrolling: (isScrolling: boolean) => void
Type declaration
▸ (isScrolling): void
Called when the list starts/stops scrolling.
Parameters
| Name | Type |
|---|---|
isScrolling | boolean |
Returns
void
Overrides
Omit.isScrolling
Defined in
dist/index.d.ts:658
itemContent
• Optional itemContent: ItemContent<D, C>
Set the callback to specify the contents of the item.
Overrides
Omit.itemContent
Defined in
dist/index.d.ts:597
itemSize
• Optional itemSize: SizeFunction
Allows customizing the height/width calculation of Item elements.
The default implementation reads el.getBoundingClientRect().height and el.getBoundingClientRect().width.
Overrides
Omit.itemSize
Defined in
dist/index.d.ts:617
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
Overrides
Omit.itemsRendered
Defined in
dist/index.d.ts:688
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 }
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).
Overrides
Omit.overscan
Defined in
dist/index.d.ts:566
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
Overrides
Omit.rangeChanged
Defined in
dist/index.d.ts:671
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.
Overrides
Omit.restoreStateFrom
Defined in
dist/index.d.ts:719
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.
Overrides
Omit.scrollSeekConfiguration
Defined in
dist/index.d.ts:628
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
Overrides
Omit.scrollerRef
Defined in
dist/index.d.ts:705
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
Overrides
Omit.startReached
Defined in
dist/index.d.ts:667
totalCount
• Optional totalCount: number
The total amount of items to be rendered.
Overrides
Omit.totalCount
Defined in
dist/index.d.ts:555
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
Overrides
Omit.totalListHeightChanged
Defined in
dist/index.d.ts:684
useWindowScroll
• Optional useWindowScroll: boolean
Uses the document scroller rather than wrapping the list in its own.
Overrides
Omit.useWindowScroll
Defined in
dist/index.d.ts:697
Methods
Methods
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:536
scrollBy
▸ scrollBy(location): void
Parameters
| Name | Type |
|---|---|
location | ScrollToOptions |
Returns
void
Defined in
dist/index.d.ts:532
scrollIntoView
▸ scrollIntoView(location): void
Parameters
| Name | Type |
|---|---|
location | number | FlatScrollIntoViewLocation |
Returns
void
Defined in
dist/index.d.ts:529
scrollTo
▸ scrollTo(location): void
Parameters
| Name | Type |
|---|---|
location | ScrollToOptions |
Returns
void
Defined in
dist/index.d.ts:531
scrollToIndex
▸ scrollToIndex(location): void
Parameters
| Name | Type |
|---|---|
location | number | FlatIndexLocationWithAlign |
Returns
void
Defined in
dist/index.d.ts:530