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

• 📖 API Reference - Complete prop reference and component API
• 💡 Examples & Use Cases - Real-world examples and advanced usage patterns

🚀 Key Features

• 🎯 Zero Configuration - Works out of the box
• 📊 Smart Data Handling - Automatically 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 and lazy loading
• 🎨 Truly Headless - Customize every style, behavior, and interaction
• 🛠️ Advanced Customization - Override any style or behavior with comprehensive APIs
• 📦 Lightweight - ~39KB minified, tree-shakable

📦 Installation

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

Bundle Size Impact

• Minified: ~39KB
• Minified + Gzipped: ~12KB
• Tree-shakable: Import only what you need
• Zero runtime dependencies: Only peer dependencies on React/Next.js

✅ Prerequisites

Requirement	Version	Notes
Next.js	12+	App Router and Pages Router supported
React	16+	Hooks-based, no class components
React DOM	16+	Standard DOM rendering
Tailwind CSS	3.0+	Required for styling
TypeScript	4.5+	Recommended for best experience

⚠️ Client Component Note: This uses "use client" directive. For SSR contexts, ensure proper hydration handling.

🚀 Quick Start

Basic Usage

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

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

export default function BasicTable() {
  const users: User[] = [
    { id: 1, name: "Alice Johnson", email: "alice@example.com" },
    { id: 2, name: "Bob Smith", email: "bob@example.com" },
    { id: 3, name: "Carol Davis", email: "carol@example.com" },
  ];

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

With Search and Pagination

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

export default function SearchableTable() {
  const [searchTerm, setSearchTerm] = useState("");
  const [currentPage, setCurrentPage] = useState(1);

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

Introduction

Next.js Reusable Table is designed for easy integration into Next.js apps. It supports sorting, pagination, row actions, and flexible data rendering via custom formatters. Built-in helpers handle arrays, dates, and URLs gracefully.

Features

Column Management

• Hide/Show columns: Each column header has a dropdown (⋮) to remove or unhide columns.
• Sorting: Specify which columns can be sorted.

<TableComponent
  columns={["Name", "Email"]}
  data={yourData}
  props={["name", "email"]}
  sortableProps={["name"]}
/>

Smart Row Interactions

The table provides intelligent click handling:

• Click anywhere on a row to trigger row action
• Click on cell content to expand/interact without triggering row action
• Expandable content with "show more" functionality

Built-In Data Handling

• Dates automatically formatted.
• Arrays displayed as chips with “+X more” for large arrays.
• URLs automatically detected and rendered as links.

Action Dropdowns

• Easily attach row actions via a dropdown button:

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

Search and Pagination

• searchValue filters rows against all columns.
• Built-in pagination. Provide page, setPage, and itemsPerPage.

<TableComponent
  searchValue={searchTerm}
  enablePagination
  page={page}
  setPage={setPage}
  itemsPerPage={10}
/>

Custom Styling

• Styling with Tailwind. Override default classes or disable them entirely:

const customClassNames = {
  table: "my-custom-table-styles",
  thead: "bg-gray-200 text-gray-700",
  tbody: "divide-y divide-gray-200",
  pagination: {
    container: "flex justify-center mt-4",
    button: "px-2 py-1 border",
    pageInfo: "mx-2",
  },
};

<TableComponent
  customClassNames={customClassNames}
  disableDefaultStyles={false}
/>;

Dark Mode

• Automatically respects system preference if enableDarkMode is true.

Loading Skeleton

• Show a skeleton loader while data is loading.

<TableComponent loading />

Empty State

Pass noContentProps to customize text and icon:

<TableComponent
  noContentProps={{
    text: "No data found",
    icon: <MyCustomIcon />,
  }}
/>

Advanced Example

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

interface Project {
  id: number;
  title: string;
  tags: string[];
  deadline: string;
  active: boolean;
  link: string;
}

export default function AdvancedProjectTable() {
  const initialData: Project[] = [
    {
      id: 1,
      title: "Website Redesign",
      tags: ["UI", "UX", "Frontend"],
      deadline: "2025-03-15T10:30:00Z",
      active: true,
      link: "https://example.com/project/1",
    },
    {
      id: 2,
      title: "Mobile App Development",
      tags: ["iOS", "Android", "Backend"],
      deadline: "2025-04-01T14:00:00Z",
      active: false,
      link: "https://example.com/project/2",
    },
    {
      id: 3,
      title: "Marketing Campaign",
      tags: ["SEO", "Social Media"],
      deadline: "2025-02-20T09:00:00Z",
      active: true,
      link: "https://example.com/project/3",
    },
    {
      id: 4,
      title: "E-commerce Platform",
      tags: ["Frontend", "Backend", "API", "Payments", "Analytics"],
      deadline: "2025-05-05T11:00:00Z",
      active: true,
      link: "https://example.com/project/4",
    },
    {
      id: 5,
      title: "Data Analysis",
      tags: ["Python", "ML", "Data Science"],
      deadline: "2025-03-01T08:00:00Z",
      active: false,
      link: "https://example.com/project/5",
    },
  ];

  const [projects, setProjects] = useState<Project[]>(initialData);
  const [page, setPage] = useState<number>(1);
  const [searchTerm, setSearchTerm] = useState<string>("");
  const [sortConfig, setSortConfig] = useState<{
    prop: keyof Project;
    order: "asc" | "desc";
  } | null>(null);

  const handleSort = (prop: keyof Project) => {
    let order: "asc" | "desc" = "asc";
    if (sortConfig && sortConfig.prop === prop) {
      order = sortConfig.order === "asc" ? "desc" : "asc";
    }
    setSortConfig({ prop, order });
  };

  const editProject = (project: Project) => {
    alert(`Edit project: ${project.title}`);
  };

  const deleteProject = (project: Project) => {
    alert(`Delete project: ${project.title}`);
  };

  const handleRowClick = (project: Project) => {
    console.log("Row clicked:", project);
  };

  const formatValue = (value: string, prop: string, project: Project) => {
    if (prop === "active") {
      return project.active ? "Active" : "Archived";
    }
    return value;
  };

  const formatHeader = (header: string, prop: string, index: number) => (
    <div>
      <span className="font-semibold uppercase tracking-wide">{header}</span>
    </div>
  );

  const sortedFilteredProjects = useMemo(() => {
    const filtered = projects.filter((project) => {
      const searchLower = searchTerm.toLowerCase();
      return (
        String(project.id).includes(searchLower) ||
        project.title.toLowerCase().includes(searchLower) ||
        project.tags.join(" ").toLowerCase().includes(searchLower) ||
        project.deadline.toLowerCase().includes(searchLower) ||
        (project.active ? "active" : "archived").includes(searchLower) ||
        project.link.toLowerCase().includes(searchLower)
      );
    });
    if (sortConfig) {
      filtered.sort((a, b) => {
        const aValue = String(a[sortConfig.prop]).toLowerCase();
        const bValue = String(b[sortConfig.prop]).toLowerCase();
        if (aValue < bValue) return sortConfig.order === "asc" ? -1 : 1;
        if (aValue > bValue) return sortConfig.order === "asc" ? 1 : -1;
        return 0;
      });
    }
    return filtered;
  }, [projects, searchTerm, sortConfig]);

  const customClassNames = {
    table: "border border-gray-300 rounded-md shadow-sm",
    thead: "bg-blue-50 text-blue-700",
    tbody: "",
    th: "px-4 py-2",
    tr: "",
    td: "px-4 py-2",
    pagination: {
      container: "mt-4",
      button: "bg-blue-500 text-white rounded px-3 py-1",
      buttonDisabled: "bg-gray-300 text-gray-700 rounded px-3 py-1",
      pageInfo: "text-blue-700",
    },
  };

  return (
    <div className="p-4">
      <h1 className="text-2xl font-bold mb-4">Advanced Project Table</h1>
      <div className="mb-4">
        <input
          type="text"
          placeholder="Search projects..."
          value={searchTerm}
          onChange={(e) => setSearchTerm(e.target.value)}
          className="border border-gray-300 rounded px-2 py-1 w-full"
        />
      </div>
      <TableComponent<Project>
        columns={["ID", "Title", "Tags", "Deadline", "Status", "Link"]}
        data={sortedFilteredProjects}
        props={["id", "title", "tags", "deadline", "active", "link"]}
        sortableProps={["title", "deadline"]}
        onSort={handleSort}
        actionTexts={["Edit", "Delete"]}
        actionFunctions={[editProject, deleteProject]}
        rowOnClick={handleRowClick}
        formatValue={formatValue}
        formatHeader={formatHeader}
        enablePagination
        page={page}
        setPage={setPage}
        itemsPerPage={2}
        noContentProps={{ text: "No projects found", icon: null }}
        customClassNames={customClassNames}
      />
    </div>
  );
}

Prop Reference

Prop	Type	Default	Description
columns	string[]	–	Column headers
data	T[]	–	Array of data objects
props	ReadonlyArray	–	Object keys to display
actions	boolean	false	Enable action dropdown
actionTexts	string[]	–	Labels for dropdown actions
loading	boolean	false	Show loading skeleton
actionFunctions	Array	–	Handlers for dropdown items
searchValue	string	–	Filter rows by substring
rowOnClick	(item: T) => void	–	Callback for row clicks
enablePagination	boolean	false	Enable pagination
page	number	1	Current page index
setPage	(page: number) => void	–	Page setter callback
itemsPerPage	number	10	Rows per page
totalPages	number	–	Override total pages
sortableProps	Array	[]	Columns that can be sorted
formatValue	(val, prop, item) => React.ReactNode	–	Custom cell formatter
enableDarkMode	boolean	true	Respect system dark mode
disableDefaultStyles	boolean	false	Disable built-in styling
customClassNames	object	{}	Tailwind class overrides
noContentProps	object	{}	Custom empty state
onSort	(prop: keyof T) => void	–	Callback triggered when a sortable column header is clicked.
formatHeader	(header: string) => React.ReactNode	–	Custom header formatter

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details on how to get started.

Versioning

We use Semantic Versioning for versioning. For the versions available, see the tags on this repository.

To bump the version, update the version field in package.json and follow the guidelines in the CONTRIBUTING.md file.

License

This project is licensed under the ISC License - see the LICENSE file for details.

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

⭐ Support the Project

If you find this library helpful, please consider:

• ⭐ Starring the repository - It helps others discover the project
• 🐛 Reporting bugs - Help improve the library by reporting issues
• 💡 Requesting features - Suggest new features or improvements
• 📖 Contributing code - Help make the library even better

Your support helps keep this project maintained and improved! 🚀

Acknowledgments

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