From cb6320390f1532e84aa3c925e29742d8c96d96e7 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Fri, 10 Apr 2026 07:45:19 -0400 Subject: [PATCH 1/5] [11.0 P3] Virtualize handles variable-height items --- aspnetcore/blazor/components/quickgrid.md | 2 +- .../blazor/components/virtualization.md | 34 +++++++++++++++++++ 2 files changed, 35 insertions(+), 1 deletion(-) diff --git a/aspnetcore/blazor/components/quickgrid.md b/aspnetcore/blazor/components/quickgrid.md index a3b1b4fe1339..8cdc46ce05df 100644 --- a/aspnetcore/blazor/components/quickgrid.md +++ b/aspnetcore/blazor/components/quickgrid.md @@ -39,7 +39,7 @@ To implement a `QuickGrid` component: * : If true, the grid is rendered with virtualization. This is normally used in conjunction with scrolling and causes the grid to fetch and render only the data around the current scroll viewport. This can greatly improve the performance when scrolling through large data sets. If you use , you should supply a value for and must ensure that every row renders with a constant height. Generally, it's preferable not to use if the amount of data rendered is small or if you're using pagination. * : Only applicable when using . defines an expected height in pixels for each row, allowing the virtualization mechanism to fetch the correct number of items to match the display size and to ensure accurate scrolling. * : Optionally defines a value for `@key` on each rendered row. Typically, this is used to specify a unique identifier, such as a primary key value, for each data item. This allows the grid to preserve the association between row elements and data items based on their unique identifiers, even when the `TGridItem` instances are replaced by new copies (for example, after a new query against the underlying data store). If not set, the `@key` is the `TGridItem` instance. -* : Defines how many additional items to render before and after the visible region to reduce rendering frequency during scrolling. While higher values can improve scroll smoothness by rendering more items off-screen, a higher value can also result in an increase in initial load times. Finding a balance based on your data set size and user experience requirements is recommended. The default value is 3. Only available when using . +* : Defines how many additional items to render before and after the visible region to reduce rendering frequency during scrolling. While higher values can improve scroll smoothness by rendering more items off-screen, a higher value can also result in an increase in initial load times. Finding a balance based on your data set size and user experience requirements is recommended. The default value is 15 in .NET 11 or later, and the default value is 3 in .NET 10 or earlier. Only available when using . * : Optionally links this `TGridItem` instance with a model, causing the grid to fetch and render only the current page of data. This is normally used in conjunction with a component or some other UI logic that displays and updates the supplied instance. * In the QuickGrid child content (), specify s, which represent `TGridItem` columns whose cells display values: * : Defines the value to be displayed in this column's cells. diff --git a/aspnetcore/blazor/components/virtualization.md b/aspnetcore/blazor/components/virtualization.md index 041b13fa7633..977f9bab4473 100644 --- a/aspnetcore/blazor/components/virtualization.md +++ b/aspnetcore/blazor/components/virtualization.md @@ -221,6 +221,22 @@ protected override void OnInitialized() => ## Item size +:::moniker range=">= aspnetcore-11.0" + +The height of each item in pixels can be set initially with (default: 50). The following example changes the default height of each item from the default of 50 pixels to 25 pixels: + +```razor + + ... + +``` + +The component measures actual item heights as they enter the viewport and maintains a running average of measured heights. All items use this running average for positioning (or the default parameter before any measurements exist). + +:::moniker-end + +:::moniker range="< aspnetcore-11.0" + 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 @@ -231,8 +247,24 @@ The height of each item in pixels can be set with 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. +:::moniker-end + ## Overscan count +:::moniker range=">= aspnetcore-11.0" + + 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: 15). The following example changes the overscan count from the default of 15 items to 17 items: + +```razor + + ... + +``` + +:::moniker-end + +:::moniker range="< aspnetcore-11.0" + 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 @@ -241,6 +273,8 @@ The com ``` +:::moniker-end + ## 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 . From fd27cd2abe0d1fb1eacc7f97061a1907e473de13 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Fri, 10 Apr 2026 07:53:06 -0400 Subject: [PATCH 2/5] Updates --- aspnetcore/release-notes/aspnetcore-11/includes/blazor.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md b/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md index 9bef2832cf6f..d6c9fafb081e 100644 --- a/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md +++ b/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md @@ -117,3 +117,9 @@ For more information, see . + +### `Virtualize` adapts to variable-height items at runtime + +The component no longer assumes every item has the same height. The component now adapts to measured item sizes at runtime, which reduces incorrect spacing and scrolling when item heights vary. These updates include an update to the default value of , which was three in .NET 10 or earlier and now changes to 15 in .NET 11 or later. The change in default value increases the precision of average item height calculations. + +For more information, see the *Item size* and *Overscan count* sections of . From 18e5ae68252eddfe6065cfd1c0044c886d663a6d Mon Sep 17 00:00:00 2001 From: Luke Latham <1622880+guardrex@users.noreply.github.com> Date: Fri, 10 Apr 2026 08:10:55 -0400 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- aspnetcore/blazor/components/virtualization.md | 2 +- aspnetcore/release-notes/aspnetcore-11/includes/blazor.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/blazor/components/virtualization.md b/aspnetcore/blazor/components/virtualization.md index 977f9bab4473..b4cd3dd1f4be 100644 --- a/aspnetcore/blazor/components/virtualization.md +++ b/aspnetcore/blazor/components/virtualization.md @@ -223,7 +223,7 @@ protected override void OnInitialized() => :::moniker range=">= aspnetcore-11.0" -The height of each item in pixels can be set initially with (default: 50). The following example changes the default height of each item from the default of 50 pixels to 25 pixels: +The height of each item in pixels can be set initially with (default: 50). The following example sets the initial height of each item from 50 pixels to 25 pixels: ```razor diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md b/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md index d6c9fafb081e..643b7ff3a47c 100644 --- a/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md +++ b/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md @@ -120,6 +120,6 @@ Blazor WebAssembly apps can perform heavy computing on the client, but doing so ### `Virtualize` adapts to variable-height items at runtime -The component no longer assumes every item has the same height. The component now adapts to measured item sizes at runtime, which reduces incorrect spacing and scrolling when item heights vary. These updates include an update to the default value of , which was three in .NET 10 or earlier and now changes to 15 in .NET 11 or later. The change in default value increases the precision of average item height calculations. +The component no longer assumes every item has the same height. The component now adapts to measured item sizes at runtime, which reduces incorrect spacing and scrolling when item heights vary. These changes include a new default value for , which was three in .NET 10 or earlier and now changes to 15 in .NET 11 or later. The change in default value increases the precision of average item height calculations. For more information, see the *Item size* and *Overscan count* sections of . From 442758897781d087814a8f3ddfd605bbe2111788 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Fri, 10 Apr 2026 08:12:20 -0400 Subject: [PATCH 4/5] Updates --- aspnetcore/blazor/components/quickgrid.md | 2 +- aspnetcore/blazor/components/virtualization.md | 1 - aspnetcore/release-notes/aspnetcore-11/includes/blazor.md | 2 +- 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/aspnetcore/blazor/components/quickgrid.md b/aspnetcore/blazor/components/quickgrid.md index 8cdc46ce05df..3141b7b9e188 100644 --- a/aspnetcore/blazor/components/quickgrid.md +++ b/aspnetcore/blazor/components/quickgrid.md @@ -39,7 +39,7 @@ To implement a `QuickGrid` component: * : If true, the grid is rendered with virtualization. This is normally used in conjunction with scrolling and causes the grid to fetch and render only the data around the current scroll viewport. This can greatly improve the performance when scrolling through large data sets. If you use , you should supply a value for and must ensure that every row renders with a constant height. Generally, it's preferable not to use if the amount of data rendered is small or if you're using pagination. * : Only applicable when using . defines an expected height in pixels for each row, allowing the virtualization mechanism to fetch the correct number of items to match the display size and to ensure accurate scrolling. * : Optionally defines a value for `@key` on each rendered row. Typically, this is used to specify a unique identifier, such as a primary key value, for each data item. This allows the grid to preserve the association between row elements and data items based on their unique identifiers, even when the `TGridItem` instances are replaced by new copies (for example, after a new query against the underlying data store). If not set, the `@key` is the `TGridItem` instance. -* : Defines how many additional items to render before and after the visible region to reduce rendering frequency during scrolling. While higher values can improve scroll smoothness by rendering more items off-screen, a higher value can also result in an increase in initial load times. Finding a balance based on your data set size and user experience requirements is recommended. The default value is 15 in .NET 11 or later, and the default value is 3 in .NET 10 or earlier. Only available when using . +* : Defines how many additional items to render before and after the visible region to reduce rendering frequency during scrolling. While higher values can improve scroll smoothness by rendering more items off-screen, a higher value can also result in an increase in initial load times. Finding a balance based on your data set size and user experience requirements is recommended. The default value is `15` in .NET 11 or later, and the default value is `3` in .NET 10 or earlier. Only available when using . * : Optionally links this `TGridItem` instance with a model, causing the grid to fetch and render only the current page of data. This is normally used in conjunction with a component or some other UI logic that displays and updates the supplied instance. * In the QuickGrid child content (), specify s, which represent `TGridItem` columns whose cells display values: * : Defines the value to be displayed in this column's cells. diff --git a/aspnetcore/blazor/components/virtualization.md b/aspnetcore/blazor/components/virtualization.md index 977f9bab4473..cab365d1c0d6 100644 --- a/aspnetcore/blazor/components/virtualization.md +++ b/aspnetcore/blazor/components/virtualization.md @@ -22,7 +22,6 @@ Use the * Rendering a set of data items in a loop. * Most of the items aren't visible due to scrolling. -* The rendered items are the same size. When the user scrolls to an arbitrary point in the component's list of items, the component calculates the visible items to show. Unseen items aren't rendered. diff --git a/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md b/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md index d6c9fafb081e..1bc4f75667c5 100644 --- a/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md +++ b/aspnetcore/release-notes/aspnetcore-11/includes/blazor.md @@ -120,6 +120,6 @@ Blazor WebAssembly apps can perform heavy computing on the client, but doing so ### `Virtualize` adapts to variable-height items at runtime -The component no longer assumes every item has the same height. The component now adapts to measured item sizes at runtime, which reduces incorrect spacing and scrolling when item heights vary. These updates include an update to the default value of , which was three in .NET 10 or earlier and now changes to 15 in .NET 11 or later. The change in default value increases the precision of average item height calculations. +The component no longer assumes every item has the same height. The component now adapts to measured item sizes at runtime, which reduces incorrect spacing and scrolling when item heights vary. These updates include an update to the default value of , which was `3` in .NET 10 or earlier and now changes to `15` in .NET 11 or later. The change in default value increases the precision of average item height calculations. For more information, see the *Item size* and *Overscan count* sections of . From 887280d9694d28c8f01c6d1f6f24a5db2863a7f2 Mon Sep 17 00:00:00 2001 From: guardrex <1622880+guardrex@users.noreply.github.com> Date: Fri, 10 Apr 2026 08:16:36 -0400 Subject: [PATCH 5/5] Updates --- aspnetcore/blazor/components/quickgrid.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/blazor/components/quickgrid.md b/aspnetcore/blazor/components/quickgrid.md index 3141b7b9e188..c3ede4bff602 100644 --- a/aspnetcore/blazor/components/quickgrid.md +++ b/aspnetcore/blazor/components/quickgrid.md @@ -39,7 +39,7 @@ To implement a `QuickGrid` component: * : If true, the grid is rendered with virtualization. This is normally used in conjunction with scrolling and causes the grid to fetch and render only the data around the current scroll viewport. This can greatly improve the performance when scrolling through large data sets. If you use , you should supply a value for and must ensure that every row renders with a constant height. Generally, it's preferable not to use if the amount of data rendered is small or if you're using pagination. * : Only applicable when using . defines an expected height in pixels for each row, allowing the virtualization mechanism to fetch the correct number of items to match the display size and to ensure accurate scrolling. * : Optionally defines a value for `@key` on each rendered row. Typically, this is used to specify a unique identifier, such as a primary key value, for each data item. This allows the grid to preserve the association between row elements and data items based on their unique identifiers, even when the `TGridItem` instances are replaced by new copies (for example, after a new query against the underlying data store). If not set, the `@key` is the `TGridItem` instance. -* : Defines how many additional items to render before and after the visible region to reduce rendering frequency during scrolling. While higher values can improve scroll smoothness by rendering more items off-screen, a higher value can also result in an increase in initial load times. Finding a balance based on your data set size and user experience requirements is recommended. The default value is `15` in .NET 11 or later, and the default value is `3` in .NET 10 or earlier. Only available when using . +* : Defines how many additional items to render before and after the visible region to reduce rendering frequency during scrolling. While higher values can improve scroll smoothness by rendering more items off-screen, a higher value can also result in an increase in initial load times. Finding a balance based on your data set size and user experience requirements is recommended. The default value is `3`. Only available when using . * : Optionally links this `TGridItem` instance with a model, causing the grid to fetch and render only the current page of data. This is normally used in conjunction with a component or some other UI logic that displays and updates the supplied instance. * In the QuickGrid child content (), specify s, which represent `TGridItem` columns whose cells display values: * : Defines the value to be displayed in this column's cells.