Getting Started

Prerequisites

Before continuing, make sure you have:

React >= 18
A React framework (Next.js, Vite, Remix, etc.)

VitalGrid gives you:

A ready-to-use virtualized table built on TanStack React Table
Drag and drop for rows and columns (via dnd-kit)
Dynamic columns driven by your data layer
A simple data source interface so you can plug in any backend

Getting Started

Install VitalGrid and its peer dependencies:

bun add @fed/vital-grid
bun add react react-dom @tanstack/react-table styled-components @dnd-kit/core @dnd-kit/sortable @dnd-kit/modifiers @dnd-kit/utilities

npm install @fed/vital-grid
npm install react react-dom @tanstack/react-table styled-components @dnd-kit/core @dnd-kit/sortable @dnd-kit/modifiers @dnd-kit/utilities

yarn add @fed/vital-grid
yarn add react react-dom @tanstack/react-table styled-components @dnd-kit/core @dnd-kit/sortable @dnd-kit/modifiers @dnd-kit/utilities

Peer Dependencies

VitalGrid requires the following peer dependencies:

react >= 18
react-dom >= 18
@tanstack/react-table ^8.0.0
styled-components > 5
@dnd-kit/core ^6.0.0 (for drag and drop)
@dnd-kit/sortable ^10.0.0 (for drag and drop)
@dnd-kit/modifiers ^9.0.0 (for drag and drop)
@dnd-kit/utilities ^3.2.2 (for drag and drop)

Setup

Create Your Factory

Create your VitalGrid factory once, not inside a component. This factory configures which features you want enabled.

Create a file to export your factory (e.g., lib/vital-grid.ts):

lib/vital-grid.ts

import { createVitalGrid } from "@fed/vital-grid";

export const VitalGrid = createVitalGrid({
  features: {
    sorting: true,
    filtering: true,
    columnReordering: true,
    rowReordering: true,
    columnResizing: true,
    virtualization: true,
    views: true,
  },
  // Optional: register custom fields here
  // fields: {
  //   status: createStatusField(),
  //   ...
  // },
});

Key points:

Factory is pure configuration: which features you want and which field types you support
No data, no backend, no hooks here
Create the factory once at module scope, not inside a component

Set Up a Data Source

VitalGrid works with any backend through the VitalGridDataSource interface. For a quick start, use a local storage data source:

components/MyTable.tsx

import { useLocalStorageDataSource, VitalGrid } from "@fed/vital-grid";

export function MyTable() {
  const dataSource = useLocalStorageDataSource("demo", {
    // Optional: seed rows and columns
    // initialRows: [...],
    // defaultColumns: [...],
  });

  const { grid } = VitalGrid.useVitalGrid({
    dataSource,
    data: dataSource.rows.current,
    columns: dataSource.columns.current.map(VitalGrid.createColumnDef),
  });

  return (
    <VitalGrid.Provider grid={grid} workspaceId="demo" height={600}>
      <VitalGrid.Root>
        <VitalGrid.Toolbar showViewControls={grid.features.views} />
        <VitalGrid.Header />
        <VitalGrid.Body />
      </VitalGrid.Root>
    </VitalGrid.Provider>
  );
}

This gives you:

Virtualized table
Basic sorting/filtering (depending on feature flags)
Column resizing
Local persistence for rows and columns
No backend needed

Note: To connect your own backend, VitalGrid uses the VitalGridDataSource<T> interface. See the Data Sources Guide for details.

Finish

You can now start using VitalGrid in your app! The basic pattern is:

Create a factory once with createVitalGrid (configure features)
Set up a data source (local storage for quick start, or your backend)
Use the factory hook VitalGrid.useVitalGrid with your data source
Render with compound components inside VitalGrid.Provider

What You Get Out of the Box

With features enabled, you get:

Virtualization: Large datasets handled efficiently
Drag and drop: For columns and rows (data source must support reordering)
System columns: Selection column, drag handle, add-column control

You do not need to wire TanStack Virtual or dnd-kit manually; VitalGrid handles that for you.

Next Steps

Once you have the basic grid working, explore:

Concepts Guide: Deeper explanation of factory, hook, provider, data source, and fields
Data Sources Guide: How to build your own VitalGridDataSource
Compound Components Guide: Layout, toolbar, header/body customization
Fields Guide: Implementing custom field types

Quick Checklist

Use this to sanity-check your setup:

Factory created once with createVitalGrid
Using a data source that returns VitalGridDataSource
useVitalGrid called with dataSource, data, columns
columns.current are VitalGridColumn[] and passed through createColumnDef
Wrapped content inside <VitalGrid.Provider grid={grid} ...>
Using <VitalGrid.Root>, <VitalGrid.Toolbar>, <VitalGrid.Header>, <VitalGrid.Body> inside the provider

If all of that is true, you are using VitalGrid the intended way and can layer on more advanced behavior with confidence.

Getting Started

Create Your Factory

Set Up a Data Source

On this page