Skip to main content

Virtuoso Grid 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 VirtuosoGridHandle types.

import { VirtuosoGrid, VirtuosoGridHandle } from 'react-virtuoso'
//...
const ref = useRef<VirtuosoGridHandle>(null)
//...
<VirtuosoGrid ref={ref} /*...*/

Read-only

Properties

Type parameters

NameType
DD
Cunknown

Hierarchy

Properties

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

Defined in

dist/index.d.ts:818


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

Defined in

dist/index.d.ts:822


components

Optional components: GridComponents<C>

Use the components property for advanced customization of the elements rendered by the list.

Defined in

dist/index.d.ts:772


computeItemKey

Optional computeItemKey: GridComputeItemKey<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:785


context

Optional context: C

Additional context available in the custom components and content callbacks

Defined in

dist/index.d.ts:759


customScrollParent

Optional customScrollParent: HTMLElement

Pass a reference to a scrollable parent element, so that the grid won't wrap in its own.

Defined in

dist/index.d.ts:842


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


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

Defined in

dist/index.d.ts:800


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


initialTopMostItemIndex

Optional initialTopMostItemIndex: GridIndexLocation

Defined in

dist/index.d.ts:849


isScrolling

Optional isScrolling: (isScrolling: boolean) => void

Type declaration

▸ (isScrolling): void

Called when the list starts/stops scrolling.

Parameters
NameType
isScrollingboolean
Returns

void

Defined in

dist/index.d.ts:795


itemClassName

Optional itemClassName: string

Sets the grid items' className

Defined in

dist/index.d.ts:834


itemContent

Optional itemContent: GridItemContent<D, C>

Set the callback to specify the contents of the item.

Defined in

dist/index.d.ts:768


listClassName

Optional listClassName: string

Sets the className for the list DOM element

Defined in

dist/index.d.ts:830


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


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.

Defined in

dist/index.d.ts:778


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

Defined in

dist/index.d.ts:808


restoreStateFrom

Optional restoreStateFrom: null | GridStateSnapshot

Defined in

dist/index.d.ts:813


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


scrollerRef

Optional scrollerRef: (ref: null | HTMLElement) => any

Type declaration

▸ (ref): any

Provides access to the root DOM element

Parameters
NameType
refnull | HTMLElement
Returns

any

Defined in

dist/index.d.ts:826


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

Defined in

dist/index.d.ts:804


stateChanged

Optional stateChanged: (state: GridStateSnapshot) => void

Type declaration

▸ (state): void

reports when the grid state changes. The reported value can be stored and passed back to restoreStateFrom to restore the grid to the same state.

Parameters
NameType
stateGridStateSnapshot
Returns

void

Defined in

dist/index.d.ts:812


totalCount

Optional totalCount: number

The total amount of items to be rendered.

Defined in

dist/index.d.ts:751


useWindowScroll

Optional useWindowScroll: boolean

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

Defined in

dist/index.d.ts:838

Methods

Methods

scrollBy

scrollBy(location): void

Parameters

NameType
locationScrollToOptions

Returns

void

Defined in

dist/index.d.ts:735


scrollTo

scrollTo(location): void

Parameters

NameType
locationScrollToOptions

Returns

void

Defined in

dist/index.d.ts:734


scrollToIndex

scrollToIndex(location): void

Parameters

NameType
locationGridIndexLocation

Returns

void

Defined in

dist/index.d.ts:733