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

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

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

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

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

atTopThreshold

• Optional atTopThreshold: number

Defined in src/components.tsx:468

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

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

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

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

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

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

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

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.

fixedFooterContent

• Optional fixedFooterContent: FixedFooterContent

Defined in src/components.tsx:288

Set the contents of the table footer.

fixedHeaderContent

• Optional fixedHeaderContent: FixedHeaderContent

Defined in src/components.tsx:283

Set the contents of the table header.

fixedItemHeight

• Optional fixedItemHeight: number

Defined in src/components.tsx:365

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

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

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

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

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

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

Called when the list starts/stops scrolling.

itemContent

• Optional itemContent: ItemContent<D, C>

Defined in src/components.tsx:336

Set the callback to specify the contents of the item.

itemSize

• Optional itemSize: SizeFunction

Defined in src/components.tsx:359

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

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

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

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

No longer necessary after 2.10.2. component should work out of the box.

scrollSeekConfiguration

• Optional scrollSeekConfiguration: ScrollSeekConfiguration | false

Defined in src/components.tsx:372

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

Provides access to the root DOM element

startReached

• Optional startReached: (index: number) => void

Defined in src/components.tsx:416

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

totalCount

• Optional totalCount: number

Defined in src/components.tsx:293

The total amount of items to be rendered.

totalListHeightChanged

• Optional totalListHeightChanged: (height: number) => void

Defined in src/components.tsx:437

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

useWindowScroll

• Optional useWindowScroll: boolean

Defined in src/components.tsx:453

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

Methods

"components".VirtuosoHandle

Hierarchy

  • VirtuosoHandle

Methods

autoscrollToBottom

▸ autoscrollToBottom(): void

Defined in src/components.tsx:605

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

scrollBy

▸ scrollBy(location: ScrollToOptions): void

Defined in src/components.tsx:601

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

Parameters:

NameType
locationScrollToOptions

Returns: void

scrollIntoView

▸ scrollIntoView(location: FlatScrollIntoViewLocation): void

Defined in src/components.tsx:593

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

Parameters:

NameType
locationFlatScrollIntoViewLocation

Returns: void

scrollTo

▸ scrollTo(location: ScrollToOptions): void

Defined in src/components.tsx:597

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

Parameters:

NameType
locationScrollToOptions

Returns: void

scrollToIndex

▸ scrollToIndex(location: number | FlatIndexLocationWithAlign): void

Defined in src/components.tsx:589

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

Parameters:

NameType
locationnumber | FlatIndexLocationWithAlign

Returns: void

Edit this page