@metadiv-studio/table

A powerful, feature-rich React table component built with TypeScript and Tailwind CSS. This package provides a comprehensive table solution with built-in support for sorting, pagination, row selection, search functionality, and custom rendering.

📦 Installation

npm i @metadiv-studio/table

🚀 Features

• TypeScript Support - Fully typed with comprehensive interfaces
• Responsive Design - Built with Tailwind CSS for modern, responsive layouts
• Row Selection - Built-in checkbox selection with customizable selection keys
• Sorting - Column-based sorting with visual indicators
• Pagination - Integrated pagination with customizable page sizes
• Search - Built-in search functionality with expandable search input
• Loading States - Skeleton loading with shimmer effects
• Custom Rendering - Flexible cell rendering for complex data display
• Dark Mode Support - Built-in dark mode compatibility
• Accessibility - ARIA-compliant table structure

🎯 Basic Usage

import Table from '@metadiv-studio/table';
import type { TableColumn } from '@metadiv-studio/table';

// Define your data structure
interface User {
  id: number;
  name: string;
  email: string;
  role: string;
  status: string;
}

// Define table columns
const columns: TableColumn<User>[] = [
  { title: "ID", dataIndex: "id", width: "80px", align: "center" },
  { title: "Name", dataIndex: "name", width: "150px" },
  { title: "Email", dataIndex: "email", width: "200px" },
  { title: "Role", dataIndex: "role", width: "120px" },
  { title: "Status", dataIndex: "status", width: "100px" },
];

// Your data
const users: User[] = [
  { id: 1, name: "John Doe", email: "[email protected]", role: "Admin", status: "Active" },
  { id: 2, name: "Jane Smith", email: "[email protected]", role: "User", status: "Inactive" },
];

// Render the table
function UserTable() {
  return (
    <Table
      columns={columns}
      dataSource={users}
      minWidth="800px"
    />
  );
}

🔧 Advanced Features

1. Custom Cell Rendering

Customize how specific columns are displayed using the render function:

import { Badge } from '@metadiv-studio/button';

const columns: TableColumn<User>[] = [
  { title: "ID", dataIndex: "id", width: "80px", align: "center" },
  { title: "Name", dataIndex: "name", width: "150px" },
  {
    title: "Status",
    dataIndex: "status",
    width: "100px",
    render: (value: string) => (
      <Badge
        className={
          value === "Active" 
            ? "bg-green-100 text-green-800 dark:bg-green-900 dark:text-green-200" 
            : "bg-red-100 text-red-800 dark:bg-red-900 dark:text-red-200"
        }
      >
        {value}
      </Badge>
    )
  },
  {
    title: "Price",
    dataIndex: "price",
    width: "100px",
    align: "right",
    render: (value: number) => `$${value.toFixed(2)}`
  },
];

2. Row Selection

Enable row selection with checkboxes:

function SelectableUserTable() {
  const [selectedKeys, setSelectedKeys] = useState<number[]>([]);

  return (
    <Table
      columns={columns}
      dataSource={users}
      selectKey="id"
      selectedKeys={selectedKeys}
      onSelect={setSelectedKeys}
      minWidth="800px"
    />
  );
}

3. Sorting

Add sorting functionality to specific columns:

function SortableUserTable() {
  const [currentSortKey, setCurrentSortKey] = useState<string>('');
  
  const handleSort = (sortKey: string, asc: boolean) => {
    setCurrentSortKey(sortKey);
    // Implement your sorting logic here
    console.log(`Sorting by ${sortKey}, ascending: ${asc}`);
  };

  const sortableColumns: TableColumn<User>[] = [
    { title: "ID", dataIndex: "id", width: "80px", align: "center" },
    { title: "Name", dataIndex: "name", width: "150px", sortKey: "name" },
    { title: "Email", dataIndex: "email", width: "200px", sortKey: "email" },
    { title: "Role", dataIndex: "role", width: "120px", sortKey: "role" },
    { title: "Status", dataIndex: "status", width: "100px" },
  ];

  return (
    <Table
      columns={sortableColumns}
      dataSource={users}
      currentSortKey={currentSortKey}
      onSortChange={handleSort}
      minWidth="800px"
    />
  );
}

4. Pagination

Add pagination controls:

function PaginatedUserTable() {
  const [currentPage, setCurrentPage] = useState(1);
  const totalPages = 20;
  const totalRecords = 100000;

  return (
    <Table
      title="User Management"
      columns={columns}
      dataSource={users}
      currentPage={currentPage}
      totalPages={totalPages}
      totalRecords={totalRecords}
      onPageChange={setCurrentPage}
      minWidth="800px"
    />
  );
}

5. Search Functionality

Enable search with an expandable search input:

