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
"components".TableVirtuosoProps
Type parameters
Name |
---|
D |
C |
Hierarchy
{}
↳ TableVirtuosoProps
Properties
alignToBottom
• Optional
alignToBottom: boolean
Defined in src/components.tsx:437
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 src/components.tsx:416
Called with true / false when the list has reached the bottom / gets scrolled up.
Can be used to load newer items, like tail -f
.
atBottomThreshold
• Optional
atBottomThreshold: number
Defined in src/components.tsx:462
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.
atTopStateChange
• Optional
atTopStateChange: (atTop: boolean) => void
Defined in src/components.tsx:421
Called with true
/ false
when the list has reached the top / gets scrolled down.
atTopThreshold
• Optional
atTopThreshold: number
Defined in src/components.tsx:457
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.
components
• Optional
components: TableComponents<C>
Defined in src/components.tsx:273
Use the components
property for advanced customization of the elements rendered by the table.
computeItemKey
• Optional
computeItemKey: ComputeItemKey<D, C>
Defined in src/components.tsx:330
If specified, the component will use the function to generate the key
property for each list item.
customScrollParent
• Optional
customScrollParent: HTMLElement
Defined in src/components.tsx:447
Pass a reference to a scrollable parent element, so that the table won't wrap in its own.
data
• Optional
data: readonly D[]
Defined in src/components.tsx:287
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 src/components.tsx:341
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 src/components.tsx:400
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 src/components.tsx:389
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.
fixedHeaderContent
• Optional
fixedHeaderContent: FixedHeaderContent
Defined in src/components.tsx:277
Set the contents of the table header.
fixedItemHeight
• Optional
fixedItemHeight: number
Defined in src/components.tsx:354
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 src/components.tsx:381
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
}
}} />
increaseViewportBy
• Optional
increaseViewportBy: number | { bottom: number ; top: number }
Defined in src/components.tsx:302
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.
initialItemCount
• Optional
initialItemCount: number
Defined in src/components.tsx:320
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 src/components.tsx:314
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 src/components.tsx:307
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 src/components.tsx:394
Called when the list starts/stops scrolling.
itemContent
• Optional
itemContent: ItemContent<D, C>
Defined in src/components.tsx:325
Set the callback to specify the contents of the item.
itemSize
• Optional
itemSize: (el: HTMLElement, field: "offsetHeight" | "offsetWidth") => number
Defined in src/components.tsx:348
Allows customizing the height/width calculation of Item
elements.
The default implementation reads el.getBoundingClientRect().height
and el.getBoundingClientRect().width
.
itemsRendered
• Optional
itemsRendered: (items: ListItem<D>[]) => void
Defined in src/components.tsx:431
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 src/components.tsx:295
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
).
rangeChanged
• Optional
rangeChanged: (range: ListRange) => void
Defined in src/components.tsx:410
Called with the new set of items each time the list items are rendered due to scrolling.
react18ConcurrentRendering
• Optional
react18ConcurrentRendering: boolean
Defined in src/components.tsx:467
No longer necessary after 2.10.2. component should work out of the box.
scrollSeekConfiguration
• Optional
scrollSeekConfiguration: ScrollSeekConfiguration | false
Defined in src/components.tsx:361
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 src/components.tsx:452
Provides access to the root DOM element
startReached
• Optional
startReached: (index: number) => void
Defined in src/components.tsx:405
Called when the user scrolls to the start of the list.
totalCount
• Optional
totalCount: number
Defined in src/components.tsx:282
The total amount of items to be rendered.
totalListHeightChanged
• Optional
totalListHeightChanged: (height: number) => void
Defined in src/components.tsx:426
Called when the total list height is changed due to new items or viewport resize.
useWindowScroll
• Optional
useWindowScroll: boolean
Defined in src/components.tsx:442
Uses the document scroller rather than wrapping the list in its own.
Methods
"components".VirtuosoHandle
Hierarchy
- VirtuosoHandle
Methods
scrollBy
▸ scrollBy(location
: ScrollToOptions): void
Defined in src/components.tsx:579
Scrolls the component with the specified amount. See ScrollToOptions (MDN)
Parameters:
Name | Type |
---|---|
location | ScrollToOptions |
Returns: void
scrollIntoView
▸ scrollIntoView(location
: FlatScrollIntoViewLocation): void
Defined in src/components.tsx:571
Scrolls the item into view if necessary. See the website example for an implementation.
Parameters:
Name | Type |
---|---|
location | FlatScrollIntoViewLocation |
Returns: void
scrollTo
▸ scrollTo(location
: ScrollToOptions): void
Defined in src/components.tsx:575
Scrolls the component to the specified location. See ScrollToOptions (MDN)
Parameters:
Name | Type |
---|---|
location | ScrollToOptions |
Returns: void
scrollToIndex
▸ scrollToIndex(location
: number | FlatIndexLocationWithAlign): void
Defined in src/components.tsx:567
Scrolls the component to the specified item index. See IndexLocationWithAlign for more options.
Parameters:
Name | Type |
---|---|
location | number | FlatIndexLocationWithAlign |
Returns: void