Common

CalculateViewLocation

CalculateViewLocation = (params) => IndexLocationWithAlign | null | number

Parameters

Parameter	Type
params	CalculateViewLocationParams

Returns

IndexLocationWithAlign | null | number

---

CalculateViewLocationParams

Properties

itemBottom

number

The bottom edge position of the item in pixels

---

itemTop

number

The top edge position of the item in pixels

---

locationParams

locationParams: object & { groupIndex: number; } | { index: number; }

The scroll location parameters including alignment and behavior options

Type Declaration

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

behavior?: "auto" | "smooth"

---

viewportBottom

number

The bottom edge position of the viewport in pixels

---

viewportTop

number

The top edge position of the viewport in pixels

---

ComputeItemKey

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

Callback type for computing unique keys for list 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

VirtuosoProps.computeItemKey for usage in Virtuoso

---

ContextProp

Type Parameters

Type Parameter
Context

Properties

context

Context

The context value passed from the parent component

---

FlatIndexLocationWithAlign

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

---

index

number | "LAST"

The index of the item to scroll to.

---

offset?: number

The offset to scroll.

Inherited from

LocationOptions.offset

---

FlatScrollIntoViewLocation

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

---

index

number

The index of the item to scroll into view

---

FollowOutput

FollowOutput = FollowOutputCallback | FollowOutputScalarType

---

FollowOutputCallback

FollowOutputCallback = (isAtBottom) => FollowOutputScalarType

Parameters

Parameter	Type
isAtBottom	boolean

Returns

FollowOutputScalarType

---

FollowOutputScalarType

FollowOutputScalarType = "auto" | "smooth" | boolean

---

IndexLocationWithAlign

IndexLocationWithAlign = FlatIndexLocationWithAlign | GroupIndexLocationWithAlign

---

Item

Base interface for list items with position and size information.

Extended by

• GroupItem
• RecordItem

Type Parameters

Type Parameter
Data

Properties

data?: Data

The data associated with this item

---

index

number

The index of the item in the list

---

offset

number

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

---

size

number

The measured size of the item in pixels

---

ListItem

ListItem<Data> = GroupItem<Data> | RecordItem<Data>

Union type representing either a regular item or a group header item in the list.

Type Parameters

Type Parameter	Description
Data	The type of the data item

See

• RecordItem for regular items
• GroupItem for group header items

---

ListRange

Represents a range of items in the list by their indices. Used to track which items are currently visible in the viewport.

See

VirtuosoProps.rangeChanged for visibility change events

Properties

endIndex

number

The index of the last visible item

---

startIndex

number

The index of the first visible item

---

LocationOptions

Extended by

• FlatIndexLocationWithAlign
• GroupIndexLocationWithAlign

Properties

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

How to position the item in the viewport.

---

behavior?: "auto" | "smooth"

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

---

offset?: number

The offset to scroll.

---

LogLevel

Log levels for controlling virtuoso diagnostic output. Use with the logLevel prop to enable debugging information.

Example

tsx

Enumeration Members

DEBUG

DEBUG: 0

Detailed debugging information including item measurements

---

ERROR

ERROR: 3

Error messages for failures (default level)

---

INFO

INFO: 1

General informational messages

---

WARN

WARN: 2

Warning messages for potential issues

---

RecordItem

Represents a regular data item (not a group header) in the list.

Extends

• Item<Data>

Type Parameters

Type Parameter
Data

Properties

data?: Data

The data associated with this item

Overrides

Item.data

---

groupIndex?: number

The index of the group this item belongs to (if in a grouped list)

---

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

Undefined for regular items (used to distinguish from group items)

---

ScrollContainerState

Represents the current scroll state of the container.

Properties

scrollHeight

number

The total scrollable height of the content in pixels

---

scrollTop

number

The current scroll position from the top in pixels

---

viewportHeight

number

The visible height of the viewport in pixels

---

ScrollerProps

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

Passed to the Components.Scroller custom component

Type Declaration

data-testid?: string

data-virtuoso-scroller?: boolean

---

ScrollIntoViewLocation

ScrollIntoViewLocation = FlatScrollIntoViewLocation | GroupedScrollIntoViewLocation

---

ScrollIntoViewLocationOptions

Options for scrolling an item into view.

Extended by

• FlatScrollIntoViewLocation
• GroupedScrollIntoViewLocation

Properties

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

How to align the item within the viewport

---

behavior?: "auto" | "smooth"

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

---

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

---

done()?

optional done: () => void

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

Returns

void

---

ScrollSeekConfiguration

Configuration for scroll seek mode, which renders placeholders during fast scrolling. This improves performance when users scroll rapidly through large lists.

Example

tsx

See

• VirtuosoProps.scrollSeekConfiguration for usage
• Components.ScrollSeekPlaceholder for custom placeholder rendering

Properties

change()?

optional change: (velocity, range) => void

Called during scrolling in scroll seek mode - use to display a hint where the list is.

Parameters

Parameter	Type
velocity	number
range	ListRange

Returns

void

---

enter

ScrollSeekToggle

Callback to determine if the list should enter “scroll seek” mode.

---

exit

ScrollSeekToggle

Callback to determine if the list should exit “scroll seek” mode.

---

ScrollSeekToggle

ScrollSeekToggle = (velocity, range) => boolean

Parameters

Parameter	Type
velocity	number
range	ListRange

Returns

boolean

---

SizeFunction

SizeFunction = (el, field) => number

Custom function for calculating item sizes. Override to account for margins, padding, or other layout considerations.

Parameters

Parameter	Type
el	HTMLElement
field	"offsetHeight" | "offsetWidth"

Returns

number

See

VirtuosoProps.itemSize for usage

---

SizeRange

Represents a range of items that share the same size.

Properties

endIndex

number

The ending index of items in this size range (inclusive)

---

size

number

The size in pixels shared by items in this range

---

startIndex

number

The starting index of items in this size range

---

StateCallback

StateCallback = (state) => void

Callback type for receiving state snapshots for persistence.

Parameters

Parameter	Type
state	StateSnapshot

Returns

void

See

• VirtuosoProps.getState for usage
• StateSnapshot for the snapshot structure

---

StateSnapshot

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

See

• VirtuosoProps.restoreStateFrom for restoring state
• VirtuosoHandle.getState for capturing state

Properties

ranges

SizeRange[]

The measured size ranges of items

---

scrollTop

number

The scroll position in pixels

---

WindowViewportInfo

Information about the window viewport when using window scrolling mode.

Properties

offsetTop

number

The offset from the top of the document to the list container in pixels

---

visibleHeight

number

The visible height of the window viewport in pixels

---

visibleWidth

number

The visible width of the window viewport in pixels