` element, so most of them aren't seen. Instead of rendering the entire list of flights at once, replace the [`foreach`](/dotnet/csharp/language-reference/keywords/foreach-in) loop in the preceding example with the component: * Specify `allFlights` as a fixed item source to . Only the currently visible flights are rendered by the component. If a non-generic collection supplies the items, for example a collection of , follow the guidance in the [Item provider delegate](#item-provider-delegate) section to supply the items. * Specify a context for each flight with the `Context` parameter. In the following example, `flight` is used as the context, which provides access to each flight's members. ```razor

``` If a context isn't specified with the `Context` parameter, use the value of `context` in the item content template to access each flight's members: ```razor

``` The component: * Calculates the number of items to render based on the height of the container and the size of the rendered items. * Recalculates and rerenders the items as the user scrolls. * Only fetches the slice of records from an external API that correspond to the currently visible region, including overscan, when `ItemsProvider` is used instead of `Items` (see the [Item provider delegate](#item-provider-delegate) section). The item content for the component can include: * Plain HTML and Razor code, as the preceding example shows. * One or more Razor components. * A mix of HTML/Razor and Razor components. ## Item provider delegate If you don't want to load all of the items into memory or the collection isn't a generic , you can specify an items provider delegate method to the component's parameter that asynchronously retrieves the requested items on demand. In the following example, the `LoadEmployees` method provides the items to the component: ```razor

@employee.FirstName @employee.LastName has the job title of @employee.JobTitle.

``` The items provider receives an , which specifies the required number of items starting at a specific start index. The items provider then retrieves the requested items from a database or other service and returns them as an along with a count of the total items. The items provider can choose to retrieve the items with each request or cache them so that they're readily available. A component can only accept **one item source** from its parameters, so don't attempt to simultaneously use an items provider and assign a collection to `Items`. If both are assigned, an is thrown when the component's parameters are set at runtime. The following example loads employees from an `EmployeeService` (not shown). The `totalEmployees` field would typically be assigned by calling a method on the same service (for example, `EmployeesService.GetEmployeesCountAsync`) elsewhere, such as during component initialization. ```csharp private async ValueTask> LoadEmployees( ItemsProviderRequest request) { var numEmployees = Math.Min(request.Count, totalEmployees - request.StartIndex); var employees = await EmployeesService.GetEmployeesAsync(request.StartIndex, numEmployees, request.CancellationToken); return new ItemsProviderResult(employees, totalEmployees); } ``` In the following example, a collection of is a non-generic collection, so an items provider delegate is used for virtualization: ```razor ... @code{ ... private ValueTask> GetRows(ItemsProviderRequest request) => new(new ItemsProviderResult( dataTable.Rows.OfType().Skip(request.StartIndex).Take(request.Count), dataTable.Rows.Count)); } ``` instructs the component to rerequest data from its . This is useful when external data changes. There's usually no need to call when using . :::moniker range=">= aspnetcore-6.0" updates a component's data without causing a rerender. If is invoked from a Blazor event handler or component lifecycle method, triggering a render isn't required because a render is automatically triggered at the end of the event handler or lifecycle method. If is triggered separately from a background task or event, such as in the following `ForecastUpdated` delegate, call to update the UI at the end of the background task or event: ```csharp ... ... private Virtualize? virtualizeComponent; protected override void OnInitialized() { WeatherForecastSource.ForecastUpdated += async () => { await InvokeAsync(async () => { await virtualizeComponent?.RefreshDataAsync(); StateHasChanged(); }); }); } ``` In the preceding example: * is called first to obtain new data for the component. * `StateHasChanged` is called to rerender the component. :::moniker-end ## Placeholder Because requesting items from a remote data source might take some time, you have the option to render a placeholder with item content: * Use a (`...`) to display content until the item data is available. * Use to set the item template for the list. ```razor

@employee.FirstName @employee.LastName has the job title of @employee.JobTitle.

