@tanstack-table-ultimate/react

A high-performance, feature-rich React data table built on TanStack Table with drag-and-drop, selection management, and sectioned views.

Features

• ✅ Performance Optimized - Memoized cells and rows for minimal re-renders
• ✅ Drag & Drop - Built-in row reordering with @hello-pangea/dnd
• ✅ Selection Management - Zustand-powered selection store with per-row subscriptions
• ✅ Sectioned Tables - Group data into collapsible sections
• ✅ Loading States - Skeleton loaders during data fetching
• ✅ Pagination - Built-in pagination support
• ✅ Sorting - Column sorting with visual indicators
• ✅ TypeScript - Full type safety with generics
• ✅ Customizable UI - Provide your own Checkbox, Pagination, and Skeleton components
• ✅ Tailwind Compatible - Works great with Tailwind CSS

Installation

npm install @tanstack-table-ultimate/react @tanstack/react-table
# or
yarn add @tanstack-table-ultimate/react @tanstack/react-table
# or
pnpm add @tanstack-table-ultimate/react @tanstack/react-table

Quick Start

import { DataTable } from "@tanstack-table-ultimate/react";
import { ColumnDef } from "@tanstack/react-table";

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

const columns: ColumnDef<User>[] = [
  {
    accessorKey: "name",
    header: "Name",
  },
  {
    accessorKey: "email",
    header: "Email",
  },
];

const data: User[] = [
  { id: "1", name: "John Doe", email: "[email protected]" },
  { id: "2", name: "Jane Smith", email: "[email protected]" },
];

function App() {
  return <DataTable columns={columns} data={data} idField="id" />;
}

With Pagination

import { useState } from "react";
import { DataTable } from "@tanstack-table-ultimate/react";

function App() {
  const [page, setPage] = useState(1);

  return (
    <DataTable
      columns={columns}
      data={data}
      idField="id"
      page={page}
      setPage={setPage}
      total={100}
      limit={10}
    />
  );
}

With Drag and Drop

import { DataTable } from "@tanstack-table-ultimate/react";

function App() {
  const handleDragEnd = (result, sectionId) => {
    console.log(
      "Moved from",
      result.source.index,
      "to",
      result.destination.index
    );
  };

  return (
    <DataTable
      columns={columns}
      data={data}
      idField="id"
      enableRowDrag
      onRowDragEnd={handleDragEnd}
    />
  );
}

With Sections

import {
  DataTable,
  DataTableSectionItem,
} from "@tanstack-table-ultimate/react";

const sections: DataTableSectionItem<User>[] = [
  {
    id: "active",
    title: "Active Users",
    data: [{ id: "1", name: "John", email: "[email protected]" }],
  },
  {
    id: "inactive",
    title: "Inactive Users",
    data: [{ id: "2", name: "Jane", email: "[email protected]" }],
  },
];

function App() {
  return (
    <DataTable
      columns={columns}
      data={[]}
      sections={sections}
      idField="id"
      enableSectionSelection
      tableId="my-table"
    />
  );
}

With Selection

Using the built-in Zustand selection store:

import {
  DataTable,
  useSelectedRows,
  selectionActions,
} from "@tanstack-table-ultimate/react";

function App() {
  const selectedUsers = useSelectedRows<User>("my-table");

  const handleClearSelection = () => {
    selectionActions.clearSelection("my-table");
  };

  return (
    <div>
      <p>Selected: {selectedUsers.length}</p>
      <button onClick={handleClearSelection}>Clear</button>

      <DataTable
        columns={columns}
        data={data}
        idField="id"
        tableId="my-table"
        enableRowSelection
      />
    </div>
  );
}

Custom UI Components

You can replace the default UI components with your own:

import {
  DataTable,
  CheckboxRenderProps,
  PaginationRenderProps,
} from "@tanstack-table-ultimate/react";

// Custom checkbox using your UI library
const MyCheckbox: React.FC<CheckboxRenderProps> = ({
  isSelected,
  isIndeterminate,
  isDisabled,
  onChange,
}) => (
  <input
    type="checkbox"
    checked={isSelected}
    ref={(el) => {
      if (el) el.indeterminate = !!isIndeterminate;
    }}
    disabled={isDisabled}
    onChange={onChange}
  />
);

// Custom pagination
const MyPagination: React.FC<PaginationRenderProps> = ({
  page,
  totalPages,
  onPageChange,
}) => (
  <div>
    <button onClick={() => onPageChange(page - 1)} disabled={page <= 1}>
      Previous
    </button>
    <span>
      Page {page} of {totalPages}
    </span>
    <button
      onClick={() => onPageChange(page + 1)}
      disabled={page >= totalPages}
    >
      Next
    </button>
  </div>
);

function App() {
  return (
    <DataTable
      columns={columns}
      data={data}
      components={{
        Checkbox: MyCheckbox,
        Pagination: MyPagination,
      }}
    />
  );
}

API Reference

DataTable Props

| Prop | Type | Default | Description | | ------------------------ | ------------------------------- | --------------------- | ----------------------------- | | columns | ColumnDef<TData, TValue>[] | Required | Column definitions | | data | TData[] | Required | Data array | | sections | DataTableSectionItem<TData>[] | - | Grouped data sections | | idField | string | - | Field to use as row ID | | tableId | string | - | Unique ID for selection store | | page | number | - | Current page (1-indexed) | | setPage | (page: number) => void | - | Page change handler | | total | number | - | Total row count | | limit | number | 10 | Rows per page | | hidePagination | boolean | false | Hide pagination | | enableRowSelection | boolean \| (row) => boolean | false | Enable row selection | | enableSectionSelection | boolean | false | Enable section selection | | enableRowDrag | boolean | false | Enable drag and drop | | isDragDisabled | boolean | false | Disable drag temporarily | | showDragableIcon | boolean | true | Show drag handle icon | | onRowDragEnd | (result, sectionId?) => void | - | Drag end handler | | isLoading | boolean | false | Show loading skeletons | | initialSorting | SortingState | [] | Initial sort state | | emptyStateMessage | string \| ReactNode | "No data available" | Empty state content | | className | string | - | Container class | | rowClassName | string \| (row) => string | - | Row class | | headerClassName | string | - | Header class | | cellClassName | string | - | Cell class | | outerShadow | boolean | true | Show container shadow | | showDivider | boolean | true | Show row dividers | | components | CustomUIComponents | - | Custom UI components |

Selection Hooks

// Check if a specific row is selected
const isSelected = useIsRowSelected(tableId, rowId);

// Get count of selected rows
const count = useSelectedCount(tableId);

// Get array of selected row IDs
const ids = useSelectedIds(tableId);

// Get array of selected row objects
const rows = useSelectedRows<TData>(tableId);

Selection Actions

import { selectionActions } from "@tanstack-table-ultimate/react";

// Toggle a row's selection
selectionActions.toggleRow(tableId, rowId, rowData);

// Set a row's selection state
selectionActions.setRowSelected(tableId, rowId, true, rowData);

// Select/deselect multiple rows
selectionActions.setMultipleRows(tableId, rows, true);

// Clear all selections
selectionActions.clearSelection(tableId);

// Get selected count
const count = selectionActions.getSelectedCount(tableId);

// Get selected IDs
const ids = selectionActions.getSelectedIds(tableId);

License

MIT © Ali338991