shadcn-custom-table-lib

A highly flexible, feature-rich, and customizable table component for React, designed for enterprise-grade data grids. Built with TanStack Table, Shadcn UI, and Lucide icons, it supports advanced filtering, sorting, pagination, custom actions, and more. Perfect for dashboards, admin panels, and data-heavy applications.

✨ Features

• TypeScript support
• Column configuration: Custom renderers, alignment, width, data types, and formatting
• Sorting: Client-side and server-side, single or multi-column
• Filtering:
  • String, number, boolean, and date filtering
  • Advanced number/date operators (equals, not equals, greater/less, between, blank, not blank)
  • Multi-select and search for string/boolean
  • Date filtering with calendar picker
• Pagination: Built-in, customizable, and supports server-side
• Row actions: View, edit, delete, and custom actions with icons and tooltips
• Row click: Optional row click handler
• Loading state: Built-in loader
• Empty state: Customizable message
• Tooltip support: For truncated or disabled content
• Accessibility: Keyboard and screen reader friendly
• Styling: Uses Shadcn UI and Tailwind for modern look

🚀 Installation

npm install shadcn-custom-table-lib

🛠️ Usage

⚠️ Styling Note

This package automatically imports its global styles (Tailwind, Shadcn, etc.) when you import any component from it. No manual CSS import is needed.

If you still do not see correct styles in your app:

• Ensure your app's build system (e.g., Next.js, Vite) allows CSS imports from node_modules.
• If using Next.js, check that your next.config.js does not block CSS from external packages.
• If you use Tailwind, make sure your Tailwind config includes the package in the content array, e.g.:

  // tailwind.config.js
  module.exports = {
    content: [
      './src/**/*.{js,ts,jsx,tsx}',
      './node_modules/shadcn-custom-table-lib/dist/**/*.{js,ts,jsx,tsx}'
    ],
    // ...
  }

If you have further issues, see the troubleshooting section below or open an issue.

import { CustomTable, BuildPaginationObject, createCommonActions } from 'shadcn-custom-table-lib';

const columns = [
  {
    header: 'Name',
    accessorKey: 'name',
    sortable: true,
    filterable: true,
    sortkey: 'name',
    align: 'left',
    width: '200px',
    dataType: 'string',
  },
  {
    header: 'Created',
    accessorKey: 'createdAt',
    sortable: true,
    filterable: true,
    sortkey: 'createdAt',
    dataType: 'date',
    width: '160px',
  },
  {
    header: 'Status',
    accessorKey: 'status',
    filterable: true,
    sortkey: 'status',
    dataType: 'boolean',
    width: '100px',
  },
  {
    header: 'ACTIONS',
    accessorKey: 'actions',
    actions: createCommonActions({
      onView: (row) => alert('View ' + row.name),
      onEdit: (row) => alert('Edit ' + row.name),
      onDelete: (row) => alert('Delete ' + row.name),
    }),
    align: 'center',
    width: '120px',
  },
];

const data = [
  { name: 'Alice', createdAt: '2024-01-01', status: true },
  { name: 'Bob', createdAt: '2024-02-15', status: false },
];

const pagination = BuildPaginationObject(
  1, // current page
  20, // total items
  10, // page size
  (page) => {}, // onPageChange
  (size) => {}, // onPageSizeChange
);

<CustomTable
  data={data}
  columns={columns}
  pagination={pagination}
  isLoading={false}
  showTooltip={true}
  onRowClick={(row) => console.log(row)}
/>

🧩 API Reference

<CustomTable />

| Prop | Type | Description | |---------------------|-------------------------------------------|------------------------------------------------------------------| | data | T[] | Table data array | | columns | TableColumn<T>[] | Column configuration array | | sortBy | string | (Optional) Current sort key | | sortOrder | 'ASC' | 'DESC' | (Optional) Sort order | | onSort | (column, order) => void | (Optional) Sort callback | | pagination | PaginationConfig | (Optional) Pagination config | | isLoading | boolean | (Optional) Show loading spinner | | border | boolean | (Optional) Show border | | showTooltip | boolean | (Optional) Show tooltips for truncated cells | | enablePagination | boolean | (Optional) Show pagination controls | | onRowClick | (row: T) => void | (Optional) Row click handler | | onFilterChange | (filters: Record<string, any>) => void | (Optional) Server-side filter callback | | initialFilters | Record<string, any> | (Optional) Initial filter values | | serverSideRender | boolean | (Optional) Enable server-side filtering/sorting |

TableColumn<T>

| Prop | Type | Description | |--------------|---------------------------------------------------|----------------------------------------------| | header | string | Column header label | | accessorKey| keyof T | Key in data objects | | sortable | boolean | Enable sorting | | filterable | boolean | Enable filtering | | sortkey | string | Sort key (for server-side) | | cell | (value, row, index) => ReactNode | (Optional) Custom cell renderer | | actions | TableAction<T>[] | (row: T) => TableAction<T>[] | (Optional) Row actions | | align | 'left' | 'center' | 'right' | (Optional) Cell alignment | | width | string | (Optional) Column width (e.g., '120px') | | dataType | 'string' | 'number' | 'date' | 'boolean' | (Optional) Data type for filtering | | format | 'id' | 'qty' | 'currency' | (Optional) Numeric formatting |

🏗️ Advanced Features

• Custom Actions: Add any number of actions per row, with icons, tooltips, and conditional logic.
• Server-side Filtering/Sorting: Use serverSideRender and onFilterChange/onSort for remote data sources.
• Custom Cell Renderers: Use the cell prop for full control over cell content.
• Date Filtering: Built-in calendar picker for date columns, with operators (equals, before, after, between, blank, not blank).
• Boolean Filtering: Multi-select true/false with checkboxes.
• Multi-Column Sorting: (If enabled in your config)
• Accessibility: Keyboard navigation, screen reader labels, and focus management.

🎨 Theming & Styling

• Uses Shadcn UI and Tailwind CSS for modern, accessible design
• Easily override styles with Tailwind classes or custom CSS

📦 Utilities

• BuildPaginationObject(page, total, limit, onPageChange, onPageSizeChange, ...) – Helper to create pagination config
• createCommonActions({ onView, onEdit, onDelete, ... }) – Quickly add standard row actions
• TruncatableCell – Utility for cells with tooltips on overflow
• TableLink – Utility for clickable links in table cells

📝 License

MIT

🙏 Credits

• TanStack Table
• Shadcn UI
• Lucide Icons

💬 Feedback & Issues

Please open an issue or PR on GitHub for bugs, feature requests, or questions!