@bknkit/table

A flexible and customizable table component library for React applications, providing an easy way to display, sort, and filter tabular data with elegant styling and comprehensive features.

Features

✨ Rich Feature Set

• 🔤 Sorting with visual indicators
• 📄 Built-in pagination controls
• 🎨 Multiple predefined themes and variants
• 📱 Responsive design
• 🎭 Customizable slots and styling
• 🔄 Loading and fetching states
• 📋 Empty state handling
• 🖱️ Row click handlers
• 🎯 TypeScript support

✨ Styling Options

• Multiple table variants (default, minimal, striped, bordered, compact, elegant)
• Configurable sizes (sm, md, lg)
• Striped rows, hoverable rows, bordered tables
• Custom CSS classes and styling
• Column width and alignment control

✨ Developer Experience

• Fully type-safe with TypeScript
• Hook-based state management
• Customizable components via slots
• Built with modern React patterns
• Tailwind CSS styling

Installation

npm install @bknkit/table
# or
yarn add @bknkit/table
# or
bun add @bknkit/table

CSS Import

Import the required CSS file in your application:

import '@bknkit/table/styles.css';

Quick Start

import React from 'react';
import { GenericTable, usePagination, useSorting } from '@bknkit/table';
import '@bknkit/table/styles.css';

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

const users: User[] = [
  { id: '1', name: 'John Doe', email: '[email protected]', role: 'Admin' },
  { id: '2', name: 'Jane Smith', email: '[email protected]', role: 'User' },
];

function UserTable() {
  const pagination = usePagination();
  const sorting = useSorting();

  const columns = [
    { key: 'name' as keyof User, label: 'Name', isSortable: true },
    { key: 'email' as keyof User, label: 'Email', isSortable: true },
    { key: 'role' as keyof User, label: 'Role', isSortable: true },
  ];

  return (
    <GenericTable
      data={users}
      columns={columns}
      currentPage={pagination.currentPage}
      itemsPerPage={pagination.pageSize}
      sortState={sorting.sortState}
      onSort={sorting.toggleSort}
    />
  );
}

API Reference

GenericTable Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | T[] | - | Required. Array of data objects to display | | columns | ColumnConfig<T>[] | - | Required. Column configuration array | | currentPage | number | - | Required. Current page number | | itemsPerPage | number | - | Required. Number of items per page | | sortState | SortState | - | Required. Current sorting state | | onSort | (column: string) => void | - | Required. Sort handler function | | showNumbers | boolean | true | Show row numbers | | loading | boolean | false | Initial loading state | | fetching | boolean | false | Data fetching state | | onRefetch | () => void | - | Refetch handler | | title | string | - | Table title | | variant | TableVariant | "default" | Table style variant | | size | TableSize | "md" | Table size | | striped | boolean | false | Enable striped rows | | hoverable | boolean | true | Enable row hover effects | | bordered | boolean | false | Enable table borders | | compact | boolean | false | Enable compact spacing | | rowClick | (item: T, index: number) => void | - | Row click handler |

Column Configuration

interface ColumnConfig<T> {
  key: keyof T | "actions";
  label: string;
  isSortable?: boolean;
  render?: (item: T) => React.ReactNode;
  width?: string | number;
  align?: "left" | "center" | "right";
  className?: string;
  headerClassName?: string;
}

Hooks

usePagination

const pagination = usePagination({
  initialPage?: number;
  initialPageSize?: number;
  pageSizeOptions?: number[];
});

Returns:

• currentPage: number
• pageSize: number
• totalItems: number
• totalPages: number
• offset: number
• limit: number
• actions.setCurrentPage(page: number)
• actions.setPageSize(size: number)
• actions.setTotalItems(total: number)

useSorting

const sorting = useSorting();

Returns:

• sortState: SortState
• toggleSort(column: string)
• getSortParams() - for API integration

Advanced Examples

Custom Cell Rendering

const columns = [
  {
    key: 'status',
    label: 'Status',
    render: (user) => (
      <Badge severity={user.status === 'active' ? 'success' : 'error'}>
        {user.status}
      </Badge>
    )
  },
  {
    key: 'actions',
    label: 'Actions',
    render: (user) => (
      <div className="flex gap-2">
        <Button size="sm" onClick={() => editUser(user.id)}>
          Edit
        </Button>
        <Button size="sm" variant="outline" onClick={() => viewUser(user.id)}>
          View
        </Button>
      </div>
    )
  }
];

Table Variants

// Different table styles
<GenericTable variant="minimal" {...props} />
<GenericTable variant="striped" {...props} />
<GenericTable variant="bordered" {...props} />
<GenericTable variant="compact" {...props} />
<GenericTable variant="elegant" {...props} />

// Different sizes
<GenericTable size="sm" {...props} />
<GenericTable size="md" {...props} />
<GenericTable size="lg" {...props} />

Loading States

<GenericTable
  data={users}
  columns={columns}
  loading={isInitialLoad}
  fetching={isRefetching}
  onRefetch={refetchData}
  {...otherProps}
/>

Custom Styling

<GenericTable
  className="custom-table"
  styling={{
    container: "border rounded-lg",
    header: "bg-gray-100",
    row: "hover:bg-gray-50",
    cell: "font-medium"
  }}
  striped={true}
  hoverable={true}
  bordered={true}
  {...props}
/>

Row Click Handling

<GenericTable
  rowClick={(user, index) => {
    console.log('Clicked user:', user);
    navigate(`/users/${user.id}`);
  }}
  rowClassName={(user, index) => 
    user.status === 'inactive' ? 'opacity-50' : ''
  }
  {...props}
/>

With Pagination Controls

import { PaginationControls } from '@bknkit/table';

function TableWithPagination() {
  const pagination = usePagination();
  
  return (
    <div>
      <GenericTable
        data={displayedUsers}
        currentPage={pagination.currentPage}
        itemsPerPage={pagination.pageSize}
        {...otherProps}
      />
      
      <PaginationControls
        currentPage={pagination.currentPage}
        totalPages={pagination.totalPages}
        pageSize={pagination.pageSize}
        totalItems={pagination.totalItems}
        onPageChange={pagination.actions.setCurrentPage}
        onPageSizeChange={pagination.actions.setPageSize}
        pageSizeOptions={pagination.pageSizeOptions}
      />
    </div>
  );
}

Available Components

• GenericTable - Main table component
• PaginationControls - Pagination controls component
• Table, TableBody, TableCell, TableHead, TableHeader, TableRow - Low-level table components
• Icons: ArrowUp, ArrowDown, ArrowUpDown, PlusIcon, EditIcon, EyeIcon, RefreshCw

TypeScript Support

The library is fully typed with TypeScript. All components and hooks provide complete type safety:

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

// Full type safety for your data structure
const columns: ColumnConfig<User>[] = [
  { key: 'name', label: 'Name', isSortable: true },
  // TypeScript will ensure 'key' matches User properties
];

Theming

The library uses Tailwind CSS for styling. You can customize the appearance by:

1. Using predefined variants: default, minimal, striped, bordered, compact, elegant
2. Custom CSS classes: Pass custom classes via className and styling props
3. Tailwind configuration: Customize colors and spacing in your Tailwind config

License

MIT

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

Support

For support, please open an issue on our GitHub repository or contact the maintainers.

Built with ❤️ by @danang_tp