@panitw/pgrid

A virtualized, extensible JavaScript data grid with frozen panes, inline editing, copy/paste, column resizing, and a pluggable extension API.

📖 Documentation · 🎮 Live samples · 📦 npm

Features

• Virtualized rendering — renders only visible cells; handles large datasets smoothly
• Frozen panes — freeze any number of leading rows/columns (6-pane layout: top-left/top/left/center/bottom-left/bottom) — demo
• Inline editing with cancellable update hooks — demo
• Copy / paste across cell ranges, spreadsheet-compatible TSV — demo
• Column resizing, text overflow, checkbox columns — demos
• Custom editors — dropdowns, date pickers, anything HTML — demo
• Cell formatters — pills, currency, progress bars, stars — demo
• Themes — toggle dark / compact / spreadsheet looks via a single CSS class — demo
• Extension API — every built-in feature is itself an extension; add your own without touching core
• Sort / filter / search at the data layer (DataTable) without losing original row order

Install

npm install @panitw/pgrid

Quick start

import { PGrid } from '@panitw/pgrid';
import '@panitw/pgrid/styles';

const grid = new PGrid({
  rowHeight: 28,
  columnWidth: 90,
  editing: true,
  autoUpdate: true,
  selection: { cssClass: 'cell-selection' },
  freezePane: { left: 1 },
  columns: [
    { id: 0, field: 'name',  title: 'Name' },
    { id: 1, field: 'qty',   title: 'Qty', editable: true },
    { id: 2, field: 'price', title: 'Price', editable: true }
  ],
  dataModel: {
    fields: ['name', 'qty', 'price'],
    format: 'array',
    data: [
      ['Apple',  10, 1.5],
      ['Banana', 20, 0.5],
      ['Cherry',  5, 3.0]
    ]
  }
});

grid.render(document.getElementById('gridDiv'));

Or load the UMD bundle directly:

<link rel="stylesheet" href="https://unpkg.com/@panitw/pgrid/dist/pgrid.css">
<script src="https://unpkg.com/@panitw/pgrid/dist/pgrid.js"></script>
<script>
  const grid = new PGrid.PGrid({ /* config */ });
  grid.render(document.getElementById('gridDiv'));
</script>

Documentation

Full documentation is published at https://panitw.github.io/pgrid/ and includes:

• Getting Started — install, your first grid, walkthrough
• Configuration — every config option, with examples
• Working with Data — formats, CRUD, search, events
• Styling — CSS class reference, theming, recipes
• Extensions — hook reference, custom editors, formatters
• API — compact reference for PGrid, DataTable, Model, View

Every feature has a runnable demo — see the samples gallery.

Built-in extensions

Available as named exports alongside PGrid:

import {
  PGrid,
  CheckboxColumnExtension,
  ColumnResizeExtension,
  TextOverflowExtension
} from '@panitw/pgrid';

Writing an extension

An extension is a plain object with optional init(grid, config) and any of the named hooks:

cellRender, cellAfterRender, cellUpdate, cellAfterUpdate, cellEditableCheck, cellAfterRecycled, keyDown, gridAfterRender, dataBeforeRender, dataBeforeUpdate, dataAfterUpdate, dataFinishUpdate.

const upperCaseExtension = {
  cellRender(e) {
    if (typeof e.data === 'string') e.cell.innerText = e.data.toUpperCase();
  }
};

new PGrid({ extensions: [upperCaseExtension], /* ... */ });

Cells are recycled during virtualization, so any DOM mutations made in cellRender should be reset in cellAfterRecycled. See the Extensions guide for more.

Architecture

PGrid → DataTable (data) + Model (layout/config) + View (DOM/render) + Extension (plugin registry) + State

These pieces don't talk to each other directly — they're coordinated through PGrid and the extension registry. See CLAUDE.md for a deeper tour.

Development

npm install
npm run dev          # Vite dev server on http://localhost:8888, opens samples/index.html
npm test             # Mocha + jsdom
npm run build        # produces dist/pgrid.js (UMD) + dist/pgrid.css for npm publish
npm run build:site   # builds the docs + samples site into site/ for GitHub Pages
npm run preview:site # preview the built site locally on http://localhost:4173

Samples in samples/ are the integration harness — they import PGrid directly from /src/index.js with HMR. Documentation pages live in docs/. Both are bundled together by npm run build:site and deployed automatically by .github/workflows/deploy-pages.yml on every push to master.

License

MIT © Panit Wechasil