GroupedVirtuoso

GroupedVirtuoso

GroupedVirtuoso<ItemData, Context>(props): ReactElement

A virtualized list component for rendering grouped data with sticky group headers. Extends Virtuoso with support for collapsible groups and group-level navigation.

Type Parameters

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

Parameters

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

Returns

ReactElement

Example

tsx

See

• GroupedVirtuosoProps for available props
• GroupedVirtuosoHandle for imperative methods

---

GroupedVirtuosoProps

The props for the GroupedVirtuoso component.

See

• GroupedVirtuoso for the component
• GroupedVirtuosoHandle for imperative methods

Extends

• Omit<VirtuosoProps<Data, Context>, "itemContent" | "totalCount">

Type Parameters

Type Parameter	Description
Data	The type of data items in the list
Context	The type of additional context passed to callbacks

Properties

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.

Inherited from

Omit.alignToBottom

---

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

Inherited from

Omit.atBottomStateChange

---

atBottomThreshold?: number

The property accepts pixel values.

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.

Inherited from

Omit.atBottomThreshold

---

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

Inherited from

Omit.atTopStateChange

---

atTopThreshold?: number

The property accepts pixel values.

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.

Inherited from

Omit.atTopThreshold

---

components?: Components<Data, Context>

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

Inherited from

Omit.components

---

computeItemKey?: ComputeItemKey<Data, Context>

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

Inherited from

Omit.computeItemKey

---

context?: Context

Additional context available in the custom components and content callbacks

Inherited from

Omit.context

---

customScrollParent?: HTMLElement

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

Inherited from

Omit.customScrollParent

---

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.

Inherited from

Omit.data

---

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.

Inherited from

Omit.defaultItemHeight

---

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

Inherited from

Omit.endReached

---

firstItemIndex?: number

Use when implementing inverse infinite scrolling, decrease the value this property in combination with a change in groupCounts to prepend groups items to the top of the list. Both new groups and extending the top group is supported.

The delta of the firstItemIndex should equal the amount of new items introduced, without the group themselves. As an example, if you prepend 2 groups with 20 and 30 items each, the firstItemIndex should be decreased with 50.

You can also prepend more items to the first group, for example: { groupCounts: [20, 30], firstItemIndex: 1000 } can become { groupCounts: [10, 30, 30], firstItemIndex: 980 }

Warning: the firstItemIndex should be a positive number, based on the total amount of items to be displayed.

Overrides

Omit.firstItemIndex

---

fixedGroupHeight?: number

Can be used to improve performance if the rendered group header items are of known size. Setting it causes the component to skip measuring group headers. The value is in pixels. This value has no effect if fixedItemHeight is not set.

Inherited from

VirtuosoProps.fixedGroupHeight

---

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.

Inherited from

Omit.fixedItemHeight

---

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:

tsx

Inherited from

Omit.followOutput

---

groupContent?: GroupContent<Context>

Specifies how each each group header gets rendered. The callback receives the zero-based index of the group.

---

groupCounts?: number[]

Specifies the amount of items in each group (and, actually, how many groups are there). For example, passing [20, 30] will display 2 groups with 20 and 30 items each.

---

headerFooterTag?: string

Set to customize the wrapper tag for the header and footer components (default is div).

Inherited from

Omit.headerFooterTag

---

heightEstimates?: number[]

Use when you have items with widely varying heights and can estimate each item’s height upfront.

Pass an array of estimated heights for each item (by index). This helps the component calculate a more accurate initial total height for the list, reducing layout shifts during initial scrolling.

The estimates don’t need to be exact - they’re used to build the initial size tree before actual measurements are taken. Once items are rendered and measured, their real heights replace the estimates.

Example

tsx

Inherited from

VirtuosoProps.heightEstimates

---

horizontalDirection?: boolean

When set, turns the scroller into a horizontal list. The items are positioned with inline-block.

Inherited from

Omit.horizontalDirection

---

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.

Inherited from

Omit.increaseViewportBy

---

initialItemCount?: number

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

Inherited from

Omit.initialItemCount

---

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.

Inherited from

Omit.initialScrollTop

---

initialTopMostItemIndex?: number | IndexLocationWithAlign

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

Inherited from

Omit.initialTopMostItemIndex

---

isScrolling()?

optional isScrolling: (isScrolling) => void

Called when the list starts/stops scrolling.

Parameters

Parameter	Type
isScrolling	boolean

Returns

void

Inherited from

Omit.isScrolling

---

itemContent?: GroupItemContent<Data, Context>

Specifies how each each item gets rendered.

---

itemSize?: SizeFunction

Allows customizing the height/width calculation of Item elements.

The default implementation reads el.getBoundingClientRect().height and el.getBoundingClientRect().width.

Inherited from

Omit.itemSize

---

itemsRendered()?

optional itemsRendered: (items) => void

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

Parameters

Parameter	Type
items	ListItem<Data>[]

Returns

void

Inherited from

Omit.itemsRendered

---

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

---

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

Set the minimum number of items to render before and after the visible viewport boundaries. This is useful when rendering items with dynamic or very tall content, where the pixel-based increaseViewportBy may not be sufficient to prevent empty areas during rapid resizing or scrolling. Using { top?: number, bottom?: number } lets you set the count for each end separately.

Inherited from

Omit.minOverscanItemCount

---

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

The property accepts pixel values.

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).

Inherited from

Omit.overscan

---

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

Inherited from

Omit.rangeChanged

---

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

---

scrollerRef()?

optional scrollerRef: (ref) => any

Provides access to the root DOM element

Parameters

Parameter	Type
ref	HTMLElement | Window | null

Returns

any

Inherited from

Omit.scrollerRef

---

scrollIntoViewOnChange()?

