NexGrid.AspNetCore 0.4.0

TableX.AspNetCore

A professional, server-driven data grid for ASP.NET Core — the Razor & Blazor half of NexGrid.

The grid never holds your dataset. Every user action (search, sort, page, page size, column filter) becomes a query string; your endpoint answers with exactly one page of rows and a total count. That is what makes the grid behave the same at 50 rows and at 5,000,000.

This package gives you three things and nothing you have to glue together:

• ASP.NET Core 8.0+ · zero package dependencies · MIT
• 🗂️ Column Header Grouping — Multi-level stacked headers with automatic colSpan and rowSpan
• 💾 Grid State Persistence (storage-key) — Saves custom column widths, order, hidden columns to localStorage
• ↔️ Column Resizing & Auto-Fit — Drag resize handles and double-click auto-fit measuring
• 🏷️ Active Filter Pills Bar — Interactive chips for active search & column filters with 1-click removal
• 📊 Excel (.xls, styled badges) and CSV export, including the whole filtered dataset across pages
• 🔍 Global search (350 ms debounce), column visibility, density, row selection, automatic S.No., numbered pagination with page-jump
• 📱 Responsive: a table at ≥ 768 px, a card per record below
• 🎨 Light / dark / auto theming, fully localizable, accessible by construction

<p align="center"> <img src="https://raw.githubusercontent.com/ChhaganSinha/NexGrid/master/docs/assets/tablex-preview.png" alt="TableX ASP.NET Core Data Grid Preview" width="100%" /> </p>

Install

dotnet add package NexGrid.AspNetCore

Reference the bundle once, in _Layout.cshtml. Both files ship inside the package as static web assets — there is nothing to copy, download, or build:

<link rel="stylesheet" href="~/_content/NexGrid.AspNetCore/tablex.css" />
<script src="~/_content/NexGrid.AspNetCore/tablex.global.js"></script>

Or without hard-coding the paths:

<link rel="stylesheet" href="@TableXAssets.StylesheetPath" />
<script src="@TableXAssets.ScriptPath"></script>

Static web assets are served by app.UseStaticFiles(), which the default templates already call. In Development they are served straight out of the package; dotnet publish copies them into your app's wwwroot. (Running a Release build without publishing is the one case where neither applies and the files 404 — publish, or set ASPNETCORE_ENVIRONMENT=Development.)

Then register the Tag Helpers once, in Views/_ViewImports.cshtml (or Pages/_ViewImports.cshtml):

@using TableX.AspNetCore
@addTagHelper *, TableX.AspNetCore

Quick start

The endpoint

[HttpGet("/api/students")]
public Task<PagedResponse<Student>> Get(TableXQuery query, CancellationToken ct) =>
    db.Students.AsNoTracking().ToPagedResponseAsync(query, options => options
        .Sortable(s => s.Name, s => s.CreatedAt)
        .Searchable(s => s.Name, s => s.Email)
        .Filterable("status", s => s.Status)
        .DefaultSort(s => s.CreatedAt, SortDirection.Descending), ct);

The view (MVC / Razor Pages)

<nex-grid caption="Students" endpoint="/api/students" enable-selection="true">
    <nex-grid-column field="name" header="Name" min-width="180" />
    <nex-grid-column field="email" header="Email" />
    <nex-grid-column field="status" header="Status" align="Center" />
    <nex-grid-column field="score" header="Score" align="Right" width="90" />
    <nex-grid-column field="createdAt" header="Enrolled" />
</nex-grid>

The view (Blazor Server, WebAssembly, or Auto)

Add @using TableX.AspNetCore.Components to _Imports.razor:

@page "/students"
@using TableX.AspNetCore.Components

<TableX TItem="Student" Caption="Students Directory" Endpoint="/api/students" EnableSelection="true">
    <TableXColumn Field="name" Header="Name" MinWidth="180" />
    <TableXColumn Field="email" Header="Email" />
    <TableXColumn Field="status" Header="Status" Align="TableXColumnAlign.Center" />
    <TableXColumn Field="score" Header="Score" Align="TableXColumnAlign.Right" Width="90" />
    <TableXColumn Field="createdAt" Header="Enrolled" />
</TableX>

That is the whole integration. The grid fetches its own data, manages its loading and error states, and re-fetches on every query change.

Wiring the query binder

TableXQuery binds itself in all three hosting styles. Nothing needs to be registered in Program.cs.

MVC and API controllers

The type carries [ModelBinder(typeof(TableXQueryModelBinder))], so an undecorated parameter is enough:

[ApiController]
[Route("api/students")]
public sealed class StudentsController(AppDbContext db) : ControllerBase
{
    [HttpGet]
    public Task<PagedResponse<Student>> Get(TableXQuery query, CancellationToken ct) => /* ... */;
}

