Documentation

What is Custom Table?

Custom Table is a feature-rich, type-safe table component for React. It supports view, edit, delete, and download actions per row, pagination, loading and empty states, optional grand total row, custom cell renderers, and theme-aware styling. This demo adds delete confirmations via react-hot-toast, Excel export (xlsx), light/dark theme toggle, and a full-width responsive layout. It is built with TypeScript and is suitable for use in any React project or as an npm package.

Installation

Install the package with npm, yarn, or pnpm:

npm install your-package-name

# or
yarn add your-package-name

# or
pnpm add your-package-name

After installation, include the component styles in your app (for example, by importing the compiled CSS or SCSS file that ships with the package, or by copying the theme variables into your own stylesheet).

Using it as a plugin or in your app

You can use Custom Table like any other React component:

1. Import the component and types from the package.
2. Define your row type (it must extend BaseRow) and your column definitions.
3. Render CustomTable with your data, columns, pagination state, and callbacks.

Example:

import { CustomTable, type BaseRow, type Column } from "your-package-name";

interface MyRow extends BaseRow {
  id: number;
  name: string;
  amount: number;
}

const columns: Column<MyRow>[] = [
  { header: "Name", field: "name" },
  { header: "Amount", field: "amount", total: true },
];

const data: MyRow[] = [/* your data */];

<CustomTable<MyRow>
  data={data}
  columns={columns}
  totalPages={5}
  totalRecords={data.length}
  page={page}
  limit={10}
  onPageChange={setPage}
  onLimitChange={setLimit}
  isPaginated
  isView
  isDelete
  onView={(row) => openModal(row)}
  onDel={(row, index) => removeRow(index)}
/>

Your app (or plugin) is responsible for managing data, page, and limit state; the table only displays the current slice and calls your callbacks when the user changes page, limit, or clicks an action.

Features at a glance

• TypeScript – Full type safety with generics (CustomTableProps<TRow>, Column<TRow>).
• Actions – Optional view, edit, delete, download, and cancel actions per row with callbacks.
• Pagination – Page and page-size controls with onPageChange and onLimitChange.
• Loading & empty states – Built-in loading row and configurable empty message.
• Grand total row – Set total: true on a column to show a sum in a footer row.
• Custom cells – Use the cell property on a column to render custom content per cell.
• Styling – CSS variables for theming; optional inline styles for header, body, and cells; hover and striped rows.
• Accessible – Semantic table markup and ARIA labels on action icons.
• Demo extras – This app uses react-hot-toast for delete confirmations, xlsx for Excel export, and a theme provider for light/dark mode; the table layout is full-width and responsive.

API reference

CustomTable props

The component is generic: CustomTable<TRow extends BaseRow>. All props are listed below.

Required props

• data – Array of row objects to display (TRow[]).
• columns – Column definitions: header, field, and optionally cell, total (Column<TRow>[]).
• totalPages – Total number of pages (e.g. Math.ceil(totalRecords / limit)).
• totalRecords – Total number of records.
• page – Current page (1-based).
• limit – Current page size (e.g. 10, 50, 100).
• onPageChange – Callback when the user changes the page.
• onLimitChange – Callback when the user changes the page size.

Optional props – appearance

• hover – Enable row hover highlight (default: true).
• striped – Enable alternating row background (default: true).
• headerStyle, bodyStyle, cellStyle, cellStyleAction – Inline styles for header cells, tbody, data cells, and the action column.

Optional props – actions

• isEdit, isView, isDelete, isDownload, isCancel – Set to true to show the corresponding action icon per row.
• onEdit, onCustomEdit, onView, onDel, onDown – Callbacks when the user clicks an action. Each receives (row, index). If onCustomEdit is provided, the edit icon calls it instead of onEdit.

Other

• isPaginated – When true, shows the pagination controls (page and limit dropdowns).
• loading – When true, shows a loading row instead of data.

Column type (Column<TRow>)

Each column has:

• header (string) – Column header label.
• field (keyof TRow) – Key of the row object to display.
• cell (optional) – Function (row: TRow) => ReactNode for custom cell content.
• total (optional) – If true, this column is included in the grand total row (numeric sum).
• align (optional) – "left" | "right" | "center" for cell and header alignment.
• headerRender (optional) – Function returning custom header content (e.g. select-all checkbox).

BaseRow type

Your row type must extend BaseRow. BaseRow includes optional fields used by the component: Status, isAction, download_pdf, and an index signature for additional properties. You can add your own fields (e.g. id, name, salary) when defining your row interface.

Theming

The table uses CSS custom properties so you can theme it for light and dark mode. Set data-theme="dark" on <html> (or a wrapper) and define overrides for:

• --bg-primary, --bg-secondary – Backgrounds.
• --text-primary, --text-secondary – Text colors.
• --border – Border color.
• --table-header-bg, --table-row-hover, --table-stripe – Table styling.
• --action-icon – Color for action icons and primary buttons.
• --btn-danger – Danger/delete button color (optional; falls back to red).
• --select-bg, --select-border – Pagination select styling.

Publishing to npm

To publish this component as an npm package:

1. Set name in package.json (e.g. @your-scope/react-custom-table).
2. Remove "private": true if present.
3. Add a build step (e.g. tsup or rollup) to produce a dist/ folder with JavaScript and type declarations.
4. Set main, types, and optionally style or exports in package.json.
5. Ensure the table CSS/SCSS is included in the package or documented for consumers.
6. Run npm publish (or npm publish --access public for unscoped packages).