optional scrollIntoViewOnChange: (params) => false | ScrollIntoViewLocation | null | undefined

Implement this callback if you want to adjust the list position when the list total count changes. Return a ScrollIntoViewLocation object to scroll to a specific item, or falsey value to avoid scrolling. Use the context contents if you need to implement custom logic based on the current state of the list.

Parameters

Parameter	Type
params	{ context: Context; scrollingInProgress: boolean; totalCount: number; }
params.context	Context
params.scrollingInProgress	boolean
params.totalCount	number

Returns

false | ScrollIntoViewLocation | null | undefined

Inherited from

Omit.scrollIntoViewOnChange

---

scrollSeekConfiguration?: false | ScrollSeekConfiguration

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

Set components.ScrollSeekPlaceholder to change the placeholder content.

Inherited from

Omit.scrollSeekConfiguration

---

skipAnimationFrameInResizeObserver?: boolean

When set, the resize observer used to measure the items will not use requestAnimationFrame to report the size changes. Setting this to true will improve performance and reduce flickering, but will cause benign errors to be reported in the console if the size of the items changes while they are being measured. See https://github.com/petyosi/react-virtuoso/issues/1049 for more information.

Inherited from

Omit.skipAnimationFrameInResizeObserver

---

startReached()?

optional startReached: (index) => void

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

Parameters

Parameter	Type
index	number

Returns

void

Inherited from

Omit.startReached

---

topItemCount?: number

Set the amount of items to remain fixed at the top of the list.

For a header that scrolls away when scrolling, check the components.Header property.

Inherited from

Omit.topItemCount

---

totalListHeightChanged()?

optional totalListHeightChanged: (height) => void

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

Parameters

Parameter	Type
height	number

Returns

void

Inherited from

Omit.totalListHeightChanged

---

useWindowScroll?: boolean

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

Inherited from

Omit.useWindowScroll

---

GroupedVirtuosoHandle

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

See

• GroupedVirtuoso for the component
• GroupedVirtuosoProps for available props

Methods

autoscrollToBottom()

autoscrollToBottom(): void

Scrolls to the bottom of the list if follow output is active. Useful when images load in the list.

Returns

void

---

getState()

getState(stateCb): void

Obtains the internal size state of the component, so that it can be restored later. This does not include the data items.

Parameters

Parameter	Type	Description
stateCb	StateCallback	Callback that receives the state snapshot

Returns

void

---

scrollBy()

scrollBy(location): void

Scrolls the component by the specified amount.

Parameters

Parameter	Type	Description
location	ScrollToOptions	The scroll offset options

Returns

void

---

scrollIntoView()

scrollIntoView(location): void

Scrolls the specified item into view if it’s not already visible.

Parameters

Parameter	Type	Description
location	number | ScrollIntoViewLocation	The item index or scroll location 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	number | IndexLocationWithAlign	The item index or location with alignment options

Returns

void

---

GroupContent

GroupContent<Context> = (index, context) => React.ReactNode

Callback type for rendering group header content in GroupedVirtuoso.

Type Parameters

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

Parameters

Parameter	Type
index	number
context	Context

Returns

React.ReactNode

Example

tsx

See

GroupedVirtuosoProps.groupContent for usage

---

GroupedScrollIntoViewLocation

Extends

• ScrollIntoViewLocationOptions

Properties

align?: "start" | "center" | "end"

How to align the item within the viewport

Inherited from

ScrollIntoViewLocationOptions.align

---

behavior?: "auto" | "smooth"

The scroll behavior - ‘smooth’ for animated scrolling, ‘auto’ for instant

Inherited from

ScrollIntoViewLocationOptions.behavior

---

calculateViewLocation?: CalculateViewLocation

Use this function to fine-tune the scrollIntoView behavior. The function receives the item’s top and bottom position in the viewport, and the viewport top/bottom. Return an location object to scroll, or null to prevent scrolling. Here’s the default implementation:

ts

Inherited from

ScrollIntoViewLocationOptions.calculateViewLocation

---

done()?

optional done: () => void

Will be called when the scroll is done, or immediately if no scroll is needed.

Returns

void

Inherited from

ScrollIntoViewLocationOptions.done

---

groupIndex

number

The index of the group to scroll into view

---

GroupIndexLocationWithAlign

Extends

• LocationOptions

Properties

align?: "start" | "center" | "end"

How to position the item in the viewport.

Inherited from

LocationOptions.align

---

behavior?: "auto" | "smooth"

Set ‘smooth’ to have an animated transition to the specified location.

Inherited from

LocationOptions.behavior

---

groupIndex

number

The group index of the item to scroll to.

---

offset?: number

The offset to scroll.

Inherited from

LocationOptions.offset

---

GroupItem

Extends

• Item<Data>

Type Parameters

Type Parameter
Data

Properties

data?: Data

The data associated with this item

Inherited from

Item.data

---

index

number

The index of the item in the list

Inherited from

Item.index

---

offset

number

The offset position of the item from the start of the list in pixels

Inherited from

Item.offset

---

originalIndex?: number

The original index before any transformations were applied

---

size

number

The measured size of the item in pixels

Inherited from

Item.size

---

type

"group"

Identifies this as a group header item

---

GroupItemContent

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

Callback type for rendering item content in a GroupedVirtuoso list. Similar to ItemContent but includes the group index.

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
groupIndex	number
data	Data
context	Context

Returns

React.ReactNode

Example

tsx

See

• GroupedVirtuosoProps.itemContent for usage
• ItemContent for non-grouped list variant

---

GroupProps

GroupProps = Pick<React.ComponentProps<"div">, "children" | "style"> & object

Passed to the Components.Group custom component

Type Declaration

data-index

number

The index of the group

data-item-index

number

The item index within the flattened list

data-known-size

number

The measured size of the group header in pixels