[FromQuery] TableXQuery query works too and binds identically — the attribute only names the binding source, which this binder reads directly off HttpContext.Request.Query.

Minimal APIs

TableXQuery implements the BindAsync(HttpContext) hook that minimal APIs look for:

app.MapGet("/api/students", (TableXQuery query, AppDbContext db, CancellationToken ct) =>
    db.Students.AsNoTracking().ToPagedResponseAsync(query, o => o
        .Sortable(s => s.Name)
        .Searchable(s => s.Name, s => s.Email), ct));

Razor Pages, middleware, background jobs

Call the parser yourself:

public async Task OnGetAsync()
{
    var query = TableXQuery.Parse(Request.Query);
    Result = await db.Students.AsNoTracking().ToPagedResponseAsync(query, Configure);
}

TableXQuery.Parse(string) takes a raw query string (with or without the leading ?), which is convenient in tests.

Binding never fails

Parsing mirrors @nexgrid/core's parseQuery exactly, including how it degrades. A hand-edited URL produces a usable grid, not a 400:

Full example — controller + EF Core

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TableX.AspNetCore;

public enum StudentStatus { Active, Suspended, Alumni }

public sealed class Student
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
    public string Email { get; set; } = "";
    public StudentStatus Status { get; set; }
    public int Score { get; set; }
    public DateTime CreatedAt { get; set; }
    public string? InternalNotes { get; set; }   // never exposed: not allowlisted
}

[ApiController]
[Route("api/students")]
public sealed class StudentsController(AppDbContext db) : ControllerBase
{
    [HttpGet]
    public Task<PagedResponse<StudentRow>> Get(TableXQuery query, CancellationToken ct) =>
        db.Students
            .AsNoTracking()
            .Where(s => s.TenantId == User.TenantId())   // authorization first, always
            .Select(s => new StudentRow(s.Id, s.Name, s.Email, s.Status, s.Score, s.CreatedAt))
            .ToPagedResponseAsync(query, options => options
                .Sortable(s => s.Name, s => s.Score, s => s.CreatedAt)
                .Searchable(s => s.Name, s => s.Email)
                .Filterable("status", s => s.Status)
                .DefaultSort(s => s.CreatedAt, SortDirection.Descending), ct);
}

public sealed record StudentRow(
    int Id, string Name, string Email, StudentStatus Status, int Score, DateTime CreatedAt);

Two round trips reach the database, and neither materialises a row the user is not looking at:

SELECT COUNT(*) FROM [Students] WHERE [TenantId] = @tenant AND ([Name] LIKE @q OR [Email] LIKE @q);

SELECT [Id], [Name], [Email], [Status], [Score], [CreatedAt] FROM [Students]
WHERE [TenantId] = @tenant AND ([Name] LIKE @q OR [Email] LIKE @q)
ORDER BY [CreatedAt] DESC
OFFSET @skip ROWS FETCH NEXT @take ROWS ONLY;

Notice @q and @take are parameters. Values from the query string are lifted into the expression tree the way a C# closure is, not baked in as constants, so the database can reuse one query plan for every search term.

Project before you page. .Select(...) into a row type keeps columns the UI never shows — InternalNotes, PasswordHash — out of the SQL entirely. The allowlist already prevents them being sorted or filtered on; projecting keeps them from being read.

Async without an EF Core dependency