Loading…

``` :::moniker range=">= aspnetcore-8.0" ## Empty content Use the parameter to supply content when the component has loaded and either is empty or is zero. `EmptyContent.razor`: :::moniker-end :::moniker range=">= aspnetcore-9.0" :::code language="razor" source="~/../blazor-samples/9.0/BlazorSample_BlazorWebApp/Components/Pages/EmptyContent.razor"::: :::moniker-end :::moniker range=">= aspnetcore-8.0 < aspnetcore-9.0" :::code language="razor" source="~/../blazor-samples/8.0/BlazorSample_BlazorWebApp/Components/Pages/EmptyContent.razor"::: :::moniker-end :::moniker range=">= aspnetcore-8.0" Change the `OnInitialized` method lambda to see the component display strings: ```csharp protected override void OnInitialized() => stringList ??= new() { "Here's a string!", "Here's another string!" }; ``` :::moniker-end ## Item size The height of each item in pixels can be set with (default: 50). The following example changes the height of each item from the default of 50 pixels to 25 pixels: ```razor ... ``` The component measures the rendering size (height) of individual items *after* the initial render occurs. Use to provide an exact item size in advance to assist with accurate initial render performance and to ensure the correct scroll position for page reloads. If the default causes some items to render outside of the currently visible view, a second rerender is triggered. To correctly maintain the browser's scroll position in a virtualized list, the initial render must be correct. If not, users might view the wrong items. ## Overscan count determines how many additional items are rendered before and after the visible region. This setting helps to reduce the frequency of rendering during scrolling. However, higher values result in more elements rendered in the page (default: 3). The following example changes the overscan count from the default of three items to four items: ```razor ... ``` ## State changes When making changes to items rendered by the component, call to enqueue re-evaluation and rerendering of the component. For more information, see . :::moniker range=">= aspnetcore-6.0" ## Keyboard scroll support To allow users to scroll virtualized content using their keyboard, ensure that the virtualized elements or scroll container itself is focusable. If you fail to take this step, keyboard scrolling doesn't work in Chromium-based browsers. For example, you can use a `tabindex` attribute on the scroll container: ```razor

...

``` To learn more about the meaning of `tabindex` value `-1`, `0`, or other values, see [`tabindex` (MDN documentation)](https://developer.mozilla.org/docs/Web/HTML/Global_attributes/tabindex). ## Advanced styles and scroll detection The component is only designed to support specific element layout mechanisms. To understand which element layouts work correctly, the following explains how `Virtualize` detects which elements should be visible for display in the correct place. If your source code looks like the following: ```razor

Flight @context.Id

``` At runtime, the component renders a DOM structure similar to the following: ```html

Flight 12

Flight 13

Flight 14

Flight 15

Flight 16

