Building LitGrid: One Web Component DataGrid for React, Angular, Vue, and Blazor

Paul Young — Fri, 02 Oct 2026 08:48:48 +0000

TL;DR

This is my first article about LitGrid, so I wanted to start with the architectural decision that shaped the project from the beginning.

I started LitGrid with one rule for myself:

Build the grid once as a real Web Component, keep its internals behind Shadow DOM, and adapt frameworks around that component instead of rebuilding the grid for each one.

Today, React, Angular, Vue, Blazor, and direct Web Component usage all sit on top of the same LitGrid implementation.

Behind the component, grid state and virtualization live in separate layers.

Live demo:

https://tipolox.com/litgrid/demo

Source:

https://github.com/tipolox/litgrid

The part I found interesting was not simply building another table component.

I was already working with Lit and Shadow DOM, and I kept coming back to the same question: could I keep that component boundary and still make the grid practical in several frameworks?

The constraint that shaped everything

When I started LitGrid, the idea was not to build a React grid, then an Angular grid, then repeat the work again for Vue and Blazor.

I wanted one implementation.

React ────────┐
Angular ──────┤
Vue ──────────┼──► LitGrid Web Component
Blazor ───────┤
Web Component ┘

The idea was simple: the React package should not implement its own sorting, selection, virtualization, keyboard navigation, column resizing, or filtering. The same goes for Angular, Vue, and Blazor.

Their job is to translate framework conventions into the public API of the same browser component. If I fix grid behavior in one place, I want all integration to benefit from it.

This has led to this architecture:

Framework adapters
        │
        ▼
   Web Component
        │
     LitElement
    Shadow DOM
        │
   ┌────┴─────┐
   │          │
Grid Core   Renderer
state/data  virtualization

React, Angular, Vue, and Blazor are not interchangeable, and I don't try to hide those differences.

The part I want to keep shared is the grid implementation itself. Each adapter deals with framework ergonomics; the grid behavior stays in one place.

Why Lit and Shadow DOM?

Lit was part of the original direction, not something I added later to make the project framework-neutral.

The main DataGrid class extends LitElement, and LitGrid keeps Lit's normal Shadow DOM render root instead of switching to light DOM.

Conceptually:

<yc-grid>
  #shadow-root
    header
    viewport
    rows
    cells
    menus
    pagination
</yc-grid>

That sounds like a small implementation choice, but it defines a lot of the architecture.

Applications do not need to depend on internal selectors like:

.viewport
.header-cell
.cell
.header-menu

Those details belong to LitGrid.

Consumers work with the host element through public properties, methods, and events.

Styling follows the same philosophy.

Internal styles live inside the component, while semantic CSS custom properties provide the external theming surface.

For example:

yc-grid {
  --litgrid-color-accent: #2563eb;
  --litgrid-color-surface: #ffffff;
  --litgrid-color-text: #111827;
}

LitGrid currently uses CSS custom properties as its main public styling mechanism.

It does not currently expose a broad ::part() styling API.

That is intentional for now. Once an internal element becomes part of a public styling contract, changing the markup later gets harder. I would rather expose a smaller, deliberate surface first.

Shadow DOM gave me the encapsulation I wanted. It also made a few problems impossible to ignore.

What Shadow DOM made me handle

Encapsulation is useful, but a DataGrid is not a static card component.

It has focus, keyboard navigation, menus, selection, ARIA state, scrolling, drag interactions, and a lot of DOM coordination.

Focus management

LitGrid keeps its active-cell model internally and uses the grid viewport as the keyboard focus entry point.

Arrow keys move the active cell.

Home and End move across row boundaries.

Page Up and Page Down move by viewport-sized ranges.

Tab and Shift+Tab can move between grid cells while still allowing normal browser focus traversal when the grid boundary is reached.

Header menus also need explicit focus behavior.

When a menu opens, focus moves into it.

When Escape closes the menu, focus returns to the trigger.

