nextjs-reusable-table

A production-ready, highly customizable and reusable table component for Next.js applications. Built with TypeScript, optimized for performance, and designed with developer experience in mind.

Documentation

File	Description
API.md	Complete prop reference, types, and utility functions
EXAMPLES.md	Real-world usage patterns and recipes
TROUBLESHOOTING.md	Common issues, fixes, and FAQ
CONTRIBUTING.md	How to contribute
CHANGELOG.md	Version history
SECURITY.md	Supported versions and vulnerability reporting

AI Tooling

File	Description
llms.txt	AI-discovery index (llms.txt standard)
llms-full.txt	Complete inlined reference for AI context windows
skills/nextjs-reusable-table/SKILL.md	Installable skill for Cursor, Claude Code, and agentskills-compatible editors
AGENTS.md	AI agent contribution guide
.cursor/rules/	Cursor IDE rules (auto-attached per file type)

Key Features

• Zero Configuration — works out of the box
• Smart Data Handling — auto-formats dates, URLs, arrays
• Built-in Search & Filtering — no extra setup needed
• Fully Responsive — mobile-first design
• Accessible — screen reader friendly with ARIA support
• Dark Mode — automatic system preference detection
• High Performance — optimized renders, ~39KB minified (~12KB gzipped)
• Truly Headless — customize every style, behavior, and interaction via disableDefaultStyles + customClassNames
• CSS Isolated — all styles scoped under @layer rtbl with rtbl- prefix, zero global style leaking

Installation

npm install nextjs-reusable-table
# or
yarn add nextjs-reusable-table
# or
pnpm add nextjs-reusable-table

Prerequisites

Requirement	Version
Next.js	13+ (App Router and Pages Router supported)
React	18+
React DOM	18+
Tailwind CSS	3+ or 4+
TypeScript	4.5+ (recommended)

Note: All components use the "use client" directive. For SSR contexts, wrap in a client component or use dynamic(() => import(...), { ssr: false }).

Quick Start

"use client";
import { TableComponent } from "nextjs-reusable-table";
import "nextjs-reusable-table/dist/index.css";

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

const users: User[] = [
  { id: 1, name: "Alice Johnson", email: "alice@example.com" },
  { id: 2, name: "Bob Smith", email: "bob@example.com" },
];

export default function UsersTable() {
  return (
    <TableComponent<User>
      columns={["ID", "Name", "Email"]}
      data={users}
      props={["id", "name", "email"]}
    />
  );
}

With Search and Pagination

"use client";
import { useState } from "react";
import { TableComponent } from "nextjs-reusable-table";
import "nextjs-reusable-table/dist/index.css";

export default function SearchableTable() {
  const [search, setSearch] = useState("");
  const [page, setPage] = useState(1);

  return (
    <div className="space-y-4">
      <input
        type="text"
        placeholder="Search..."
        value={search}
        onChange={(e) => setSearch(e.target.value)}
        className="w-full p-2 border rounded-md"
      />
      <TableComponent<User>
        columns={["ID", "Name", "Email"]}
        data={users}
        props={["id", "name", "email"]}
        searchValue={search}
        enablePagination
        page={page}
        setPage={setPage}
        itemsPerPage={10}
      />
    </div>
  );
}

Tailwind Setup

Tailwind v3 — add to content in tailwind.config.js:

content: [
  "./src/**/*.{js,ts,jsx,tsx}",
  "./node_modules/nextjs-reusable-table/dist/**/*.{js,mjs}",
]

Tailwind v4 — add to your CSS:

@import "tailwindcss";
@source "../node_modules/nextjs-reusable-table/dist";

Features

Smart Data Handling

• Dates automatically formatted using Intl.DateTimeFormat
• Arrays displayed as chips with "+X more" expand button
• URLs detected and rendered as <Link> elements

Column Management

• Sort by specifying sortableProps and providing an onSort handler
• Hide/show columns via per-header dropdown (showRemoveColumns={true})

Action Dropdowns

<TableComponent
  actions
  actionTexts={["Edit", "Delete"]}
  actionFunctions={[
    (item) => handleEdit(item),
    (item) => handleDelete(item),
  ]}
/>

Custom Cell Rendering

<TableComponent<User>
  formatValue={(value, prop, item) => {
    if (prop === "status")
      return <span className={item.active ? "text-green-600" : "text-red-500"}>{value}</span>;
    return value;
  }}
/>

Headless Mode

<TableComponent
  disableDefaultStyles
  customClassNames={{
    container: "border rounded-xl overflow-hidden",
    table: "w-full text-sm",
    thead: "bg-slate-100",
    th: "px-4 py-3 font-semibold text-left",
    tr: "border-b hover:bg-slate-50",
    td: "px-4 py-3",
  }}
/>

For all prop options, see API.md. For more examples, see EXAMPLES.md.

Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

License

ISC — see LICENSE.

Acknowledgments

Inspired by common data table patterns in React and Next.js applications. Thanks to all contributors and users for their support.