``` The actual number of rows rendered and the size of the spacers vary according to your styling and `Items` collection size. However, notice that there are spacer `div` elements injected before and after your content. These serve two purposes: * To provide an offset before and after your content, causing currently-visible items to appear at the correct location in the scroll range and the scroll range itself to represent the total size of all content. * To detect when the user is scrolling beyond the current visible range, meaning that different content must be rendered. > [!NOTE] > To learn how to control the spacer HTML element tag, see the [Control the spacer element tag name](#control-the-spacer-element-tag-name) section later in this article. The spacer elements internally use an [Intersection Observer](https://developer.mozilla.org/docs/Web/API/Intersection_Observer_API) to receive notification when they're becoming visible. `Virtualize` depends on receiving these events. `Virtualize` works under the following conditions: * **All rendered content items, including [placeholder content](#placeholder), are of identical height.** This makes it possible to calculate which content corresponds to a given scroll position without first fetching every data item and rendering the data into a DOM element. * **Both the spacers and the content rows are rendered in a single vertical stack with every item filling the entire horizontal width.** In typical use cases, `Virtualize` works with `div` elements. If you're using CSS to create a more advanced layout, bear in mind the following requirements: * Scroll container styling requires a `display` with any of the following values: * `block` (the default for a `div`). * `table-row-group` (the default for a `tbody`). * `flex` with `flex-direction` set to `column`. Ensure that immediate children of the component don't shrink under flex rules. For example, add `.mycontainer > div { flex-shrink: 0 }`. * Content row styling requires a `display` with either of the following values: * `block` (the default for a `div`). * `table-row` (the default for a `tr`). * Don't use CSS to interfere with the layout for the spacer elements. The spacer elements have a `display` value of `block`, except if the parent is a table row group, in which case they default to `table-row`. Don't try to influence spacer element width or height, including by causing them to have a border or `content` pseudo-elements. Any approach that stops the spacers and content elements from rendering as a single vertical stack, or causes the content items to vary in height, prevents correct functioning of the component. :::moniker-end ## Root-level virtualization :::moniker range=">= aspnetcore-7.0" The component supports using the document itself as the scroll root, as an alternative to having some other element with `overflow-y: scroll`. In the following example, the `` or `` elements are styled in a component with `overflow-y: scroll`: ```razor ``` :::moniker-end :::moniker range=">= aspnetcore-6.0 < aspnetcore-7.0" The component supports using the document itself as the scroll root, as an alternative to having some other element with `overflow-y: scroll`. When using the document as the scroll root, avoid styling the `` or `` elements with `overflow-y: scroll` because it causes the [intersection observer](#advanced-styles-and-scroll-detection) to treat the full scrollable height of the page as the visible region, instead of just the window viewport. You can reproduce this problem by creating a large virtualized list (for example, 100,000 items) and attempt to use the document as the scroll root with `html { overflow-y: scroll }` in the page CSS styles. Although it may work correctly at times, the browser attempts to render all 100,000 items at least once at the start of rendering, which may cause a browser tab lockup. To work around this problem prior to the release of .NET 7, either avoid styling ``/`` elements with `overflow-y: scroll` or adopt an alternative approach. In the following example, the height of the `` element is set to just over 100% of the viewport height: ```razor ``` :::moniker-end :::moniker range="< aspnetcore-6.0" The component supports using the document itself as the scroll root, as an alternative to having some other element with `overflow-y: scroll`. When using the document as the scroll root, avoid styling the `` or `` elements with `overflow-y: scroll` because it causes the full scrollable height of the page to be treated as the visible region, instead of just the window viewport. You can reproduce this problem by creating a large virtualized list (for example, 100,000 items) and attempt to use the document as the scroll root with `html { overflow-y: scroll }` in the page CSS styles. Although it may work correctly at times, the browser attempts to render all 100,000 items at least once at the start of rendering, which may cause a browser tab lockup. To work around this problem prior to the release of .NET 7, either avoid styling ``/`` elements with `overflow-y: scroll` or adopt an alternative approach. In the following example, the height of the `` element is set to just over 100% of the viewport height: ```razor ``` :::moniker-end :::moniker range=">= aspnetcore-7.0" ## Control the spacer element tag name If the component is placed inside an element that requires a specific child tag name, allows you to obtain or set the virtualization spacer tag name. The default value is `div`. For the following example, the component renders inside a table body element ([`tbody`](https://developer.mozilla.org/docs/Web/HTML/Element/tbody)), so the appropriate child element for a table row ([`tr`](https://developer.mozilla.org/docs/Web/HTML/Element/tr)) is set as the spacer. `VirtualizedTable.razor`: :::code language="razor" source="~/../blazor-samples/8.0/BlazorSample_BlazorWebApp/Components/Pages/VirtualizedTable.razor"::: In the preceding example, the document root is used as the scroll container, so the `html` and `body` elements are styled with `overflow-y: scroll`. For more information, see the following resources: * [Root-level virtualization](#root-level-virtualization) section * :::moniker-end