ToPagedResponseAsync runs genuinely asynchronously on EF Core, but this package takes no Microsoft.EntityFrameworkCore package reference — it must not pin an EF version onto your app, and it must stay usable over other providers. The async path is discovered at run time instead: rows are materialised through IAsyncEnumerable<T> (a BCL interface EF Core's queryables implement), and the count goes through EF Core's IAsyncQueryProvider located by type name. Anything without an async surface — LINQ to Objects, an in-memory test double — falls back to the synchronous path, which is the correct answer there anyway.

Full example — minimal API

using Microsoft.EntityFrameworkCore;
using TableX.AspNetCore;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDbContext<AppDbContext>(o => o.UseSqlServer(/* ... */));
builder.Services.AddRazorPages();

var app = builder.Build();
app.UseStaticFiles();       // serves _content/TableX.AspNetCore/*
app.MapRazorPages();

app.MapGet("/api/students", (TableXQuery query, AppDbContext db, CancellationToken ct) =>
    db.Students
        .AsNoTracking()
        .ToPagedResponseAsync(query, options => options
            .Sortable(s => s.Name, s => s.Score, s => s.CreatedAt)
            .Searchable(s => s.Name, s => s.Email)
            .Filterable("status", s => s.Status)
            .DefaultSort(s => s.CreatedAt, SortDirection.Descending), ct));

app.Run();

PagedResponse<T> serializes to exactly the shape every TableX adapter reads, regardless of your app's JsonSerializerOptions:

{
  "items": [ /* exactly ONE page of rows */ ],
  "page": 2,
  "pageSize": 25,
  "total": 1284,      // full FILTERED count — this drives the pager
  "totalPages": 52
}

The allowlist, and why it is not optional

A grid sends the column ids it was configured with. The query string is not a grid — it is whatever anyone types into the address bar:

?sort=PasswordHash:asc
?filter[IsDeleted]=false
?sort=Owner.Organisation.BillingEmail:desc

A grid library that resolved those names by reflection would happily order by a password hash and let an attacker read it one binary-search page at a time.

TableX never turns a client string into a member access. Sortable, Searchable and Filterable build dictionaries from expressions the server wrote, and applying a query is a lookup:

if (!options.SortableMembers.TryGetValue(spec.Field, out var selector))
{
    continue;   // not allowlisted: dropped, never reflected
}

Which means:

• An unregistered key does nothing. No error, no leak, no 500 — the grid renders in its default order. There is no code path from a query-string value to a property, so there is nothing to escape and nothing to sanitise.
• Keys are matched case-insensitively against the member name, so s => s.CreatedAt answers the browser's ?sort=createdAt:desc. Use the Sortable(key, selector) / Filterable(key, selector) overloads when the column id differs from the member name, or to order by a computed expression.
• Filter values are converted, never interpreted. ?filter[score]=banana drops the filter rather than failing the request. Strings, enums, bool, numbers, Guid, DateTime, DateTimeOffset, DateOnly and TimeOnly are supported.
• Nothing is allowed by default. A call with no configure delegate ignores every sort, search and filter and just pages.

The allowlist is not authorization. Filter by tenant, owner, or role before ToPagedResponse — the grid pages whatever query you hand it.

Always set a DefaultSort

Skip/Take over an unordered SQL query has no defined row order. Without a default sort a user can page forward and see the same record twice, and never see another. One line fixes it:

.DefaultSort(s => s.CreatedAt, SortDirection.Descending)

Tag Helpers

<nex-grid>

Renders three things: a <div> for the bundle to mount into, a <script type="application/json"> block holding the configuration, and a short init script that calls TableX.createTableX.

Configuration never goes inside executable JavaScript. It travels in an inert JSON block written with System.Text.Json's default encoder, which escapes <, > and & — so no caption, header, or endpoint can close the <script> element early, whatever it contains.

The grid handle is left on the container as element.tablex, so other scripts can call refresh(), getQuery(), getSelection() or update() on it:

document.getElementById("students-grid").tablex.refresh();

<nex-grid-column>

Custom cell renderers

A cell renderer is a function, and functions do not survive JSON. Set init="false" to get the container and the configuration block without the init script, then start the grid yourself:

<nex-grid id="students-grid" caption="Students" endpoint="/api/students" init="false">
    <nex-grid-column field="name" header="Name" />
    <nex-grid-column field="status" header="Status" align="Center" />
</nex-grid>

<script>
    const host = document.getElementById("students-grid");
    const config = JSON.parse(document.getElementById("students-grid-config").textContent);

    config.columns.find(c => c.accessorKey === "status").cell = ({ getValue }) => {
        const badge = document.createElement("span");
        badge.className = "badge badge-" + String(getValue()).toLowerCase();
        badge.textContent = getValue();     // textContent, never innerHTML
        return badge;
    };

    host.tablex = TableX.createTableX(host, config);
</script>

Everything @nexgrid/vanilla accepts is available on that object: onNotify, onRowClick, onSelectionChange, locale, badgeRules, fetchOptions, and the rest. See the @nexgrid/vanilla README.

The wire format

Client to server:

GET /api/students?page=2&pageSize=25&sort=name:asc&q=smith&filter[status]=Active

Server to client: a PagedResponse<T>. Implement those two and any TableX adapter — React, Angular, vanilla — works against your endpoint with no glue.

API reference

Models

Query

Tag Helpers and assets

Building from source

The package embeds @nexgrid/vanilla's browser bundle, so build the JavaScript first:

npm install
npm run build:core && npm run build:vanilla
dotnet build dotnet/TableX.sln -c Release

The .csproj copies packages/vanilla/dist/tablex.global.js and tablex.css into wwwroot/ before every build, guarded by Exists(...). A checkout where the JavaScript has not been built still compiles — it just warns and produces a package with no browser payload.

Author & Maintainer

Chhagan Sinha

• GitHub: @ChhaganSinha

License

MIT © 2026 Chhagan Sinha. See LICENSE.