@digitaleventsupport/data-table

A powerful and customizable data table component built with React, TypeScript, TanStack Table, and Tailwind CSS.

Features ✨

• 🎯 Type-safe - Full TypeScript support
• 🔄 Sorting - Client-side and server-side sorting
• 📄 Pagination - Multiple pagination variants
• 🔍 Filtering - Column filters, search filters, and global search
• 👁️ Column Visibility - Show/hide columns
• 📌 Sticky Columns - Pin columns to left or right
• 🎨 Customizable - Built with Tailwind CSS
• 🌗 Dark Mode - Built-in dark mode support
• ⚡ Performance - Skeleton loading and optimized rendering
• 🎭 Flexible - Works with both client-side and server-side data

Installation

npm install @digitaleventsupport/data-table
# or
pnpm add @digitaleventsupport/data-table
# or
yarn add @digitaleventsupport/data-table

Prerequisites

Your project must have:

• React 18+
• Tailwind CSS 3+ configured

Setup

1. Configure Tailwind CSS

Update your tailwind.config.js:

module.exports = {
  presets: [require('@digitaleventsupport/data-table/tailwind')],
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@digitaleventsupport/data-table/dist/**/*.{js,mjs}',
  ],
}

2. Import CSS Variables (Optional)

If you don't already have these CSS variables, import them in your app:

import '@digitaleventsupport/data-table/variables.css'

Usage

Basic Example

import { DataTable, Table, useCreateTable } from '@digitaleventsupport/data-table'
import { ColumnDef } from '@tanstack/react-table'

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

const columns: ColumnDef<User>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
  },
  {
    accessorKey: 'email',
    header: 'Email',
  },
  {
    accessorKey: 'role',
    header: 'Role',
  },
]

function UsersTable() {
  const data: User[] = [
    { id: 1, name: 'John Doe', email: '[email protected]', role: 'Admin' },
    { id: 2, name: 'Jane Smith', email: '[email protected]', role: 'User' },
  ]

  const table = useCreateTable({
    data,
    columns,
  })

  return (
    <DataTable table={table}>
      <Table />
    </DataTable>
  )
}

With Pagination and Controls

import { 
  DataTable, 
  Table, 
  Pagination,
  PageSize,
  PageCount,
  ColumnVisibility,
  useCreateTable 
} from '@digitaleventsupport/data-table'

function UsersTable() {
  const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10 })

  const table = useCreateTable({
    data,
    columns,
    options: {
      pagination: {
        state: pagination,
        onChange: setPagination,
      },
    },
  })

  return (
    <DataTable table={table}>
      <div className="flex items-center justify-between mb-4">
        <ColumnVisibility />
        <PageSize range={[10, 20, 50, 100]} />
      </div>
      
      <Table />
      
      <div className="flex items-center justify-between mt-4">
        <PageCount />
        <Pagination variant="simple" />
      </div>
    </DataTable>
  )
}

With Filters

import { 
  DataTable, 
  Table,
  GlobalSearchFilter,
  ColumnFilters,
  ClearFilters,
  useCreateTable 
} from '@digitaleventsupport/data-table'

function UsersTable() {
  const [columnFilters, setColumnFilters] = useState([])
  const [globalFilter, setGlobalFilter] = useState('')

  const table = useCreateTable({
    data,
    columns,
    options: {
      columnFilters: {
        state: columnFilters,
        onChange: setColumnFilters,
      },
      globalFiltering: {
        state: globalFilter,
        onChange: setGlobalFilter,
      },
    },
  })

  return (
    <DataTable table={table}>
      <div className="flex gap-2 mb-4">
        <GlobalSearchFilter placeholder="Search..." debounce={300} />
        <ColumnFilters />
        <ClearFilters />
      </div>
      
      <Table />
    </DataTable>
  )
}

Server-Side Data

function UsersTable() {
  const [sorting, setSorting] = useState([])
  const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 10 })

  const { data, isLoading, isFetching } = useQuery({
    queryKey: ['users', sorting, pagination],
    queryFn: () => fetchUsers({ sorting, pagination }),
  })

  const table = useCreateTable({
    data: data?.users ?? [],
    columns,
    options: {
      sorting: {
        manualSorting: true,
        state: sorting,
        onChange: setSorting,
      },
      pagination: {
        manualPagination: true,
        state: pagination,
        onChange: setPagination,
        rowCount: data?.totalCount ?? 0,
      },
      isLoading,
      isFetching,
    },
  })

  return (
    <DataTable table={table}>
      <Table />
      <Pagination variant="full" />
    </DataTable>
  )
}

Components

Core Components

• DataTable - Provider component that wraps all table-related components
• Table - The main table component with sorting, filtering, and sticky columns support

Control Components

• ColumnVisibility - Toggle column visibility
• PageCount - Display current page info
• PageSize - Select rows per page
• Pagination - Navigate pages (variants: minimal, icons, simple, full)

Filter Components

• GlobalSearchFilter - Search across all columns
• ColumnFilters - Multi-select column filters
• ColumnSearchFilter - Individual column search (auto-rendered in headers)
• ClearFilters - Clear all active filters

Hooks

• useCreateTable - Create a TanStack Table instance
• useTable - Access table context
• useSerializedColumnFilters - Serialize filters for API calls

Column Configuration

import { ColumnDef } from '@tanstack/react-table'

const columns: ColumnDef<User>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
    enableSorting: true,
    enableHiding: true,
    enableGlobalFilter: true, // Enable for global search
    meta: {
      label: 'Full Name', // Display name
      columnFilter: [
        {
          type: 'search', // Add search filter in header
        },
      ],
    },
  },
  {
    accessorKey: 'status',
    header: 'Status',
    meta: {
      label: 'Status',
      columnFilter: [
        {
          type: 'multi-select',
          icon: CheckCircle,
          values: [
            { label: 'Active', value: 'active' },
            { label: 'Inactive', value: 'inactive' },
          ],
        },
      ],
    },
  },
]

API Reference

Full API documentation with examples is available in the source code JSDoc comments.

TypeScript

This package is written in TypeScript and provides full type safety:

import type { TableContext, ColumnDefFilter } from '@digitaleventsupport/data-table'

Styling

The package uses Tailwind CSS and CSS variables for theming. You can override the default theme by defining your own CSS variables:

:root {
  --border: 220 13% 91%;
  --radius: 0.75rem;
  /* ... other variables */
}

License

MIT

Contributing

Contributions are welcome! This package is built with best practices in mind and follows TypeScript and React conventions.