@utiltools/datagrid

A lightweight, TypeScript-first React data grid with sorting, filtering, pagination and row selection.

✨ Features

• ⚛️ React 18+ — Built for modern React applications
• 🔒 TypeScript First — Complete type safety and IntelliSense
• 📦 Lightweight — Minimal bundle size, no external dependencies
• 🎨 Customizable — Easy to style and theme
• ⚡ Performant — Handles large datasets efficiently
• ♿ Accessible — Keyboard navigation and ARIA attributes
• 📱 Responsive — Works on all screen sizes

📦 Installation

npm install @utiltools/datagrid

yarn add @utiltools/datagrid

pnpm add @utiltools/datagrid

🚀 Quick Start

import { DataGrid } from '@utiltools/datagrid';
import type { ColumnDef } from '@utiltools/datagrid';

interface User {
  id: number;
  name: string;
  email: string;
  role: string;
}

const data: User[] = [
  { id: 1, name: 'Alice Johnson', email: '[email protected]', role: 'Admin' },
  { id: 2, name: 'Bob Smith', email: '[email protected]', role: 'User' },
  { id: 3, name: 'Charlie Brown', email: '[email protected]', role: 'Editor' },
];

const columns: ColumnDef<User>[] = [
  { key: 'name',  label: 'Name',  sortable: true, filterable: true },
  { key: 'email', label: 'Email', sortable: true },
  { key: 'role',  label: 'Role',  sortable: true },
];

function App() {
  return (
    <DataGrid
      data={data}
      columns={columns}
      rowKey="id"
      pageSize={10}
      searchable
    />
  );
}

🎯 Core Features

Column Definition (ColumnDef<T>)

interface ColumnDef<T> {
  key: keyof T & string;          // must match a property in your row objects
  label: string;                  // header text
  sortable?: boolean;             // enable sort on click (default: false)
  filterable?: boolean;           // show per-column filter input (default: false)
  width?: number;                 // fixed pixel width
  minWidth?: number;              // minimum width
  align?: 'left' | 'center' | 'right';
  render?: (value: unknown, row: T, rowIndex: number) => string; // HTML string renderer
  hidden?: boolean;               // exclude column from render
  pinned?: boolean;               // pin column to the left
}

Sorting

Click any column header marked sortable: true to cycle through ascending → descending → unsorted.

const columns: ColumnDef<User>[] = [
  { key: 'name', label: 'Name', sortable: true },
  { key: 'age',  label: 'Age',  sortable: true },
];

Filtering

Set filterable: true on any column to show a filter input beneath the column header. A global search box is also shown in the toolbar by default.

const columns: ColumnDef<User>[] = [
  { key: 'name',  label: 'Name',       sortable: true, filterable: true },
  { key: 'city',  label: 'City',       sortable: true, filterable: true },
  { key: 'salary', label: 'Salary',    sortable: true },
];

// Disable the global search box
<DataGrid data={data} columns={columns} rowKey="id" searchable={false} />

Pagination

<DataGrid
  data={data}
  columns={columns}
  rowKey="id"
  pageSize={25}
  pageSizeOptions={[10, 25, 50, 100]}
/>

Row Selection

import { useState } from 'react';

function MyGrid() {
  const [selected, setSelected] = useState<Set<string>>(new Set());

  return (
    <>
      <p>{selected.size} rows selected</p>
      <DataGrid
        data={data}
        columns={columns}
        rowKey="id"
        selectable
        onSelectionChange={setSelected}
      />
    </>
  );
}

Custom Cell Rendering

The render function returns an HTML string. Use it for badges, formatted values, etc.

const columns: ColumnDef<User>[] = [
  {
    key: 'status',
    label: 'Status',
    sortable: true,
    align: 'center',
    render: (value) => {
      const color = value === 'Active' ? 'green' : 'gray';
      return `<span style="color:${color};font-weight:600">${value}</span>`;
    },
  },
  {
    key: 'salary',
    label: 'Salary',
    sortable: true,
    align: 'right',
    render: (value) =>
      typeof value === 'number' ? `$${value.toLocaleString()}` : '—',
  },
];

Loading State

<DataGrid
  data={[]}
  columns={columns}
  rowKey="id"
  pageSize={10}
  loading
/>

Striped Rows

<DataGrid data={data} columns={columns} rowKey="id" striped />

📋 Props Reference

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | TRow[] | required | Array of row objects | | columns | ColumnDef<TRow>[] | required | Column definitions | | rowKey | keyof TRow | index | Field used as unique row identifier | | pageSize | number | 10 | Initial rows per page | | pageSizeOptions | number[] | [10, 25, 50, 100] | Page size dropdown options | | selectable | boolean | false | Enable row selection checkboxes | | striped | boolean | false | Alternate row background colors | | searchable | boolean | true | Show global search input in toolbar | | searchPlaceholder | string | "Search…" | Global search input placeholder | | loading | boolean | false | Show skeleton loading state | | emptyMessage | string | "No data to display." | Message shown when data is empty | | className | string | "" | Additional CSS classes for the outer wrapper | | onSelectionChange | (keys: Set<string>) => void | — | Fired when selected rows change |

🔗 Related Packages

• @utiltools/grid-core — framework-agnostic sorting, filtering, pagination and selection engine (used internally)

📚 Documentation

Full documentation, API reference, and interactive demos:

👉 developer.utiltools.org/docs/datagrid

🎮 Live Demo

👉 developer.utiltools.org/demos/datagrid

📄 License

MIT © Fatih Sevim

🤝 Contributing

Contributions, issues and feature requests are welcome!

See GitHub repository for more information.

Made with ❤️ by the UtilTools team