React Tailwind Grid Table (@ohryzon/react-tablez)

A lightweight, feature-rich, and highly customizable React Data Grid/Table component. Built for React 19 and Tailwind CSS v4, this component is designed with speed, responsiveness, type safety, and premium aesthetics in mind.

---

✨ Features

• ⚡ Lightweight & Fast: Designed with minimal footprint and optimized with React memoization (useMemo) to handle thousands of rows with no performance lag.
• ↕️ Smart Sorting: Natural alphanumeric and date-based sorting out of the box, with support for custom sort comparators.
• 🔍 Multi-Level Filtering: Features global text search filtering and column-specific inputs.
• 📄 Pagination: Highly configurable pagination controls supporting customizable page sizes, bounds, and ellipses.
• 📱 Responsive Layout: Adapts gracefully to smaller screens by optionally rendering rows as elegant mobile cards.
• 🌓 Dark & Light Modes: Native support for dark/light themes, with options to sync with system preferences (auto) or force a specific mode.
• 🛠️ Flexible Column API: Render nested JSON paths (e.g. user.profile.name) and write custom cell renderers for badges, actions, or interactive elements.
• 🔄 Dual State Model: Use uncontrolled mode for immediate setup (internal state) or controlled mode for server-side sorting, searching, and paging.
• 🎨 Tailwind Customization: Easily pass tailwind override classes to headers, cells, wrappers, or buttons via the classNames property.

---

📦 Installation

Install via npm, yarn, or pnpm:

# npm
npm install @ohryzon/react-tablez

# yarn
yarn add @ohryzon/react-tablez

# pnpm
pnpm add @ohryzon/react-tablez

---

🚀 Quick Start

Define your columns and data array, and mount the component:

import { Table, Column } from '@ohryzon/react-tablez';

interface User {
  id: number;
  name: string;
  role: string;
  status: string;
}

const columns: Column<User>[] = [
  { key: 'name', header: 'Name', sortable: true, filterable: true },
  { key: 'role', header: 'Role', sortable: true },
  { 
    key: 'status', 
    header: 'Status', 
    render: (val) => (
      <span className={val === 'Active' ? 'text-green-500' : 'text-gray-500'}>
        ● {val}
      </span>
    )
  }
];

const data: User[] = [
  { id: 1, name: 'Alice Smith', role: 'Developer', status: 'Active' },
  { id: 2, name: 'Bob Johnson', role: 'Designer', status: 'Inactive' }
];

export default function Dashboard() {
  return (
    <Table<User>
      data={data}
      columns={columns}
      pagination={true}
      defaultPageSize={5}
    />
  );
}

---

🛠️ Advanced Integration

Below is an example showcasing advanced capabilities like nested JSON path keys, row actions, and theme toggle selectors:

import React, { useState } from 'react';
import { Table, Column, RowAction } from '@ohryzon/react-tablez';

interface Employee {
  id: number;
  name: string;
  profile: {
    title: string;
    salary: number;
  };
  status: 'Active' | 'Inactive';
}

const columns: Column<Employee>[] = [
  { key: 'name', header: 'Employee Name', sortable: true },
  // Deep nested JSON property
  { key: 'profile.title', header: 'Position', sortable: true, filterable: true },
  { 
    key: 'profile.salary', 
    header: 'Annual Salary', 
    sortable: true, 
    dataType: 'number',
    render: (val) => `$${val.toLocaleString()}`
  },
  {
    key: 'status',
    header: 'Status',
    render: (val) => (
      <span className={`px-2.5 py-0.5 rounded-full text-xs font-semibold ${val === 'Active' ? 'bg-green-100 text-green-800' : 'bg-red-100 text-red-800'}`}>
        {val}
      </span>
    )
  }
];

export default function StaffDirectory() {
  const [staff, setStaff] = useState<Employee[]>([
    { id: 1, name: 'Sarah Connor', profile: { title: 'Engineering Lead', salary: 125000 }, status: 'Active' },
    { id: 2, name: 'John Miller', profile: { title: 'Senior Developer', salary: 98000 }, status: 'Active' }
  ]);

  const actions: RowAction<Employee>[] = [
    {
      name: 'edit',
      label: 'Edit',
      onClick: (row) => console.log('Editing row:', row)
    },
    {
      name: 'delete',
      label: 'Delete',
      onClick: (row) => setStaff((prev) => prev.filter((item) => item.id !== row.id)),
      className: 'text-red-600 hover:text-red-850'
    }
  ];

  return (
    <Table<Employee>
      data={staff}
      columns={columns}
      actions={actions}
      actionsLayout="dropdown" // Renders action choices as a dropdown menu
      theme="dark" // Supports 'light', 'dark', 'auto'
      pagination={true}
      defaultPageSize={10}
      columnFilters={true} // Column specific filter inputs
    />
  );
}

