Blazor Data Grid

Add a Data Grid to a Blazor App

Two steps, and neither involves your build. Start with the package:

dotnet add package Blazor-ApexGrid

Then add the namespaces to _Imports.razor. Note the underscores: the NuGet package is Blazor-ApexGrid but the C# namespace is Blazor_ApexGrid, because a hyphen is not legal in an identifier.

@using Blazor_ApexGrid.Components
@using Blazor_ApexGrid.Models

There is no third step. Nothing is registered in Program.cs, and nothing is copied into wwwroot. The grid engine and its styles are a static web asset served from _content/Blazor-ApexGrid/, which the framework wires up for you.

Why Does My Blazor Grid Render Blank?

There are two causes, and they look identical.

The render mode. From .NET 8, Blazor Web Apps render statically by default, and a component that needs JavaScript interop has to opt into interactivity. Set the render mode on the page or the component:

@rendermode InteractiveServer

InteractiveWebAssembly and InteractiveAuto work equally well. There is no error and nothing in the console, which is what makes this expensive to diagnose.

The height. The grid virtualizes rows, so it needs a bounded height to know what a viewport is. Height defaults to 400px and takes any CSS value, but if you pass a percentage whose parent has no height of its own, it resolves to zero and the grid renders as nothing.

Declare Columns as C# Objects

A column is a GridColumn<TItem>. Key binds it to a row property under that property's serialized name, which is camelCase: a Name property is "name" and a GrossValue property is "grossValue". That one convention also governs the tree PathKey and the {field} tokens in a detail template.

Type selects the built-in renderer and editor from thirteen values: Number, String, Boolean, Select, Rating, Date, Image, Currency, Avatar, Badge, Progress, Sparkline and Status. It is nullable and omitted when null, so leaving it off lets the grid infer the type from your data, and setting it is how you overrule that.

For anything the C# model does not cover, AdditionalConfig is a [JsonExtensionData] escape hatch that passes keys through to the engine untouched, including function-valued renderers supplied as JavaScript function strings. It is an escape hatch by design: the keys are not checked by the compiler.

Edit Cells with Undo and Redo

Editing is opt-in twice, which is deliberate: once on the grid through GridEditingConfiguration, and once per column through Editable = true. Turning it on at the grid alone does nothing, so there is no way to make every column editable by accident.

<ApexGrid TItem="Person" @ref="grid"
          Data="people" Columns="columns"
          Editing="editing"
          OnCellValueChanged="OnEdited"
          OnHistoryChanged="OnHistory" />

@code {
    private ApexGrid<Person>? grid;

    private readonly GridEditingConfiguration editing = new()
    {
        Enabled = true,
        Mode = EditMode.Cell,
        Trigger = EditTrigger.DoubleClick,
        History = new() { Enabled = true }
    };

    private void OnEdited(GridCellValueChangedEventArgs<Person> e)
        => Console.WriteLine($"{e.Key} on row {e.RowIndex} is now {e.Value}");

    private void OnHistory(GridHistoryChangedEventArgs e)
        => (canUndo, canRedo) = (e.CanUndo, e.CanRedo);
}

With History enabled, committed edits go on an undo stack that defaults to 100 entries. Drive it from your own toolbar with UndoAsync, RedoAsync, CanUndoAsync and CanRedoAsync, and keep the buttons in the right state from OnHistoryChanged.

Nested Rows Without a Nested Model

Tree data does not ask you to reshape your query. The collection stays flat and the grid derives the hierarchy from a path array on each row, so the only thing you supply is which field holds it.

<ApexGrid TItem="Employee"
          Data="employees"
          Columns="columns"
          Tree="tree" />

@code {
    private readonly GridTreeConfiguration tree = new()
    {
        Enabled = true,
        PathKey = "path",
        DefaultExpanded = true
    };

    public class Employee
    {
        public string Name { get; set; } = "";
        public string Title { get; set; } = "";
        // ["Adrian"], ["Adrian", "Bryan"], ["Adrian", "Bryan", "Cara"]
        public string[] Path { get; set; } = [];
    }
}

DefaultExpanded takes false, true or a depth number, and GroupColumnKey chooses which column carries the chevron and the indentation. There are no callbacks to implement.

Row expansion is the separate case where each row opens a detail panel rather than child rows. Set DetailTemplateHtml on a GridExpansionConfiguration to an HTML string whose {field} tokens are replaced with that row's values, HTML-escaped on the way in.

Save and Restore a View

A user who sorts three columns, hides two more and pins the first has built something worth keeping. GetStateAsync captures it as JSON you can put anywhere: a database column, local storage, a saved-views table.

// Capture the whole view: sort, filters, paging, column order, pins, widths.
var snapshot = await grid.GetStateAsync();
await SaveForUserAsync(snapshot);

// Restore it later. Only the slices present in the snapshot are applied.
await grid.SetStateAsync(snapshot);

// A machine-readable description of the grid: columns, available
// operations and current state.
var schema = await grid.GetSchemaAsync();

SetStateAsync applies only the slices a snapshot actually contains, so a partial snapshot is valid and you can persist just the parts you care about.

The rest of the grid is drivable the same way, through the component reference rather than by rebuilding parameters:

await grid.SortAsync(new GridSortExpression
{
    Key = "name",
    Direction = SortingDirection.Ascending
});

await grid.FilterAsync(new GridFilterExpression
{
    Key = "role",
    Condition = "contains",
    SearchTerm = "Engineer"
});

await grid.SetQuickFilterAsync(searchBox);
await grid.NextPageAsync();
await grid.PinColumnAsync("name", PinPosition.Start);

What This Package Does Not Cover

Blazor-ApexGrid 1.0.0 bundles the community ApexGrid core. That covers everything on this page, and it leaves the enterprise analytics tier outside the C# surface: row grouping, column aggregations, pivoting, the server-side row model, the Excel-style set filter, the advanced filter builder, the columns tool panel, range selection with a status bar, integrated charts, cell formulas, the AI toolkit, the context menu and XLSX export.

If your application is a reporting surface built on grouping and pivoting, that is the honest answer before you start rather than after. Those features are real and supported in the JavaScript grid today, and reaching them from .NET means driving apex-grid-enterprise through your own interop rather than this package.

Two smaller boundaries worth knowing. Cell and header templates are JavaScript function strings passed through AdditionalConfig, not Razor render fragments, so a template cannot contain Blazor components.

And the grid decides whether to re-push your data by comparing the collection's identity and its count. Adding or removing rows changes the count, so the grid redraws on the next render, and reassigning the collection changes its identity, so that works too. Editing a property on a row already in the list changes neither, and that edit will not appear. Call RefreshAsync when you have changed what is inside a row rather than which rows there are.