diff --git a/aspnetcore/blazor/components/virtualization.md b/aspnetcore/blazor/components/virtualization.md index 0e5b1cc8b1e0..8b5bfc41b030 100644 --- a/aspnetcore/blazor/components/virtualization.md +++ b/aspnetcore/blazor/components/virtualization.md @@ -274,6 +274,50 @@ The com :::moniker-end +:::moniker range=">= aspnetcore-10.0" + +## Scroll to a specific item + +The component provides two ways to control scroll position: `InitialItemIndex` for the first render and `ScrollToItemAsync` for programmatic scrolling after the component is rendered. + +### `InitialItemIndex` parameter + +Set `InitialItemIndex` to open the list at a specific item index on first interactive render. This is a one-shot parameter—changes after first render are ignored. Out-of-range values are clamped. + +```razor + + + +``` + +### `ScrollToItemAsync` method + +Call `ScrollToItemAsync` to programmatically scroll to an item after first render. The scroll is instant (no animation). The method returns a `Task` that completes when the target item is aligned to the top of the viewport. Cancellation is supported via `CancellationToken`. + +If multiple calls occur, the last call wins—earlier calls complete normally but only the final target is honored. If the user scrolls during a programmatic scroll, the user's scroll takes precedence. Calling before first interactive render throws an . + +```razor + + + + + + +@code { + private Virtualize? virtualizeComponent; + + private async Task ScrollToFlight() + { + if (virtualizeComponent is not null) + { + await virtualizeComponent.ScrollToItemAsync(200); + } + } +} +``` + +:::moniker-end + :::moniker range=">= aspnetcore-11.0" ## Control viewport scroll position behavior when items are dynamically added @@ -283,20 +327,20 @@ The com Assign a `VirtualizeAnchorMode` value to the `AnchorMode` parameter to control how the viewport behaves at list edges when items are dynamically added: * `None`: No edge pinning. The viewport stays at the current scroll position regardless of item changes. -* `Beginning`: Pins the viewport to the beginning of the list. When the user is at a scroll position near the top of the list and new items arrive at the beginning, the viewport stays at the top showing the newest items. For example, this pinning behavior is useful for a news feed user experience. +* `Start`: Pins the viewport to the start of the list. When the user is at a scroll position near the top of the list and new items arrive at the start, the viewport stays at the top showing the newest items. For example, this pinning behavior is useful for a news feed user experience. * `End`: Pins the viewport to the end of the list. When the user is at a scroll position near the bottom of the list and new items arrive at the end, the viewport auto-scrolls to show them. If the user has scrolled away, auto-scroll disengages until they return to the bottom. For example, this pinning behavior is useful for a chat or logging user experience. -The following example pins the viewport to the beginning of a virtualized flight list: +The following example pins the viewport to the start of a virtualized flight list: ```razor
- +
``` -Modes can be combined. For example, assigning `Beginning | End` pins both edges. Combining `None` with other modes is supported but doesn't change the combined value. +Modes can be combined. For example, assigning `Start | End` pins both edges. Combining `None` with other modes is supported but doesn't change the combined value. `Virtualize.ItemComparer` gets or sets a comparer used to detect whether items were prepended or appended when using class-typed items with an (for more information, see the [Item provider delegate](#item-provider-delegate) section). @@ -307,7 +351,7 @@ The comparer determines if the first loaded item changed between provider calls, I thought that it wouldn't need it. --> ```razor - ...