VirtuosoGrid

VirtuosoGrid

VirtuosoGrid<ItemData, Context>(props): ReactElement

A virtualized grid component for efficiently rendering large datasets in a grid/masonry layout. Automatically calculates visible items based on container and item dimensions.

Type Parameters

Type Parameter	Default type	Description
ItemData	any	The type of data items in the grid
Context	any	The type of additional context passed to callbacks

Parameters

Parameter	Type	Description
props	VirtuosoGridProps<ItemData, Context> & object	VirtuosoGridProps

Returns

ReactElement

Example

tsx

See

• VirtuosoGridProps for available props
• VirtuosoGridHandle for imperative methods
• GridComponents for customizing grid elements

---

VirtuosoGridProps

The props for the VirtuosoGrid component.

See

• VirtuosoGrid for the component
• VirtuosoGridHandle for imperative methods

Extends

• GridRootProps

Type Parameters

Type Parameter	Default type	Description
Data	-	The type of data items in the grid
Context	unknown	The type of additional context passed to callbacks

Properties

atBottomStateChange()?

optional atBottomStateChange: (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

Parameter	Type
atBottom	boolean

Returns

void

---

atTopStateChange()?

optional atTopStateChange: (atTop) => void

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

Parameters

Parameter	Type
atTop	boolean

Returns

void

---

components?: GridComponents<Context>

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

---

computeItemKey?: GridComputeItemKey<Data, Context>

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

---

context?: Context

Additional context available in the custom components and content callbacks

---

customScrollParent?: HTMLElement

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

---

data?: readonly Data[]

The data items to be rendered. If data is set, the total count will be inferred from the length of the array.

---

endReached()?

optional endReached: (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

Parameter	Type
index	number

Returns

void

---

increaseViewportBy?: number | { bottom: number; top: number; }

The property accepts pixel values.

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?: number

Use for server-side rendering - if set, the list will render the specified amount of items regardless of the container / item size.

---

initialTopMostItemIndex?: GridIndexLocation

Set to a value between 0 and totalCount - 1 to make the grid start scrolled to that item. Pass in an object to achieve additional effects similar to scrollToIndex.

---

isScrolling()?

optional isScrolling: (isScrolling) => void

Called when the list starts/stops scrolling.

Parameters

Parameter	Type
isScrolling	boolean

Returns

void

---

itemClassName?: string

Sets the grid items’ className

---

itemContent?: GridItemContent<Data, Context>

Set the callback to specify the contents of the item.

---

listClassName?: string

Sets the className for the list DOM element

---

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.

---

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 grid 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) => void

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

Parameters

Parameter	Type
range	ListRange

Returns

void

---

readyStateChanged()?

optional readyStateChanged: (ready) => void

invoked with true after the grid has done the initial render and the items have been measured.

Parameters

Parameter	Type
ready	boolean

Returns

void

---

restoreStateFrom?: GridStateSnapshot | null

Pass a state obtained from the stateChanged callback to restore the grid state. This includes scroll position and item measurements.

---

scrollerRef()?

optional scrollerRef: (ref) => any

Provides access to the root DOM element

Parameters

Parameter	Type
ref	HTMLElement | null

Returns

any

---

scrollSeekConfiguration?: false | ScrollSeekConfiguration

Use to display placeholders if the user scrolls fast through the list.

Set components.ScrollSeekPlaceholder to change the placeholder content.

---

startReached()?

optional startReached: (index) => void

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

Parameters

Parameter	Type
index	number

Returns

void

---

stateChanged()?

optional stateChanged: (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

Parameter	Type
state	GridStateSnapshot

Returns

void

---

totalCount?: number

The total amount of items to be rendered.

---

useWindowScroll?: boolean

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

---

VirtuosoGridHandle

Exposes the VirtuosoGrid component methods for imperative control. Access via ref on the VirtuosoGrid component.

See

• VirtuosoGrid for the component
• VirtuosoGridProps for available props

Methods

scrollBy()

scrollBy(location): void

Scrolls the component by the specified amount.

Parameters

Parameter	Type	Description
location	ScrollToOptions	The scroll offset options

Returns

void

---

scrollTo()

scrollTo(location): void

Scrolls the component to the specified position.

Parameters

Parameter	Type	Description
location	ScrollToOptions	The scroll position options

Returns

void

---

scrollToIndex()

scrollToIndex(location): void

Scrolls the component to the specified item index.

Parameters

Parameter	Type	Description
location	GridIndexLocation	The item index or location with alignment options

Returns

void

---

GridComponents

Customize the VirtuosoGrid rendering by passing a set of custom components.

Example

tsx

See

VirtuosoGridProps.components for usage in VirtuosoGrid

Type Parameters

Type Parameter	Default type	Description
Context	any	The type of additional context passed to components

Properties

Footer?: ComponentType<ContextProp<Context>>

Set to render a component at the bottom of the list.

---

Header?: ComponentType<ContextProp<Context>>

Set to render a component at the top of the list.

The header remains above the top items and does not remain sticky.

---

Item?: ComponentType<Pick<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "className" | "style" | "children"> & RefAttributes<HTMLDivElement> & object & ContextProp<Context>>

Set to customize the item wrapping element. Use only if you would like to render list from elements different than a div.

---

List?: ComponentType<Pick<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "className" | "style" | "children"> & RefAttributes<HTMLDivElement> & object & ContextProp<Context>>

Set to customize the items wrapper. Use only if you would like to render list from elements different than a div.

---

Scroller?: ComponentType<Pick<DetailedHTMLProps<HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "style" | "tabIndex" | "children"> & RefAttributes<HTMLDivElement> & object & ContextProp<Context>>

Set to customize the outermost scrollable element. This should not be necessary in general, as the component passes its HTML attribute props to it.

---

ScrollSeekPlaceholder?: ComponentType<GridScrollSeekPlaceholderProps & ContextProp<Context>>

Set to render an item placeholder when the user scrolls fast. See the scrollSeekConfiguration property for more details.

---

ElementDimensions

Dimensions of an element in pixels.

Properties

height

number

Height in pixels

---

width

number

Width in pixels

---

Gap

Gap between grid items in pixels.

Properties

column

number

Horizontal gap between columns

---

row

number

Vertical gap between rows

---

GridComputeItemKey

GridComputeItemKey<Data, Context> = (index, item, context) => React.Key

Callback type for computing unique keys for grid items.

Type Parameters

Type Parameter	Description
Data	The type of the data item
Context	The type of context passed from the component

Parameters

Parameter	Type
index	number
item	Data
context	Context

Returns

React.Key

See

VirtuosoGridProps.computeItemKey for usage

---

GridIndexLocation

GridIndexLocation = FlatIndexLocationWithAlign | number

---

GridItem

Type Parameters

Type Parameter
Data

Properties

data?: Data

The data associated with this grid item

---

index

number

The index of the item in the grid

---

GridItemContent

GridItemContent<Data, Context> = (index, data, context) => React.ReactNode

Callback type for rendering item content in a VirtuosoGrid.

Type Parameters

Type Parameter	Description
Data	The type of the data item
Context	The type of context passed from the component

Parameters

Parameter	Type
index	number
data	Data
context	Context

Returns

React.ReactNode

Example

tsx

See

VirtuosoGridProps.itemContent for usage

---

GridItemProps

GridItemProps = Pick<React.ComponentProps<"div">, "children" | "className" | "style"> & React.RefAttributes<HTMLDivElement> & object

Passed to the GridComponents.Item custom component

Type Declaration

data-index

number

---

GridListProps

GridListProps = Pick<React.ComponentProps<"div">, "children" | "className" | "style"> & React.RefAttributes<HTMLDivElement> & object

Passed to the GridComponents.List custom component

Type Declaration

data-testid

string

---

GridRootProps

GridRootProps = Omit<React.HTMLProps<HTMLDivElement>, "data" | "ref">

---

GridScrollSeekPlaceholderProps

Passed to the GridComponents.ScrollSeekPlaceholder custom component

Properties

height

number

The height of the placeholder in pixels

---

index

number

The index of the item being replaced by the placeholder

---

width

number

The width of the placeholder in pixels

---

GridStateSnapshot

A snapshot of the VirtuosoGrid state that can be saved and restored. Use this to persist scroll position and layout across page reloads.

See

• VirtuosoGridProps.restoreStateFrom for restoring state
• VirtuosoGridProps.stateChanged for capturing state

Properties

gap

Gap

Gap between items

---

item

ElementDimensions

Item dimensions

---

scrollTop

number

Scroll position in pixels

---

viewport

ElementDimensions

Viewport dimensions

---

VirtuosoGridMockContext

const VirtuosoGridMockContext: Context<VirtuosoGridMockContextValue | undefined>

React context for mocking VirtuosoGrid component measurements in tests. Wrap your VirtuosoGrid component with this provider to bypass DOM measurements.

Example

tsx

---

VirtuosoGridMockContextValue

Mock context value for testing VirtuosoGrid components. Provides fixed dimensions to bypass DOM measurements.

Properties

itemHeight

number

Fixed height for each grid item in pixels

---

itemWidth

number

Fixed width for each grid item in pixels

---

viewportHeight

number

Fixed viewport height in pixels

---

viewportWidth

number

Fixed viewport width in pixels