This was one of the first places where encapsulation stopped being "free." A grid has to feel predictable from the keyboard, so I ended up treating focus movement as explicit component behavior and covering it with tests rather than assuming the browser would always do the right thing across the shadow boundary.

ARIA relationships

The viewport uses ARIA grid semantics, including logical row and column counts and an active descendant.

One important detail is that the referenced elements are inside the same Shadow Root as the viewport.

For example, the active-cell relationship stays internal to the component rather than trying to reference an element across the Shadow DOM boundary.

That keeps the accessibility model aligned with the component structure.

I also try to be careful with the accessibility claim. LitGrid implements ARIA grid semantics, keyboard interaction, and optional screen-reader announcements, and those structures have automated coverage.

What I am not claiming is exhaustive validation across every browser and screen-reader combination. That kind of confidence needs broader real-world testing.

A public API instead of DOM coupling

The Web Component boundary only helps if the adapters respect it.

For example, I don't want the React package reaching through the shadow root to find private elements:

grid.shadowRoot
  ?.querySelector('.viewport')
  ?.something()

That would work until the internal markup changed. Then a harmless refactor inside LitGrid could break a framework adapter.

Instead, the host exposes operations directly:

grid.data = rows
grid.columns = columns
grid.config = config

grid.setColumnVisible('email', false)
grid.setQuickSearch('active')
grid.setPage(2)

State changes can also be observed through DOM events.

For example:

new CustomEvent('column-state-change', {
  bubbles: true,
  composed: true,
  detail: {
    reason,
    state
  }
})

Those events are dispatched from the custom-element host and translated by the framework adapters into the conventions expected by each framework.

What a thin React adapter actually looks like

This is also why I describe the adapters as thin. In the React integration, "thin" is fairly literal.

The React integration ultimately renders the Web Component:

return <yc-grid ref={gridRef}></yc-grid>

Complex values are assigned as JavaScript properties rather than serialized as HTML attributes:

export function syncGridInputs(grid, inputs) {
  grid.data = inputs.data
  grid.columns = inputs.columns
  grid.config = inputs.config
  grid.theme = inputs.theme

  grid.ariaLabel = inputs.ariaLabel
  grid.ariaDescription = inputs.ariaDescription

  grid.viewportHeight = inputs.height
  grid.virtualRowHeight = inputs.rowHeight

  grid.overscanCount = inputs.overscan
  grid.columnOverscanCount = inputs.columnOverscan
}

That property assignment matters for Web Components.

Things like arrays, column definitions, callbacks, and configuration objects are not naturally represented as string attributes.

The adapter also listens to DOM events:

useEffect(() => {
  const element = gridRef.current

  if (!element || !onColumnStateChange) {
    return
  }

  const handler = event => {
    onColumnStateChange(event.detail)
  }

  element.addEventListener('column-state-change', handler)

  return () => {
    element.removeEventListener('column-state-change', handler)
  }
}, [onColumnStateChange])

And then React developers use a normal React-facing API:

<DataGrid
  data={rows}
  columns={columns}
  height={400}
  onColumnStateChange={handleColumnStateChange}
/>

That is most of the job: translate React-shaped inputs and callbacks into the Web Component contract. Sorting, selection, virtualization, and the rest still belong to LitGrid itself.

The Web Component isn't the whole architecture

As the grid grew, another problem became obvious: putting every piece of logic inside one large LitElement would eventually make the component difficult to reason about.

So I split responsibilities instead of treating the Web Component as the entire architecture.

Grid Core

The core handles state and data operations such as:

sorting
filtering
Quick Search
pagination
selection
configuration

It does not need the DOM to perform those operations.

That makes the logic easier to test independently from the component UI and keeps browser-rendering concerns out of the data engine.

Renderer utilities

The renderer layer contains virtualization and scroll-mapping calculations.

That math should not care whether the caller happens to be React, Angular, Vue, or Blazor. Keeping it separate also makes it easier to test without dragging the whole component lifecycle into the test.

Web Component

The Web Component combines those layers with:

