@darksnow-ui/data-table

Advanced data table component built on top of TanStack Table v8 with built-in features like sorting, filtering, pagination, row selection, and more.

Features

• 🎯 Built on TanStack Table v8 - Powerful and flexible
• 🔍 Global & Column Filtering - Search across all data or specific columns
• 📊 Sorting - Multi-column sorting with indicators
• 📄 Pagination - Built-in pagination with customizable page sizes
• ✅ Row Selection - Single or multi-row selection
• 👁️ Column Visibility - Show/hide columns dynamically
• 📏 Density Options - Compact, normal, or comfortable spacing
• 📤 Export - Export data as CSV or JSON
• 🎨 Fully Themed - Uses DarkSnow UI design system
• 📱 Responsive - Works on all screen sizes
• 🌍 i18n Ready - Customizable locale strings
• ⚡ Performance - Virtualization ready
• 🔧 Highly Customizable - Every aspect can be customized

Installation

npm install @darksnow-ui/data-table @tanstack/react-table
# or
yarn add @darksnow-ui/data-table @tanstack/react-table
# or
pnpm add @darksnow-ui/data-table @tanstack/react-table

Dependencies

Peer Dependencies (you need to install these):

• react (^18.0.0 || ^19.0.0)
• react-dom (^18.0.0 || ^19.0.0)
• @tanstack/react-table (^8.20.5)

Bundled Dependencies (included):

• clsx - For className merging (tiny ~0.5KB)
• lucide-react - For icons

Basic Usage

import { DataTable, DataTableColumn } from '@darksnow-ui/data-table'

interface User {
  id: string
  name: string
  email: string
  role: string
  status: 'active' | 'inactive'
}

const columns: DataTableColumn<User>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
  },
  {
    accessorKey: 'email',
    header: 'Email',
  },
  {
    accessorKey: 'role',
    header: 'Role',
  },
  {
    accessorKey: 'status',
    header: 'Status',
    cell: ({ row }) => (
      <span className={row.getValue('status') === 'active' ? 'text-green-500' : 'text-red-500'}>
        {row.getValue('status')}
      </span>
    ),
  },
]

const data: User[] = [
  { id: '1', name: 'John Doe', email: '[email protected]', role: 'Admin', status: 'active' },
  { id: '2', name: 'Jane Smith', email: '[email protected]', role: 'User', status: 'active' },
  // ... more data
]

function UsersTable() {
  return (
    <DataTable
      data={data}
      columns={columns}
      enableRowSelection
      enableExport
    />
  )
}

Advanced Example with All Features

import { 
  DataTable, 
  DataTableColumn,
  useSelectableColumns,
  useActionColumn,
  useFormattedColumns 
} from '@darksnow-ui/data-table'
import { Edit, Trash, MoreHorizontal } from 'lucide-react'

interface Product {
  id: string
  name: string
  category: string
  price: number
  stock: number
  createdAt: string
}

function ProductsTable() {
  const [data, setData] = useState<Product[]>(products)
  
  // Create selectable columns
  const selectColumns = useSelectableColumns<Product>()
  
  // Create formatted columns
  const dataColumns = useFormattedColumns<Product>([
    { key: 'name', header: 'Product Name' },
    { key: 'category', header: 'Category' },
    { key: 'price', header: 'Price', type: 'currency' },
    { key: 'stock', header: 'Stock', type: 'number' },
    { key: 'createdAt', header: 'Created', type: 'date' },
  ])
  
  // Create action column
  const actionColumn = useActionColumn<Product>([
    {
      label: 'Edit',
      icon: <Edit className="h-4 w-4" />,
      onClick: (row) => console.log('Edit', row),
    },
    {
      label: 'Delete',
      icon: <Trash className="h-4 w-4" />,
      onClick: (row) => console.log('Delete', row),
    },
  ])
  
  const columns: DataTableColumn<Product>[] = [
    ...selectColumns,
    ...dataColumns,
    actionColumn,
  ]
  
  return (
    <DataTable
      data={data}
      columns={columns}
      
      // Features
      enableSorting
      enableFiltering
      enableColumnFilters
      enableGlobalFilter
      enablePagination
      enableRowSelection
      enableColumnVisibility
      enableDensity
      enableExport
      
      // Pagination
      pageSize={20}
      pageSizeOptions={[10, 20, 50, 100]}
      
      // Callbacks
      onRowClick={(row) => console.log('Row clicked:', row)}
      onSelectionChange={(selected) => console.log('Selected:', selected)}
      
      // Visual
      striped
      hoverable
      stickyHeader
      
      // Custom toolbar actions
      toolbarActions={
        <button className="btn-primary">
          Add Product
        </button>
      }
      
      // Custom empty state
      emptyMessage="No products found"
      
      // Internationalization
      locale={{
        search: 'Buscar...',
        columns: 'Colunas',
        // ... other translations
      }}
    />
  )
}

Using Hooks

useDataTableState

Manage loading and error states:

import { useDataTableState } from '@darksnow-ui/data-table'

function MyTable() {
  const { data, loading, error, fetchData } = useDataTableState<User>()
  
  useEffect(() => {
    fetchData(async () => {
      const response = await fetch('/api/users')
      return response.json()
    })
  }, [fetchData])
  
  return (
    <DataTable
      data={data}
      columns={columns}
      loading={loading}
    />
  )
}

useFormattedColumns

Automatically format common data types:

const columns = useFormattedColumns<Order>([
  { key: 'id', header: 'Order ID' },
  { key: 'customer', header: 'Customer' },
  { key: 'total', header: 'Total', type: 'currency' },
  { key: 'createdAt', header: 'Date', type: 'date' },
  { key: 'isPaid', header: 'Paid', type: 'boolean' },
  {
    key: 'status',
    header: 'Status',
    format: (value) => value.toUpperCase(),
  },
])

Custom Column Definitions

const columns: DataTableColumn<User>[] = [
  {
    accessorKey: 'name',
    header: 'Name',
    // Enable column-specific features
    sortable: true,
    filterable: true,
    exportable: true,
  },
  {
    accessorKey: 'email',
    header: ({ column }) => (
      <button
        onClick={() => column.toggleSorting(column.getIsSorted() === 'asc')}
        className="flex items-center gap-1"
      >
        Email
        <ArrowUpDown className="h-4 w-4" />
      </button>
    ),
  },
  {
    id: 'actions',
    cell: ({ row }) => (
      <DropdownMenu>
        <DropdownMenuTrigger>
          <MoreHorizontal className="h-4 w-4" />
        </DropdownMenuTrigger>
        <DropdownMenuContent>
          <DropdownMenuItem>Edit</DropdownMenuItem>
          <DropdownMenuItem>Delete</DropdownMenuItem>
        </DropdownMenuContent>
      </DropdownMenu>
    ),
  },
]

Theming

The DataTable uses DarkSnow UI theme tokens:

• theme-bg-* - Background colors
• theme-mark-* - Border colors
• theme-content-* - Text colors
• theme-accent - Accent color for focus states

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | TData[] | required | Array of data to display | | columns | DataTableColumn<TData>[] | required | Column definitions | | enableSorting | boolean | true | Enable column sorting | | enableFiltering | boolean | true | Enable filtering features | | enablePagination | boolean | true | Enable pagination | | enableRowSelection | boolean | false | Enable row selection | | enableExport | boolean | false | Enable export features | | pageSize | number | 10 | Default page size | | onRowClick | (row: TData) => void | - | Row click handler | | loading | boolean | false | Show loading state | | locale | DataTableLocale | English | Internationalization |

License

MIT © DarkSnow UI