Data Table

A powerful and flexible data table component for displaying, filtering, sorting, and paginating tabular data.

Reference the TanStack Table Column Definitions Guide for detailed column definition guide.

Features

Advanced Filtering - Multiple filter types (text, number, date, select, multi-select) with customizable operators

URL State Management - Sync table state with URL search params using nuqs

Sorting - Multi-column sorting with persistent state

Pagination - Server-side or client-side pagination with customizable page sizes

Column Visibility - Toggle column visibility with view options menu

Row Selection - Single or multi-row selection with action bar

Column Pinning - Pin columns to left or right for better UX

Keyboard Navigation - Full keyboard support with shortcuts for filter and sort menus

Responsive - Mobile-first design with overflow handling

Customizable - Flexible API for custom filters, columns, and actions

Layout

Import all components and combine them:

import {
  DataTable,
  DataTableToolbar,
  DataTableAdvancedToolbar,
  DataTableFilterList,
  useDataTable
} from "komdes";

const { table } = useDataTable({
  data,
  columns,
  pageCount,
});

// With standard toolbar
<DataTable table={table}>
  <DataTableToolbar table={table}>
</DataTable>

// Add extra children for custom node
<DataTable table={table}>
  <DataTableToolbar table={table}>
    <Button size="icon" variant="outline">
      <RefreshCw />
    </Button>
  </DataTableToolbar>
</DataTable>

Walkthrough

Define columns with appropriate metadata:

import { Text, CalendarIcon, DollarSign } from "lucide-react";
import { DataTableColumnHeader } from "komdes";

const columns = React.useMemo(() => [
  {
    // Enter a unique ID; this is used as the query key for the column filter
    id: "username", 
    accessorFn: (row) => row.username,
    header: ({ column }) => (
      <DataTableColumnHeader column={column} title="Title" />
    ),
    cell: ({ row }) => <div>{row.getValue("title")}</div>,
    // Meta options for columns for sorting, filtering, and display options.
    meta: { 
      label: "Username", 
      placeholder: "Search username...", 
      variant: "text", 
      icon: Text, 
    }, 
    // By default is `false`; set this to `true` to enable filtering.
    enableColumnFilter: true, 
  },
], []);

Initialize the table state using the useDataTable hook:

import { useDataTable } from "komdes";

function TableDemo() {
  const { table } = useDataTable({
    data,
    columns,
    // Enter the total number of pages
    pageCount, 
    initialState: {
      pagination: { pageIndex: 0, pageSize: 10 },
      sorting: [{ desc: true, id: 'createdAt' }],
    },
    // Unique identifier for rows, can be used for unique row selection
    getRowId: (row) => row.id, 
  });

  return (
    // ... render table
  );
}

Pass the table instance to the DataTable, and DataTableToolbar components:

import { DataTable, DataTableToolbar, DataTableSortList } from "komdes";

function DataTableDemo() {
  return (
    <DataTable table={table}>
      <DataTableToolbar table={table}>
        <Button size="icon" variant="outline">
          <RefreshCw />
        </Button>
      </DataTableToolbar>
    </DataTable>
  );
}

Render an action bar on row selection:

import { ActionBar } from "@/components/ui/action-bar";

function TableActionBar({ table }: { table: Table<Data> }) {
  const rows = table.getFilteredSelectedRowModel().rows;

  const onOpenChange = React.useCallback((open: boolean) => {
    if (!open) {
      table.toggleAllRowsSelected(false);
    }
  },
  [table],
);

  return (
    <ActionBar open={rows.length > 0} onOpenChange={onOpenChange}>
      {/* Add your custom actions here */}
    </ActionBar>
  );
}

function DataTableDemo() {
  return (
    <DataTable
      table={table}
      actionBar={<TableActionBar table={table} />}
    >
      <DataTableToolbar table={table} />
    </DataTable>
  );
}

API Reference

Column Definitions

The column definitions are used to define the columns of the data table.

const columns = React.useMemo<ColumnDef<Project>[]>(
  () => [
    {
      // Required: Unique identifier for the column
      id: "title", 
      // Required: Key to access the data, `accessorFn` can also be used
      accessorKey: "title", 
      // Optional: Custom header component
      header: ({ column }) => (
        <DataTableColumnHeader column={column} title="Title" />
      ),
      // Optional: Custom cell component
      cell: ({ row }) => <div>{row.getValue("title")}</div>,
      // Optional: Meta options for filtering, sorting, and view options
      meta: {
        label: "Title",
        placeholder: "Search titles...",
        variant: "text",
        icon: Text,
      },
      // By default, the column will not be filtered. Set to `true` to enable filtering.
      enableColumnFilter: true, 
    },
    {
      id: "status",
      // Access nested data using `accessorFn`
      accessorFn: (row) => row.lineItem.status,
      header: "Status",
      meta: {
        label: "Status",
        variant: "select",
        options: [
          { label: "Active", value: "active" },
          { label: "Inactive", value: "inactive" },
        ],
      },
      enableColumnFilter: true,
    },
  ],
  [],
);