DOM rendering
pointer interaction
focus
keyboard navigation
menus
sizing
scrolling
ARIA behavior

That separation gives the project a useful rule of thumb:

Data/state problem
      ↓
    Core

Virtual-coordinate problem
      ↓
  Renderer

Browser interaction/rendering
      ↓
  Web Component

Framework convention
      ↓
   Adapter

The boundaries are not perfect, and I do not expect them to be. But when I add something new, this gives me a practical first question: is this grid state, virtualization math, browser behavior, or framework glue?

Virtualization is more than "render fewer rows"

The obvious reason to virtualize a grid is DOM size.

If a logical dataset contains:

100,000 rows × 50 columns

the grid should not create five million DOM cells.

LitGrid instead renders the rows and columns that intersect the active viewport, plus overscan.

Logical dataset
│
│      not rendered
│
├───────────────────────
│       overscan
│   ┌───────────────┐
│   │   viewport    │
│   │               │
│   │ rendered rows │
│   │ and columns   │
│   │               │
│   └───────────────┘
│       overscan
├───────────────────────
│
│      not rendered

Rendering fewer rows was the obvious virtualization problem. The less obvious problem showed up when the logical scroll space became very large.

A browser cannot represent an arbitrarily tall element forever. Eventually, a huge spacer can be clamped internally, which means the browser's physical scroll range no longer matches the grid's logical row space.

LitGrid therefore keeps a distinction between:

logical / virtual scroll space

and:

physical browser scroll space

The current implementation caps its intended physical scroll height:

private maxScrollableHeight = 67108864

For datasets whose virtual height exceeds that display space, LitGrid maps the browser-visible scroll position back into the larger virtual coordinate system.

Conceptually:

browser scrollTop
       │
       │ map ratio
       ▼
virtual scroll offset
       │
       ▼
virtualizer
       │
       ▼
visible row range

There is another complication.

A browser may clamp the physical spacer below even the requested capped size.

After render, LitGrid measures the actual spacer height.

If the browser produced something smaller than expected, subsequent scroll mapping uses the measured size rather than assuming the requested height was honored.

I did not start the project thinking about browser element-height limits. This is exactly the kind of problem that only appeared after the basic virtualization model was already working, and it forced me to separate logical scroll coordinates from the physical scroll space the browser can actually represent.

Row and column virtualization

LitGrid virtualizes both axes.

The row virtualizer determines:

start row
end row
offset top
visible size
bottom padding

while the column virtualizer performs a similar job horizontally.

Both fixed and variable row sizes are supported.

This lets the rendered DOM stay tied to what the user can currently see rather than to the entire dataset.

I deliberately avoid calling LitGrid "the fastest grid."

Performance depends on:

dataset structure
cell renderers
browser
hardware
overscan configuration
application behavior
framework integration

The concrete claim is simpler:

LitGrid uses row and column virtualization so the rendered DOM follows the active viewport rather than the complete logical dataset.

The renderer tradeoff

This is where the architecture pushes back the hardest against normal framework expectations.

Cell rendering belongs to LitGrid's Lit rendering system.

A renderer can return a simple value:

{
  key: 'amount',
  render: value =>
    `$${Number(value).toLocaleString()}`
}

or a Lit template:

import { html } from 'lit'

{
  key: 'status',
  render: value =>
    html`<strong>${String(value)}</strong>`
}

A Lit template can also contain another Web Component:

{
  key: 'status',
  render: value =>
    html`
      <status-badge .status=${value}></status-badge>
    `
}

What it cannot currently do is take over cell rendering with a framework-native renderer.

For example, this is not a supported React cell renderer today:

render: value => (
  <StatusBadge status={value} />
)

Likewise, LitGrid does not currently mount Vue VNodes or Angular components as native cell renderers.

That is a real limitation. A React developer naturally wants to reuse an existing <StatusBadge />, action menu, avatar, or button inside a cell. Today, LitGrid does not let React take over that cell directly.

