Scroll Location

AutoscrollToBottom

AutoscrollToBottom<Data, Context> = ItemLocationCallback<Data, Context> | NonNullable<ScrollToOptions["behavior"]> | boolean

Specifies whether append-like data changes or rendered-item size changes should scroll to the bottom.

Passing false or undefined preserves the current viewport. Passing true is equivalent to 'auto'. Passing a ScrollBehavior directly applies only when the list is already at the bottom.

Use the callback form when the policy needs access to scrollLocation, atBottom, scrollInProgress, context, or the operation data. In callback form, return false to preserve position, a ScrollBehavior to scroll the last item into view, or an ItemLocation for custom alignment.

Type Parameters

Type Parameter	Default type	Description
Data	unknown	The type of the data items in the list.
Context	unknown	The type of the context passed to the list.

---

ItemLocation

ItemLocation = number | ItemLocationWithAlign

A location in the list to scroll to. Passing a number scrolls instantly to the item at the specified index aligned to the top. See ItemLocationWithAlign for more advanced options.

---

ItemLocationCallback

ItemLocationCallback<Data, Context> = (params) => ScrollBehavior | boolean | ItemLocation

A callback function that determines whether a data or rendered-item size change should scroll.

Return false to preserve the current viewport. Return true or a ScrollBehavior to scroll to the bottom. Return an ItemLocation to scroll to a specific item.

The callback receives the scroll location from before the change is applied. In callback form, returning a ScrollBehavior or ItemLocation scrolls even when atBottom is false; return false when a scrolled-up user should stay where they are.

Type Parameters

Type Parameter	Default type	Description
Data	unknown	The type of the data items in the list.
Context	unknown	The type of the context passed to the list.

Parameters

Parameter	Type
params	ItemLocationCallbackParams<Data, Context>

Returns

ScrollBehavior | boolean | ItemLocation

---

ItemLocationCallbackParams

The parameters passed to the ItemLocationCallback function.

Type Parameters

Type Parameter	Default type	Description
Data	unknown	The type of the data items in the list.
Context	unknown	The type of the context passed to the list.

Properties

atBottom

boolean

Whether the list is at the bottom before the data change.

---

context

Context

The context passed to the list.

---

data

Data[]

The data supplied by the operation that triggered the policy. For append and insert operations, this is the added data. For declarative data updates, this is the next data array. For notifyItemsChanged, this is the current list data.

---

scrollInProgress

boolean

Indicates whether the list is currently scrolling. If you receive fast updates and use 'smooth' scrolling, there’s a chance that the list will be in the middle of a scroll when new data arrives.

---

scrollLocation

ListScrollLocation

The location of the list before the data or rendered-item size change. See ListScrollLocation for the details of the parameter received.

---

ItemLocationWithAlign

Specifies a location in the list to scroll to.

Properties

align?: "start" | "center" | "end" | "start-no-overflow"

How to align the item in the viewport.

---

behavior?: ScrollBehavior

Set 'smooth' to have an animated transition to the specified location.

---

done()?

optional done: () => void

A callback that’s invoked when the scroll is complete.

Returns

void

---

index

number | "LAST"

The index of the item to scroll to. Use 'LAST' to scroll to the last item.

---

offset?: number

Use the offset for additional adjustment of the position - can be a positive or negative number.

---

NotifyItemsChangedOptions

Options for notifying the list that rendered item content may have changed size without changing the data array.

Type Parameters

Type Parameter	Default type
Data	unknown
Context	unknown

Properties

scrollToBottom

AutoscrollToBottom<Data, Context>

Specifies whether the list should scroll to the bottom if rendered items grow.

Use the callback form to inspect the pre-change scrollLocation, atBottom, scrollInProgress, context, and current data. Return false to keep a scrolled-up user at the same location.

---

ScrollModifier

ScrollModifier = null | undefined | { location: ItemLocation; purgeItemSizes?: boolean; type: "item-location"; } | { autoScroll: AutoscrollToBottom; type: "auto-scroll-to-bottom"; } | { behavior: ScrollBehavior | { location: () => ItemLocation | null | undefined; }; type: "items-change"; } | ScrollModifierOptionValue

Describes the scroll modification to perform when the data of the list is updated. See the scroll modifier documentation section for examples of how to use this type.

---

ScrollModifierOption

const ScrollModifierOption: object

Predefined scroll modifier options for common data operations.

Type Declaration

prepend

"prepend"

removeFromEnd

"remove-from-end"

removeFromStart

"remove-from-start"

---

ScrollModifierOptionType

ScrollModifierOptionType = typeof ScrollModifierOption

The type of the ScrollModifierOption constant.

---

ScrollModifierOptionValue

ScrollModifierOptionValue = ScrollModifierOptionType[keyof ScrollModifierOptionType]

The possible values of the ScrollModifierOption constant.

---

scrollToBottomAlways

scrollToBottomAlways<Data, Context>(__namedParameters): ItemLocation

Always scrolls the last item into view.

The helper uses a smooth scroll while the list is already at the bottom or scrolling to the bottom, and an instant scroll otherwise. Use this for local actions, such as sending the current user’s message, where the new item should become visible even if the user was scrolled up.

Type Parameters

Type Parameter	Default type
Data	unknown
Context	unknown

Parameters

Parameter	Type
__namedParameters	ItemLocationCallbackParams<Data, Context>

Returns

ItemLocation

---

scrollToBottomIfAtBottom

scrollToBottomIfAtBottom<Data, Context>(__namedParameters): false | ScrollBehavior

Scrolls to the bottom only if the list was already at the bottom or is already scrolling to the bottom.

Use this for incoming messages or row growth where a scrolled-up user should stay at their current location.

Type Parameters

Type Parameter	Default type
Data	unknown
Context	unknown

Parameters

Parameter	Type
__namedParameters	ItemLocationCallbackParams<Data, Context>

Returns

false | ScrollBehavior

---

ShortSizeAlign

ShortSizeAlign = "top" | "bottom" | "bottom-smooth"

Specifies the alignment of the items when the content of the list is smaller than the viewport height.

• 'top' (default), the items will be aligned to the top
• 'bottom', the items will be aligned to the bottom.
• 'bottom-smooth', the items will be aligned to the bottom and the scroll will be animated.