---

⚡ Server-Side Operations (Controlled State)

To manage pagination, sorting, and filtering externally (e.g. for server-side SQL queries or API pagination), pass the controlled* properties:

<Table<User>
  data={apiData}
  columns={columns}
  
  // Controlled Pagination
  controlledPagination={{
    currentPage: page,
    pageSize: pageSize,
    totalItems: totalRowsOnServer,
    onPageChange: (newPage) => setPage(newPage),
    onPageSizeChange: (newSize) => setPageSize(newSize)
  }}
  
  // Controlled Sorting
  controlledSorting={{
    sortBy: activeSortField,
    sortOrder: activeSortDirection, // 'asc' | 'desc' | null
    onSort: (field, order) => {
      setActiveSortField(field);
      setActiveSortDirection(order);
    }
  }}
  
  // Controlled Filtering
  controlledFiltering={{
    globalFilter: searchQuery,
    onGlobalFilterChange: (query) => setSearchQuery(query)
  }}
/>

---

📖 API Reference

TableProps<T>

Property	Type	Default	Description
data	T[]	Required	Array of objects representing the row data.
columns	Column<T>[]	Required	Array of column definitions.
rowKey	keyof T | ((row: T, index: number) => string | number)	undefined	Unique key for each row.
loading	boolean	false	When true, renders an animated skeleton loading state.
loadingElement	React.ReactNode	undefined	Custom React skeleton loader to override default.
emptyState	React.ReactNode	undefined	Custom element to render when the table is empty.
actions	RowAction<T>[]	undefined	Custom row operations (e.g. edit, delete actions).
actionsHeader	string	"Actions"	Custom header label for the Actions column.
actionsLayout	"inline" | "dropdown"	"inline"	Whether to display buttons next to each other or inside a menu.
theme	"light" | "dark" | "auto"	"light"	Layout palette theme. "auto" syncs with system media preference.
responsiveCards	boolean	true	When true, collapses rows into cards on screen sizes under 768px.
classNames	TableClassNames	{}	Custom Tailwind classes to override individual table tags.
pagination	boolean	true	Enable client-side pagination.
defaultPageSize	number	10	Default number of records per page.
pageSizeOptions	number[]	[5, 10, 20, 50]	Dropdown page size selections.
globalFilter	boolean	true	Enable global searching input.
columnFilters	boolean	false	Enable input fields for individual columns.

---

Column<T>

Option	Type	Default	Description
key	string	Required	Access key of the row object. Supports nested dot notation (e.g. details.address.zip).
header	React.ReactNode	Required	Header label or React node.
sortable	boolean	false	Allow sorting by clicking the header.
filterable	boolean	false	Enable text input filtering for this column.
dataType	"string" | "number" | "date" | "boolean"	"string"	Data type used for logical alphanumeric or chronological sorting.
render	(value: any, row: T, index: number) => React.ReactNode	undefined	Custom renderer callback for cells in this column.
sortType	(a: any, b: any) => number	undefined	Custom sorting comparator.
headerClassName	string	""	Custom Tailwind classes to style this header cell.
cellClassName	string	""	Custom Tailwind classes to style these cells.

---

TableClassNames

Inject custom styles into the component using the classNames option. Available selectors:

export interface TableClassNames {
  wrapper?: string;               // Main container block
  table?: string;                 // Table HTML element
  thead?: string;                 // Table head element
  th?: string;                    // Table header cell element
  tbody?: string;                 // Table body element
  trRow?: string;                 // Body row element
  td?: string;                    // Body cell element
  pagination?: string;            // Footer block wrapper
  paginationButton?: string;      // Page buttons
  globalFilterWrapper?: string;   // Search container
  globalFilterInput?: string;     // Search input text field
  columnFiltersWrapper?: string;  // Column filter row
  columnFilterInput?: string;     // Column filter input field
  actionsWrapper?: string;        // Actions block container
  actionsButton?: string;         // Actions buttons
}

---

🧱 Local Development & Scripts

Inside the project directory, you can run the following:

• Run Dev Server (for viewing the dashboard demo):

  npm run dev

• Execute Unit Test Suite (via Vitest & Testing Library):

  npm run test

• Build Demo Application:

  npm run build

• Package the Library for NPM (generates UMD/ESM files and TS declarations in dist/):

  npm run build:lib

---

🚀 Publishing to NPM

1. Compile the library assets and declaration files:

   npm run build:lib

2. Log in to your npm registry profile:

   npm login

3. Publish the compiled dist/ package (pass --access public as it is a scoped package):

   npm publish --access public

---

📄 License

Dedicated to the public domain under the Unlicense. Feel free to use, copy, modify, or distribute.