Properties

Core configuration options for defining columns.

Prop	Description
`id`	Required: Unique identifier for the column
`accessorKey`	Required: Key to access the data from the row
`accessorFn`	Optional: Custom accessor function to access data
`header`	Optional: Custom header component with column props
`cell`	Optional: Custom cell component with row props
`meta`	Optional: Meta options for accessing column metadata
`enableColumnFilter`	By default, the column will not be filtered. Set to `true` to enable filtering
`enableSorting`	Enable sorting for this column
`enableHiding`	Enable column visibility toggle

Column Meta

Column meta options for filtering, sorting, and view options.

Prop	Description
`label`	The display name for the column
`placeholder`	The placeholder text for filter inputs
`variant`	The type of filter to use (`text`, `number`, `select`, etc.)
`options`	For select/multi-select filters, an array of options with `label`, `value`, and optional `count` and `icon`
`range`	For range filters, a tuple of `[min, max]` values
`unit`	For numeric filters, the unit to display (e.g., 'hr', '$')
`icon`	The react component to use as an icon for the column

Filter Variants

Available filter variants for column meta.

Title	Description
`text`	Text search with contains, equals, etc.
`number`	Numeric filters with equals, greater than, less than, etc.
`range`	Range filters with minimum and maximum values
`date`	Date filters with equals, before, after, etc.
`dateRange`	Date range filters with start and end dates
`boolean`	Boolean filters with true/false values
`select`	Single-select filters with predefined options
`multiSelect`	Multi-select filters with predefined options

useDataTable

A hook for initializing the data table with state management.

Overview

The useDataTable hook acts as an intelligent wrapper around useReactTable from @tanstack/react-table. It seamlessly handles:

Server-side pagination, sorting, and filtering

Controlled or uncontrolled state for page and page size

Debounced column filter updates (defaults to 300ms) to prevent excessive API calls

Row selection and column visibility management

Import

import { useDataTable } from "komdes";

Usage

Basic Setup

First, define your columns. Use the meta property to configure filter behaviors.

import { useMemo, useState } from "react";
import { useDataTable, DataTable, DataTableColumnHeader } from "komdes";
import type { ColumnDef } from "@tanstack/react-table";

function useInvoiceColumns(): ColumnDef<Invoice>[] {
  return useMemo(
    () => [
      {
        accessorFn: (row) => row.invoice_id,
        id: "invoice_id",
        header: ({ column }) => (
          <DataTableColumnHeader column={column} title="Invoice ID" />
        ),
        enableColumnFilter: true,
        enableHiding: false,
        enableSorting: false,
        size: 150,
        meta: {
          label: "Invoice ID",
          placeholder: "Search invoice ID...",
          variant: "text",
        },
      },
      {
        accessorKey: "amount",
        header: ({ column }) => (
          <DataTableColumnHeader column={column} title="Amount" />
        ),
      },
    ],
    [],
  );
}

Controlled Pagination (Recommended for API integrations)

When fetching data from an external API, it's highly recommended to control the pagination state externally.

function InvoiceTable() {
  const [page, setPage] = useState(1);
  const [limit, setLimit] = useState(10);

  // Fetch data from your API utilizing the page & limit variables
  const { data, meta } = useQuery({
    queryKey: ["invoices", page, limit],
    queryFn: () => fetchInvoices({ page, limit }),
  });

  const columns = useInvoiceColumns();

  const { table, filterValues } = useDataTable({
    columns,
    data: data?.data ?? [],
    getRowId: (row) => row.invoice_id,
    pageCount: meta?.total_pages ?? 0,
    // Controlled pagination props
    page,
    perPage: limit,
    onPageChange: setPage,
    onPerPageChange: (newLimit) => {
      setLimit(newLimit);
      setPage(1); // Reset to the first page when the limit changes
    },
  });

  return <DataTable table={table} />;
}

Uncontrolled Pagination

If you don't provide page, perPage, or onPageChange, the hook will manage the state internally.

const { table, filterValues, page, perPage } = useDataTable({
  columns,
  data,
  pageCount,
  // Internal state management is active since no controlled props are passed
});

Column filtering is enabled by setting enableColumnFilter: true in your column definitions. The filterValues returned by the hook contains the active filter key-value pairs that can be sent directly to your API:

const { table, filterValues } = useDataTable({ ... });

// filterValues contains: { invoice_id: 'INV-001', status: ['paid', 'pending'] }
// Utilize this object as API query parameters
useEffect(() => {
  refetch({ ...filterValues });
}, [filterValues]);

Props

The useDataTable hook accepts the following properties.

Prop

Type

