nextjs-reusable-table
Version:
A production-ready, highly customizable and reusable table component for Next.js applications. Features include sorting, pagination, search, dark mode, TypeScript support, and zero dependencies.
219 lines (173 loc) • 6.56 kB
Markdown
[](https://www.npmjs.com/package/nextjs-reusable-table)
[](https://www.npmjs.com/package/nextjs-reusable-table)
[](https://bundlephobia.com/package/nextjs-reusable-table)
[](https://github.com/ninsau/nextjs-reusable-table/blob/main/LICENSE)
[](https://www.typescriptlang.org/)
[](#testing)
[](#installation)
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.
| File | Description |
|------|-------------|
| [API.md](API.md) | Complete prop reference, types, and utility functions |
| [EXAMPLES.md](EXAMPLES.md) | Real-world usage patterns and recipes |
| [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Common issues, fixes, and FAQ |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
| [CHANGELOG.md](CHANGELOG.md) | Version history |
| [SECURITY.md](SECURITY.md) | Supported versions and vulnerability reporting |
| File | Description |
|------|-------------|
| [llms.txt](llms.txt) | AI-discovery index (llms.txt standard) |
| [llms-full.txt](llms-full.txt) | Complete inlined reference for AI context windows |
| [skills/nextjs-reusable-table/SKILL.md](skills/nextjs-reusable-table/SKILL.md) | Installable skill for Cursor, Claude Code, and agentskills-compatible editors |
| [AGENTS.md](AGENTS.md) | AI agent contribution guide |
| [.cursor/rules/](.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
```bash
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 })`.
```tsx
"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"]}
/>
);
}
```
```tsx
"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 v3** — add to `content` in `tailwind.config.js`:
```js
content: [
"./src/**/*.{js,ts,jsx,tsx}",
"./node_modules/nextjs-reusable-table/dist/**/*.{js,mjs}",
]
```
**Tailwind v4** — add to your CSS:
```css
@import "tailwindcss";
@source "../node_modules/nextjs-reusable-table/dist";
```
- Dates automatically formatted using `Intl.DateTimeFormat`
- Arrays displayed as chips with "+X more" expand button
- URLs detected and rendered as `<Link>` elements
- Sort by specifying `sortableProps` and providing an `onSort` handler
- Hide/show columns via per-header dropdown (`showRemoveColumns={true}`)
### Action Dropdowns
```tsx
<TableComponent
actions
actionTexts={["Edit", "Delete"]}
actionFunctions={[
(item) => handleEdit(item),
(item) => handleDelete(item),
]}
/>
```
```tsx
<TableComponent<User>
formatValue={(value, prop, item) => {
if (prop === "status")
return <span className={item.active ? "text-green-600" : "text-red-500"}>{value}</span>;
return value;
}}
/>
```
```tsx
<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](API.md). For more examples, see [EXAMPLES.md](EXAMPLES.md).
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
ISC — see [LICENSE](LICENSE).
Inspired by common data table patterns in React and Next.js applications. Thanks to all contributors and users for their support.