function SearchableUserTable() {
  const handleSearch = (searchTerm: string) => {
    // Implement your search logic here
    console.log('Searching for:', searchTerm);
  };

  return (
    <Table
      title="User Management"
      columns={columns}
      dataSource={users}
      onSearch={handleSearch}
      minWidth="800px"
    />
  );
}

6. Loading States

Show loading skeletons while data is being fetched:

function LoadingUserTable() {
  const [loading, setLoading] = useState(false);

  return (
    <Table
      columns={columns}
      dataSource={users}
      loading={loading}
      minWidth="800px"
    />
  );
}

7. Combined Features

Use all features together for a comprehensive table:

function ComprehensiveUserTable() {
  const [currentPage, setCurrentPage] = useState(1);
  const [selectedKeys, setSelectedKeys] = useState<number[]>([]);
  const [currentSortKey, setCurrentSortKey] = useState<string>('');
  const [loading, setLoading] = useState(false);

  const handleSort = (sortKey: string, asc: boolean) => {
    setCurrentSortKey(sortKey);
    // Implement sorting logic
  };

  const handleSearch = (searchTerm: string) => {
    // Implement search logic
  };

  return (
    <Table
      title="User Management System"
      columns={columns}
      dataSource={users}
      loading={loading}
      minWidth="800px"
      selectKey="id"
      selectedKeys={selectedKeys}
      onSelect={setSelectedKeys}
      currentPage={currentPage}
      totalPages={20}
      totalRecords={100000}
      onPageChange={setCurrentPage}
      currentSortKey={currentSortKey}
      onSortChange={handleSort}
      onSearch={handleSearch}
    />
  );
}

📋 API Reference

Table Props

| Prop | Type | Description | |------|------|-------------| | columns | TableColumn<T>[] | Array of column definitions | | dataSource | T[] | Array of data objects | | title | React.ReactNode | Optional table title | | loading | boolean | Show loading skeleton state | | minWidth | string \| number | Minimum table width | | selectKey | string | Key for row selection (default: 'id') | | selectedKeys | any[] | Array of selected row keys | | onSelect | (keys: any[]) => void | Selection change handler | | currentPage | number | Current page number | | totalPages | number | Total number of pages | | totalRecords | number | Total number of records | | onPageChange | (page: number) => void | Page change handler | | currentSortKey | string | Currently sorted column key | | onSortChange | (key: string, asc: boolean) => void | Sort change handler | | onSearch | (term: string) => void | Search input handler |

TableColumn Interface

interface TableColumn<T> {
  title: React.ReactNode;           // Column header
  dataIndex: string;                // Data property key
  sortKey?: string;                 // Optional sort key
  width?: string;                   // Column width
  align?: 'left' | 'center' | 'right'; // Text alignment
  render?: (value: any, record: T, index: number) => React.ReactNode; // Custom renderer
}

🎨 Styling

The table uses Tailwind CSS classes and supports dark mode out of the box. For custom styling, you can:

1. Override Tailwind classes using the className prop on individual components
2. Use CSS custom properties for theme-specific styling
3. Extend the component with additional styling props

🌙 Dark Mode

Dark mode is automatically supported and follows your application's theme. The table will automatically adjust colors based on the dark class on the html element.

📱 Responsive Design

The table is built with responsive design principles:

• Horizontal scrolling for small screens
• Flexible column widths
• Mobile-friendly touch interactions
• Responsive pagination controls

🔧 Customization

Custom Pagination Component

You can replace the built-in pagination with your own component by not providing the onPageChange prop.

Custom Loading States

The loading state shows skeleton rows, but you can customize this by implementing your own loading logic.

Custom Search UI

The search input can be customized by modifying the search button and input styling through CSS overrides.

📦 Dependencies

This package has the following peer dependencies:

• react ^18
• react-dom ^18

And includes these internal dependencies:

• @metadiv-studio/button - For action buttons
• @metadiv-studio/input - For search input
• @radix-ui/react-checkbox - For row selection checkboxes
• @radix-ui/react-icons - For various icons
• lucide-react - For additional icons

🚀 Getting Started

1. Install the package:

   npm i @metadiv-studio/table

2. Import and use:

   import Table from '@metadiv-studio/table';
   import type { TableColumn } from '@metadiv-studio/table';

3. Define your data and columns:

   const columns: TableColumn<YourType>[] = [
     { title: "Name", dataIndex: "name" },
     { title: "Email", dataIndex: "email" },
   ];

4. Render the table:

   <Table
     columns={columns}
     dataSource={yourData}
     minWidth="800px"
   />

🤝 Contributing

This package is part of the @metadiv-studio ecosystem. For issues, feature requests, or contributions, please refer to the project repository.

📄 License

This package is licensed under the UNLICENSED license.