Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 41 ยท Getting Started

How Blazor Renders and Updates the UI

Understand the Blazor render tree, how diffing produces minimal DOM updates, when components re-render, how @key keeps list items stable, and how to avoid needless renders with ShouldRender.

Blazor feels like magic until you know the mechanism behind it. This lesson opens the box: what a render tree is, how Blazor decides what to change on the page, when a component renders again, and the few tools you have to control it (@key, ShouldRender). Understanding this saves you from the most common performance and "my list is glitching" problems.

Render trees

When a component renders, it does not produce an HTML string. It produces a render tree: a lightweight, in-memory description of elements, attributes, text and child components. The framework keeps the previous tree. After the next render it compares the two and builds a diff: a short list of edits like "set the text of node 7" or "remove node 12". Only that list reaches the browser (or, with Interactive Server, travels over the SignalR connection), which keeps updates small and fast.

flowchart TD
  A["Event or parameter change"] --> B["Component runs BuildRenderTree"]
  B --> C["New render tree"]
  C --> D["Compare with old tree"]
  D --> E["List of edits (diff)"]
  E --> F["Browser applies the edits"]

From trigger to changed DOM: only the diff is sent.

A runnable stand-in: diffing two trees

This stand-in compares two flat lists of nodes by position and prints the edits. The real algorithm is smarter (it understands nesting and sequence numbers), but the principle is the same.

C# Stand-in: compute a minimal diff

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Out of five nodes, only two edits are produced: one update and one addition. The heading and the unchanged items cost nothing.

When does a component render?

A component renders again when:

  1. It first appears. The initial render happens after parameters are set.
  2. An event handler in it completes. Handlers wired with @onclick, @oninput and friends trigger a render of the component that owns them.
  3. Its parameters may have changed. When a parent re-renders, each child gets its parameters set again and typically renders too.
  4. You call StateHasChanged(). This explicitly asks for a render (covered in Refs and State Changes).
  5. A cascading value it uses changes. (See chapter 6.)

The render is queued, not instant: calling StateHasChanged several times in one method still renders once when control returns to the framework. And rendering is asynchronous-friendly: while you await something, Blazor can render the intermediate state.

A parent re-render does not necessarily mean children update the page. Blazor re-renders a child only when its parameters might have changed. Simple types (numbers, strings, booleans) are compared cheaply. Complex objects are assumed changed, which is a reason to pass immutable data.

Lists and @key

Diffing lists has a trap. If you remove the first item of a list, a position-based diff sees every item shift: item 2's content moves into slot 1, and so on. Visible text is fine, but anything attached to the DOM element, such as an input's typed text, focus or a CSS animation, stays with the position, not the item.

The fix is @key, which tells Blazor "this element represents this specific object":

HTML
@foreach (var task in tasks)
{
    <li @key="task.Id">
        <input value="@task.Title" />
        <button @onclick="() => Remove(task)">Delete</button>
    </li>
}

With @key, Blazor matches elements by Id. Deleting the first task removes exactly one <li>, and the other rows keep their own typed text and focus. The key must be unique among siblings and stable (an Id, not the loop index). Good keys are database ids or Guids; bad keys are indexes, random numbers generated during render, or objects that change identity.

Here is the idea in a runnable stand-in: matching by key versus by position when the first row is removed.

C# Stand-in: position versus key

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Without keys, "Bread" ends up showing "2 litres", Milk's note. With keys, every row keeps the right one.

Controlling renders with ShouldRender

Occasionally a component renders far more often than needed, for example one that receives rapid updates. You can override ShouldRender:

C#
private bool dirty;

protected override bool ShouldRender() => dirty;

Return false to skip a render. Use this sparingly: a wrong value leaves the UI stale, and the first render is always performed regardless. Prefer measuring first. For large lists, virtualization (<Virtualize>) and smaller components usually help more than ShouldRender.

Common mistakes

  • Using the loop index as @key. It is the same as no key once items move.
  • Expecting the page to change immediately. The DOM updates after the render is processed, not mid-method.
  • Heavy work in BuildRenderTree or in expressions. Markup expressions run on every render; keep them cheap and put expensive work in lifecycle methods (Component Lifecycle).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Blazor send to the browser after a component re-renders?

    Blazor compares render trees and applies only the minimal edits.
  2. 2. Which of these triggers a render of a component?

    After a UI event handler completes, the owning component is re-rendered.
  3. 3. What is @key used for?

    @key lets the diff match elements by identity instead of position.
  4. 4. Which makes the worst @key?

    An index changes when items shift, which defeats the purpose of a key.

Summary

  • Components render to a render tree; Blazor diffs it against the previous tree and applies only the changes.
  • Renders happen on first display, after event handlers, on parameter changes and on StateHasChanged.
  • Use @key with a stable unique value for items in a list that can change.
  • ShouldRender can skip renders but should be a last resort.

Next: Debugging and Hot Reload