Render Performance

A single Blazor render is cheap. It evaluates your markup, builds a description of what should exist, compares it with the previous description, and sends only the differences. For a page with forty elements, that is work you will never notice.

Cost arrives in three ways. Rendering more components than the change affects, usually because the state that changed lives higher in the tree than it needs to. Doing expensive work in a method that runs on every render. And rendering a great many components at once, which is what a list of five thousand rows is.

Before any technique in this lesson: measure. The browser's performance profiler will show you which renders are slow, and the framework's own timings will show you how often a component renders. Optimising a component that was never the problem adds code, removes clarity, and changes nothing the reader can feel.

<ul>
    @foreach (var employee in visible)
    {
        <li @key="employee.Id">
            <EmployeeRow Employee="employee" OnSelect="Select" />
        </li>
    }
</ul>

<button type="button" @onclick="SortByDepartment">Sort by department</button>

@code {
    private List<Employee> visible = [];

    private void SortByDepartment() =>
        visible = visible.OrderBy(e => e.Department).ThenBy(e => e.Name).ToList();
}

• Without @key, Blazor matches the previous output to the new output by position. Row one is compared with row one, whatever is now in it.
• That is fine while the list only grows at the end. Sort it, filter it, or remove an item from the middle, and position one now holds a different person. Blazor keeps the element that was there and changes its content, so anything the browser owns about that element stays behind: focus, scroll position in a nested area, an open dropdown, half-typed text in an input.
• With @key, Blazor matches by the key instead. The element for employee 4471 moves with employee 4471, and the browser state moves with it.
• The key must be stable and unique among its siblings. The loop index is the one choice that defeats the purpose entirely, because it changes exactly when the order does.
• A key on a component preserves that component instance, so its private fields travel with the row rather than being reassigned to a different person's data. That is the version of this bug that is genuinely hard to diagnose.
• This is a correctness fix before it is a performance one. It also reduces work, because moving an element is cheaper than rewriting its contents, but the reason to reach for it is the wrong-row bug.

@code {
    [Parameter, EditorRequired]
    public Employee Employee { get; set; } = default!;

    [Parameter]
    public bool IsSelected { get; set; }

    private string display = "";
    private int renderedEmployeeId;
    private bool renderedSelection;

    protected override void OnParametersSet()
    {
        // Runs on every parameter change, which is every render of the parent.
        // Proportional work only. No sorting, no service calls, no queries.
        display = Employee.Name + " · " + Employee.Department;
    }

    protected override bool ShouldRender()
    {
        if (Employee.Id == renderedEmployeeId && IsSelected == renderedSelection)
        {
            return false;
        }

        renderedEmployeeId = Employee.Id;
        renderedSelection = IsSelected;
        return true;
    }
}

• OnParametersSet runs every time the parent supplies parameters, and the parent supplies them on every one of its renders — whether or not any value changed. A search box in the parent means this method runs on every keystroke, once per row.
• Concatenating two strings there is fine. Sorting a thousand items, calling a service, or querying a database is not: that cost is now paid per row per keystroke. Move it behind a check for what actually changed, or out of the component entirely.
• ShouldRender runs after parameters are set and decides whether to produce output. Returning false skips this component's render, and its children with it, because children are rendered by their parent.
• It is not consulted for the first render. A component always renders once.
• The comparison covers exactly the two parameters the markup uses. That is the discipline the whole technique rests on: if the markup reads a third parameter and the comparison does not include it, the row stops responding to that parameter.
• Note what this cannot see. If Employee is mutated in place by the parent, the id is unchanged and the row is skipped while its data is different. Reference and id comparisons both assume the parent replaces objects rather than editing them.

<div class="employee-scroll" style="height: 30rem; overflow-y: auto">
    <Virtualize Items="visible" Context="employee" ItemSize="48">
        <ItemContent>
            <EmployeeRow Employee="employee" OnSelect="Select" />
        </ItemContent>
    </Virtualize>
</div>

• Virtualize renders the rows in view plus a small buffer, and sizes a spacer above and below so the scrollbar behaves as though every row were present. A list of 5,000 becomes roughly thirty rendered components.
• ItemSize is the row height in pixels, and it is the figure Blazor uses before it can measure anything. A wrong value shows up as a scrollbar that jumps while you scroll. Rows whose heights vary are a poor fit for this component.
• The container needs a constrained height and its own scrolling. Without a viewport to measure against, there is nothing to virtualise.
• ItemsProvider replaces Items when the data is fetched a page at a time from a server. The Placeholder fragment then gives each not-yet-loaded row something to occupy its space, which only applies in that mode.
• There are costs, and they land on people rather than on the profiler. Rows that are not rendered cannot be found by the browser's own find-on-page, so Ctrl+F stops being a way to locate a colleague. A screen reader user is moving through a list whose contents change as it scrolls. And the row count is not visible anywhere unless you say it.
• So for a genuinely long list, a search box, a filter and server-side paging often serve people better than a fast scroll through five thousand rows. Virtualize is the right tool when scrolling is the interaction people actually want.