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

Properties

"components".VirtuosoGridProps

Type parameters

Name
T

Hierarchy

  • {} & {} & {} & GridRootProps & RefAttributes<MethodsFromPropMap<SystemSpec<[SystemSpec<[SystemSpec<[SystemSpec<any[], (Anonymous function)>], (Anonymous function)>, SystemSpec<any[], (Anonymous function)>, SystemSpec<[SystemSpec<any[], (Anonymous function)>], (Anonymous function)>, SystemSpec<[SystemSpec<any[], (Anonymous function)>, SystemSpec<[SystemSpec<any[], (Anonymous function)>], (Anonymous function)>], (Anonymous function)>, SystemSpec<[SystemSpec<any[], (Anonymous function)>], (Anonymous function)>, SystemSpec<[SystemSpec<any[], (Anonymous function)>], (Anonymous function)>], (Anonymous function)>, SystemSpec<SystemSpecs, (Anonymous function)>], (Anonymous function)>, { events: { atBottomStateChange: "atBottomStateChange" = "atBottomStateChange"; atTopStateChange: "atTopStateChange" = "atTopStateChange"; endReached: "endReached" = "endReached"; isScrolling: "isScrolling" = "isScrolling"; rangeChanged: "rangeChanged" = "rangeChanged"; startReached: "startReached" = "startReached" } ; methods: { scrollBy: "scrollBy" = "scrollBy"; scrollTo: "scrollTo" = "scrollTo"; scrollToIndex: "scrollToIndex" = "scrollToIndex" } ; optional: { ItemContainer: "ItemContainer" = "ItemContainer"; ListContainer: "ListContainer" = "ListContainer"; ScrollContainer: "ScrollContainer" = "ScrollContainer"; components: "components" = "components"; computeItemKey: "computeItemKey" = "computeItemKey"; initialItemCount: "initialItemCount" = "initialItemCount"; item: "item" = "item"; itemClassName: "itemClassName" = "itemClassName"; itemContent: "itemContent" = "itemContent"; listClassName: "listClassName" = "listClassName"; overscan: "overscan" = "overscan"; scrollSeek: "scrollSeek" = "scrollSeek"; scrollSeekConfiguration: "scrollSeekConfiguration" = "scrollSeekConfiguration"; scrollerRef: "scrollerRef" = "scrollerRef"; totalCount: "totalCount" = "totalCount"; useWindowScroll: "useWindowScroll" = "useWindowScroll" } }>>

    VirtuosoGridProps

Properties

atBottomStateChange

Optional atBottomStateChange: (atBottom: boolean) => void

Defined in src/components.tsx:291

Called with true / false when the list has reached the bottom / gets scrolled up. Can be used to load newer items, like tail -f.


atTopStateChange

Optional atTopStateChange: (atTop: boolean) => void

Defined in src/components.tsx:296

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


components

Optional components: GridProps["components"]

Defined in src/components.tsx:245

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


computeItemKey

Optional computeItemKey: GridProps["computeItemKey"]

Defined in src/components.tsx:257

If specified, the component will use the function to generate the key property for each list item.


endReached

Optional endReached: (index: number) => void

Defined in src/components.tsx:275

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.


isScrolling

Optional isScrolling: (isScrolling: boolean) => void

Defined in src/components.tsx:269

Called when the list starts/stops scrolling.


itemClassName

Optional itemClassName: string

Defined in src/components.tsx:311

Sets the grid items' className


itemContent

Optional itemContent: GridProps["itemContent"]

Defined in src/components.tsx:240

Set the callback to specify the contents of the item.


key

Optional key: Key | null

Inherited from VirtuosoGridProps.key

Defined in node_modules/@types/react/index.d.ts:137


listClassName

Optional listClassName: string

Defined in src/components.tsx:306

Sets the className for the list DOM element


overscan

Optional overscan: number | { main: number ; reverse: number }

Defined in src/components.tsx:252

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.


rangeChanged

Optional rangeChanged: (range: ListRange) => void

Defined in src/components.tsx:285

Called with the new set of items each time the list items are rendered due to scrolling.


ref

Optional ref: Ref<T>

Inherited from VirtuosoGridProps.ref

Defined in node_modules/@types/react/index.d.ts:140


scrollSeekConfiguration

Optional scrollSeekConfiguration: ScrollSeekConfiguration | false

Defined in src/components.tsx:264

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 | null) => any

Defined in src/components.tsx:301

Provides access to the root DOM element


startReached

Optional startReached: (index: number) => void

Defined in src/components.tsx:280

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


totalCount

totalCount: GridProps["totalCount"]

Defined in src/components.tsx:235

The total amount of items to be rendered.


useWindowScroll

Optional useWindowScroll: boolean

Defined in src/components.tsx:316

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

Methods

"components".VirtuosoHandle

Hierarchy

  • {}

    VirtuosoHandle

Methods

scrollBy

scrollBy(location: ScrollToOptions): void

Defined in src/components.tsx:335

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

Parameters:

NameType
locationScrollToOptions

Returns: void


scrollIntoView

scrollIntoView(location: ScrollIntoViewLocation): void

Defined in src/components.tsx:327

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

Parameters:

NameType
locationScrollIntoViewLocation

Returns: void


scrollTo

scrollTo(location: ScrollToOptions): void

Defined in src/components.tsx:331

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

Parameters:

NameType
locationScrollToOptions

Returns: void


scrollToIndex

scrollToIndex(location: number | IndexLocationWithAlign): void

Defined in src/components.tsx:323

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

Parameters:

NameType
locationnumber | IndexLocationWithAlign

Returns: void