Building Components

A component file has two parts. Markup at the top: HTML with C# expressions mixed into it. A @code block at the bottom: an ordinary C# class body with fields, properties and methods.

When the component renders, Blazor evaluates the expressions and produces HTML. When an event fires, it calls your method and then renders the component again. Those two sentences cover most of what happens, and the example below is an application of them.

@page "/employees"
@rendermode InteractiveServer

<h1>Employees</h1>

<label for="search">Search by name</label>
<input id="search" value="@searchTerm" @oninput="SearchChanged" />

@if (Visible.Count == 0)
{
    <p role="status">No employees match that search.</p>
}
else
{
    <table>
        <caption>Showing @Visible.Count of @employees.Count employees</caption>
        <thead>
            <tr>
                <th scope="col">Name</th>
                <th scope="col">Department</th>
                <th scope="col">Action</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var employee in Visible)
            {
                <tr @key="employee.Id">
                    <td>@employee.Name</td>
                    <td>@employee.Department</td>
                    <td>
                        <button type="button" @onclick="() => Select(employee)">
                            View @employee.Name
                        </button>
                    </td>
                </tr>
            }
        </tbody>
    </table>
}

@if (selected is not null)
{
    <p role="status">
        Selected @selected.Name, started @selected.StartDate.ToString("d MMM yyyy")
    </p>
}

@code {
    private readonly List<Employee> employees =
    [
        new(1, "Priya Nair", "Finance", new DateOnly(2019, 4, 8)),
        new(2, "Tom Whelan", "Operations", new DateOnly(2021, 9, 20)),
        new(3, "Sara Kowalski", "Engineering", new DateOnly(2023, 1, 16)),
    ];

    private string searchTerm = string.Empty;
    private Employee? selected;

    private List<Employee> Visible => employees
        .Where(e => e.Name.Contains(searchTerm, StringComparison.OrdinalIgnoreCase))
        .ToList();

    private void SearchChanged(ChangeEventArgs args)
    {
        searchTerm = args.Value?.ToString() ?? string.Empty;
    }

    private void Select(Employee employee) => selected = employee;
}

• Employee is a record declared in your models: public record Employee(int Id, string Name, string Department, DateOnly StartDate). The list is built inline here so the example stands alone; a real screen loads it from a service.
• @if and @foreach are C# control flow in markup. The braces are C# braces, and the markup inside them is what gets produced for each pass. There is no separate template language to learn.
• value="@searchTerm" writes the current term into the input, and @oninput calls SearchChanged on every keystroke. ChangeEventArgs carries the new value as an object, so it needs converting. The next lesson replaces this pair with @bind, which is shorthand for precisely this.
• @onclick="() => Select(employee)" passes a lambda, which is how you get the loop variable into the handler. Note that it is a lambda and not a call — writing Select(employee) without the arrow would invoke the method during rendering.
• @key="employee.Id" tells Blazor which rendered row belongs to which employee. When the list is filtered or reordered, it moves the existing rows instead of rewriting each one in place.
• Visible is a property, so it is recalculated every time the component renders. Filtering three records in memory is nothing; if this property called an API, it would call it on every render. See the note at the end of this lesson.
• The button text includes the employee name so that each button has a distinct accessible name. A column of buttons all called View is ambiguous to anyone reading them out of context. If the design wants only the word View on screen, put the name in a visually hidden span inside the button.
• scope="col" on the header cells, and the table caption, are what make the table navigable with a screen reader. Both are content decisions, so they belong here rather than in CSS.

That automatic re-render happens after any event handler the framework invoked. It is the reason a Blazor component has no update-the-page code in it, and the reason state and display cannot get out of step within a component.

Two details are worth knowing early. An async handler renders more than once: Blazor renders when the handler first awaits, and again when it completes, so a loading state is easy to show. And state that changes outside an event handler — a timer firing, a message arriving from a background service — does not trigger anything, because Blazor never knew about it. In that case you call StateHasChanged yourself to ask for a render.

If you find yourself calling StateHasChanged inside a normal event handler, that is a sign something else is wrong. The framework already rendered for you.