For some applications that will be fine; for others it may be a dealbreaker. I would rather say that plainly than call the integration "framework-ready" and leave the important caveat in the small print.

The reason for the limitation is also the same reason LitGrid can maintain one internal rendering implementation:

The framework integrates with the grid, but Lit remains responsible for the grid's internal rendering.

I do think there is a way to improve this without throwing away the architecture.

One option I am exploring is a renderer-host API where LitGrid owns the cell and its lifecycle, but a framework adapter is allowed to mount something into a host that LitGrid provides.

Something like:

interface ExternalCellRenderer {
  mount(host: HTMLElement, context: CellContext): void
  update(context: CellContext): void
  destroy(): void
}

That could potentially allow React, Vue, or Angular components to live inside virtualized cells without moving framework logic into the grid core.

The important design requirement would be that existing string and Lit renderers stay on their current fast path.

Framework-native rendering should be opt-in so only applications using it pay the extra component lifecycle cost.

I have put this on the roadmap as a design problem, not as a promised feature. Before making it public API, I want to prove that mount/update/destroy works cleanly with virtualization and that users who stay on the existing Lit path do not pay for the extra framework lifecycle.

Browser-side rendering and SSR

SSR is another place where the current architecture has a visible edge.

The Web Component package currently registers the custom element in the browser:

if (!customElements.get('yc-grid')) {
  customElements.define('yc-grid', DataGrid)
}

That means LitGrid should currently be treated as a browser-side interactive component.

For SSR frameworks such as Next.js, the integration should be loaded in a client/browser context rather than assuming the grid itself can execute in a normal server-only JavaScript environment.

The same general distinction applies elsewhere:

the application shell can be server-rendered, while the interactive DataGrid is initialized on the client.

I would rather document that boundary clearly now and harden it over time than imply that choosing Web Components automatically solves SSR.

Blazor is a slightly different integration

Blazor forced a slightly different adapter shape because the integration crosses both a framework boundary and a language/runtime boundary.

The public NuGet package is:

dotnet add package Tipolox.LitGrid.Blazor

It provides a strongly typed:

DataGrid<TItem>

and bundles the required JavaScript as Razor Class Library static assets.

It supports .NET 8+ Blazor WebAssembly and Blazor Server applications.

DOM interaction still happens in JavaScript because the actual grid lives in the browser.

The Razor component communicates with that browser component through asynchronous JS interop.

That means Blazor shares the same underlying Web Component, but the adapter mechanics are necessarily different from React or Vue.

I also do not want to blur browser-side grid performance with Blazor Server round trips.

In Server mode, round trips that cross the Blazor circuit naturally depend on network and server latency.

The grid's browser-side interaction remains local, but application callbacks that cross that boundary have different performance characteristics from WebAssembly.

What LitGrid supports today

The current open-source release includes:

Virtualization
  Row virtualization
  Column virtualization
  Variable row sizing

Data
  Sorting
  Filtering
  Quick Search
  Pagination

Interaction
  Row selection
  Cell selection
  Multi-selection
  Keyboard navigation
  Clipboard operations

Columns
  Resize
  Reorder
  Visibility
  Best fit

State
  Column state
  Persistence
  State-change events

UI
  Light and dark themes
  Lit-based custom renderers

Accessibility
  ARIA grid semantics
  Keyboard focus behavior
  Optional screen-reader announcements

Column state can also be manipulated programmatically:

grid.setColumnState(savedState)

LitGrid intentionally emits state-change events when the effective state changes through that imperative API.

The event contains a reason such as:

resize
reorder
visibility
restore
reset
set

so applications can distinguish the source of a change when necessary.

Using LitGrid directly

The Web Component package can be used without a framework wrapper.

pnpm add @tipolox/litgrid-web

Import the package:

import '@tipolox/litgrid-web'

Then:

<yc-grid id="users-grid"></yc-grid>

and assign structured values as properties:

const grid =
  document.querySelector('#users-grid')