Returns

The useDataTable hook returns an object with the following properties.

Prop

Type

Column Meta for Filter Variant

Utilize the meta property in your column definitions to configure the UI representation of the filter:

meta: {
  label: 'Status',
  variant: 'select',    // Accepts: 'text' | 'select' | 'multiSelect' | 'date' | 'range' | 'boolean'
  options: [
    { label: 'Paid', value: 'paid' },
    { label: 'Pending', value: 'pending' },
  ],
}

Loading State (DataTableSkeleton)

DataTableSkeleton is used to display a loading skeleton that strictly matches the actual layout of the data table. This is extremely useful when combined with React.Suspense or when awaiting data from an API.

Skeleton Usage

import { DataTableSkeleton } from "komdes";

function MyTableSkeleton() {
  return (
    <DataTableSkeleton
      columnCount={7}
      rowCount={10}
      filterCount={2}
      shrinkZero
    />
  );
}

Suspense Integration

The recommended pattern when using frameworks like Next.js or React Router v7 with asynchronous data fetching:

import { Suspense } from "react";
import { DataTableSkeleton } from "komdes";

function Page() {
  return (
    <div className="p-6">
      <Suspense fallback={<DataTableSkeleton columnCount={5} rowCount={10} />}>
        <MyDataTableContainer />
      </Suspense>
    </div>
  );
}

Skeleton Props

Prop	Type	Default	Description
`columnCount`	`number`	—	Required. The number of columns the skeleton should render.
`rowCount`	`number`	`10`	The number of row skeletons to display.
`filterCount`	`number`	`0`	The number of filter skeleton boxes to display in the top toolbar.
`cellWidths`	`string[]`	`['auto']`	An array of column widths (e.g., `['100px', '200px']`).
`withViewOptions`	`boolean`	`true`	Whether to render the skeleton for the column visibility toggle button.
`withPagination`	`boolean`	`true`	Whether to render the skeleton for the bottom pagination controls.
`shrinkZero`	`boolean`	`false`	If `true`, columns will possess a `min-width` matching their respective `cellWidths`.
`className`	`string`	—	Custom CSS class for the main container.

				Status	Role	Created At
citlalli_spinka	Citlalli Spinka	citlalli29@hotmail.com	+18176914076	inactive	superadmin	22 Jan 2024
taurean_stark	Taurean Stark	taurean_turner72@gmail.com	+14237063140	inactive	admin	09 Nov 2024
efrain_schuster50	Efrain Schuster	efrain_paucek81@gmail.com	+13952948130	active	admin	24 May 2024
jill.mosciski	Jill Mosciski	jill65@yahoo.com	+17002257703	active	cashier	06 Nov 2024
unique.bayer41	Unique Bayer	unique68@yahoo.com	+14203368951	active	cashier	04 May 2024
maryann.lubowitz44	Maryann Lubowitz	maryann37@hotmail.com	+15015139631	inactive	admin	17 Sep 2024
christopher.runolfsson	Christopher Runolfsson	christopher1@hotmail.com	+12688106049	active	admin	14 Jun 2024
eda_lebsack	Eda Lebsack	eda_little@hotmail.com	+12618535627	invited	admin	18 Mar 2024
eleanor_kerluke58	Eleanor Kerluke	eleanor_gottlieb@hotmail.com	+18013288238	active	cashier	14 Sep 2024
vince_fritsch98	Vince Fritsch	vince.corwin18@yahoo.com	+18055136159	active	admin	06 Sep 2024

				Status	Role	Created At
citlalli_spinka	Citlalli Spinka	citlalli29@hotmail.com	+18176914076	inactive	superadmin	22 Jan 2024
taurean_stark	Taurean Stark	taurean_turner72@gmail.com	+14237063140	inactive	admin	09 Nov 2024
efrain_schuster50	Efrain Schuster	efrain_paucek81@gmail.com	+13952948130	active	admin	24 May 2024
jill.mosciski	Jill Mosciski	jill65@yahoo.com	+17002257703	active	cashier	06 Nov 2024
unique.bayer41	Unique Bayer	unique68@yahoo.com	+14203368951	active	cashier	04 May 2024
maryann.lubowitz44	Maryann Lubowitz	maryann37@hotmail.com	+15015139631	inactive	admin	17 Sep 2024
christopher.runolfsson	Christopher Runolfsson	christopher1@hotmail.com	+12688106049	active	admin	14 Jun 2024
eda_lebsack	Eda Lebsack	eda_little@hotmail.com	+12618535627	invited	admin	18 Mar 2024
eleanor_kerluke58	Eleanor Kerluke	eleanor_gottlieb@hotmail.com	+18013288238	active	cashier	14 Sep 2024
vince_fritsch98	Vince Fritsch	vince.corwin18@yahoo.com	+18055136159	active	admin	06 Sep 2024