Skip to main content

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

Read-only

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:670


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

Overrides

Omit.atBottomStateChange

Defined in

dist/index.d.ts:653


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:690


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

Overrides

Omit.atTopStateChange

Defined in

dist/index.d.ts:657


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:686


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:520


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:578


context

Optional context: C

Additional context available in the custom components and content callbacks

Inherited from

Omit.context

Defined in

dist/index.d.ts:863


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:678


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:536


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:588


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

Overrides

Omit.endReached

Defined in

dist/index.d.ts:640


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:631


fixedFooterContent

Optional fixedFooterContent: FixedFooterContent

Set the contents of the table footer.

Defined in

dist/index.d.ts:528


fixedHeaderContent

Optional fixedHeaderContent: FixedHeaderContent

Set the contents of the table header.

Defined in

dist/index.d.ts:524


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:599


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

Overrides

Omit.followOutput

Defined in

dist/index.d.ts:624


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:552


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:570


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:565


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:559


isScrolling

Optional isScrolling: (isScrolling: boolean) => void

Type declaration

▸ (isScrolling): void

Called when the list starts/stops scrolling.

Parameters
NameType
isScrollingboolean
Returns

void

Overrides

Omit.isScrolling

Defined in

dist/index.d.ts:635


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:574


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:594


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

Overrides

Omit.itemsRendered

Defined in

dist/index.d.ts:665


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:1049


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:543


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

Overrides

Omit.rangeChanged

Defined in

dist/index.d.ts:648


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:1055


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:605


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

Overrides

Omit.scrollerRef

Defined in

dist/index.d.ts:682


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

Overrides

Omit.startReached

Defined in

dist/index.d.ts:644


totalCount

Optional totalCount: number

The total amount of items to be rendered.

Overrides

Omit.totalCount

Defined in

dist/index.d.ts:532


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

Overrides

Omit.totalListHeightChanged

Defined in

dist/index.d.ts:661


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:674

Methods

Methods

scrollBy

scrollBy(location): void

Parameters

NameType
locationScrollToOptions

Returns

void

Defined in

dist/index.d.ts:513


scrollIntoView

scrollIntoView(location): void

Parameters

NameType
locationnumber | FlatScrollIntoViewLocation

Returns

void

Defined in

dist/index.d.ts:510


scrollTo

scrollTo(location): void

Parameters

NameType
locationScrollToOptions

Returns

void

Defined in

dist/index.d.ts:512


scrollToIndex

scrollToIndex(location): void

Parameters

NameType
locationnumber | FlatIndexLocationWithAlign

Returns

void

Defined in

dist/index.d.ts:511