grid.data = [
  { id: 1, name: 'Ada' },
  { id: 2, name: 'Grace' }
]

grid.columns = [
  {
    key: 'id',
    header: 'ID',
    width: 80
  },
  {
    key: 'name',
    header: 'Name',
    width: 220
  }
]

grid.viewportHeight = 400

The framework adapters are conveniences around this browser component.

They are not prerequisites for the grid itself.

Framework packages

The current integrations are distributed as:

pnpm add @tipolox/litgrid-react
pnpm add @tipolox/litgrid-angular
pnpm add @tipolox/litgrid-vue
pnpm add @tipolox/litgrid-web

and for Blazor:

dotnet add package Tipolox.LitGrid.Blazor

The naming is admittedly a little mixed today:

npm organization   @tipolox/*
browser element    <yc-grid>
Blazor package     Tipolox.LitGrid.Blazor

Those names come from different stages of the project, but they all refer to the same LitGrid implementation.

When LitGrid may not be the right fit

Since this is the first article I am writing about LitGrid, I also want to be clear about where I would not recommend it yet.

LitGrid may not be the best fit today if your application requires:

Native framework components inside every custom cell.

The current renderer belongs to Lit. React JSX, Angular components, and Vue VNodes are not currently native cell-renderer outputs.

Deep styling of arbitrary internal elements.

The current public styling contract is primarily CSS custom properties rather than a large ::part() surface.

Server-only rendering of the grid itself.

LitGrid is currently designed as an interactive browser component.

A mature grid ecosystem with years of production history.

LitGrid is still a young open-source project. I am actively looking for the kinds of edge cases that only appear when a component meets real applications.

Some of those constraints are exactly the things I want to improve. But for now, they are part of the product, and I think they belong in the same article as the strengths.

Why open source?

LitGrid is MIT licensed.

Open sourcing LitGrid was important to me because a DataGrid ends up touching far more of the browser platform than the word "grid" suggests:

scrolling
layout
focus
keyboard navigation
ARIA
pointer interaction
virtualization
measurement
rendering
state
framework lifecycles

Those are exactly the kinds of areas where edge cases appear.

When somebody hits an edge case, I want the discussion to be about the code and the design decision that produced it. Keeping the implementation visible makes that possible.

Open source also makes the "one grid implementation" idea easier to evaluate.

The architecture is there to inspect: the React, Angular, Vue, Blazor, Web Component, core, and virtualization packages are all visible in the repository.

The question LitGrid is trying to answer

After working on it for a while, I think the most useful way to describe LitGrid is still as a question:

Can another DataGrid be built?

Obviously it can.

The question I am more interested in is:

Can a complex interactive UI component be implemented once around Web Components, Lit, and Shadow DOM while still providing practical integrations for React, Angular, Vue, and Blazor?

LitGrid is my attempt to answer that question in actual code. I like the direction so far, but the project has also made the costs of the architecture very concrete.

Shadow DOM gives LitGrid a strong implementation boundary, but focus and accessibility behavior need deliberate handling.

A single rendering engine prevents framework implementations from drifting apart, but framework-native cell components become harder.

Virtualization keeps DOM size under control, but very large coordinate spaces require scroll mapping because browser element height is finite.

Those tradeoffs are the part I want to keep exploring. If you have built a serious Web Component, a cross-framework library, or a virtualized UI and ran into a completely different set of problems, that is the feedback I would most like to hear.

Try it or inspect the code

LitGrid is open source under the MIT License.

Live demo

tipolox.com/litgrid/demo

GitHub

github.com/tipolox/litgrid

Open-source DataGrid overview and framework integrations

tipolox.com/litgrid/open-source-datagrid

If you work with Web Components, virtualized UI, or cross-framework libraries, I would genuinely like to hear what broke first in your design, what you ended up compromising on, and what you would do differently now.

And if you try LitGrid in a real application, please open an issue when something feels awkward or wrong. That kind of feedback is more useful to me right now than a polished feature checklist.

DEV Community: Paul Young