Tablewind

Tablewind is a React/Next.js/Tailwind CSS library for data tables. It provides a set of reusable components that support inline editing, filtering, sorting, pagination, and more – all styled with Tailwind CSS.

Features

• Inline Editing: Edit data directly in the table.
• Sorting & Filtering: Easily sort and filter your data.
• Pagination: Built-in pagination controls.
• Bulk Actions: Support for selecting and acting on multiple rows.
• Customizable: Leverage Tailwind CSS to customize styling.
• Dual Navigation Support: Use the default React Router version or the Next.js version via separate entry points.

Installation

Install via npm:

npm install tablewind

Or using Yarn:

yarn add tablewind

Or using pnpm:

pnpm add tablewind

Peer Dependencies

Ensure you have the following installed in your project:

• react (>= 18.0.0)
• react-dom (>= 18.0.0)
• swr (^2.3.2)
• tailwindcss (^4.0.0)

Optional (Based on Your Environment)

• Next.js: next (>= 15.0.0) – for using the Next.js version.
• React Router: react-router-dom (>= 7.0.0) – for using the React Router version.

Usage

Default (React Router Version)

import { DataTable } from 'tablewind';

function MyComponent() {
    return (
        <DataTable
            endpoint="/api/data"
            columns={[
                // Define your column configurations here
            ]}
            fetcher={fetch} // Or your custom fetcher function
        />
    );
}

Next.js Version

import { DataTable } from 'tablewind/next';

function MyPage() {
    return (
        <DataTable
            endpoint="/api/data"
            columns={[
                // Define your column configurations here
            ]}
            fetcher={fetch} // Or your custom fetcher function
        />
    );
}

API: DataTable Props

| Prop Name | Type | Description | Optional | |------------------------|----------------------------------------------|-----------------------------------------------------------------------------|----------| | pageTitle | string | The main heading for the table page. | Yes | | pageSubtitle | string | Subtitle displayed beneath the main title. | Yes | | addNewUrl | string | URL to navigate to when the "Add New" button is clicked. | Yes | | endpoint | string | API endpoint used to fetch table data. | No | | columns | ColumnConfig<T>[] | Column definitions for the table. | No | | initialQuery | Record<string, string> | Initial query params to pre-load filters or pagination. | Yes | | fetcher | (url: string) => Promise<PaginatedResponse<T>> | Custom function for fetching data. | Yes | | onRowSelect | (selectedIds: string[], clearSelectionsAfterAction?: () => void, revalidate?: () => void) => void | Callback when row selection changes. Optionally provides a function to clear selections after bulk actions and a function to revalidate data. | Yes | | filterFields | FilterField[] | Array of field definitions for building the filter UI. | Yes | | bulkActions | BulkAction[] | List of bulk actions to display when multiple rows are selected. | Yes | | className | string | Custom CSS class for the table container. | Yes | | handleDelete | (id: string) => void | Callback invoked when a row is deleted. | Yes | | dateRangeFilter | { queryParamBase: string } | Enables a plug-and-play date range filter using the provided param base. | Yes | | loadingComponent | React.ReactNode | Custom component to render during loading. | Yes | | errorComponent | React.ReactNode | Custom component to render on error. | Yes | | redirectOnError | () => void | Called when there's an error; useful for redirecting. | Yes | | navigate | (url: string) => void | Function used to navigate (Next.js or React Router). | Yes | | showMobileFilters | boolean | Controls visibility of the filter panel on mobile. | No | | setShowMobileFilters | (open: boolean) => void | Sets the visibility state of mobile filters. | No | | showSelectionAlert | boolean | Shows an alert with the number of selected items when any items are selected. Defaults to false. | Yes | | showKeepSelectedOption | boolean | Shows a checkbox to keep items selected after bulk actions. Defaults to false. | Yes | | searchEnabled | boolean | Enables the internal search bar in the table header. Defaults to false. | Yes | | searchPlaceholder | string | Placeholder text for the search input. Defaults to 'Search...'. | Yes | | onEditSave | (id: string, newValues: EditValues) => void | Called when an inline edit is saved. | Yes | | onEditCancel | () => void | Called when inline edit mode is cancelled. | Yes |

Search Functionality

Tablewind provides flexible search capabilities that can be implemented in two ways:

Internal Search Bar

Enable a built-in search bar within the table header:

<DataTable
    endpoint="/api/data"
    columns={columns}
    searchEnabled={true}
    searchPlaceholder="Search items..."
    // ... other props
/>

The internal search bar:

• Appears in the table header on both desktop and mobile views
• Includes debouncing (300ms) to optimize API calls
• Has a clear button to quickly reset the search
• Automatically syncs with URL query parameters

External Search Bar

Use a search bar from outside the library (e.g., in a navbar):

import { SearchBar } from 'tablewind';

function Navbar() {
    const navigate = useNavigate();
    const [searchParams] = useSearchParams();
    
    const handleSearch = (value: string) => {
        const params = new URLSearchParams(searchParams);
        if (value) {
            params.set('search', value);
        } else {
            params.delete('search');
        }
        navigate(`?${params.toString()}`);
    };

    return (
        <nav>
            <SearchBar
                value={searchParams.get('search') || ''}
                onChange={handleSearch}
                placeholder="Search..."
            />
        </nav>
    );
}

The DataTable will automatically pick up the ?search=value query parameter from the URL and pass it to the API endpoint.

Note: The search parameter is cleared when you use the "Reset Filters" button, whether using internal or external search.

Selection Alert Features

Tablewind provides optional features to enhance the user experience when selecting rows:

Selection Alert

By default, Tablewind only shows an alert when all items are selected. You can enable a selection alert that appears whenever any items are selected:

<DataTable
    endpoint="/api/data"
    columns={columns}
    showSelectionAlert={true}  // Shows "X items selected" for any selection
    // ... other props
/>

Keep Selected After Bulk Actions

You can provide users with the option to keep items selected after performing bulk actions:

<DataTable
    endpoint="/api/data"
    columns={columns}
    showSelectionAlert={true}
    showKeepSelectedOption={true}  // Shows checkbox to keep selections
    bulkActions={[
        {
            key: 'delete',
            label: 'Delete Selected',
            onClick: (selectedIds, clearSelectionsAfterAction, revalidate) => {
                // Perform bulk delete
                deleteItems(selectedIds).then(() => {
                    // Refresh the data without losing component state
                    revalidate?.();
                    // Conditionally clear selections based on user preference
                    clearSelectionsAfterAction?.();
                });
            }
        }
    ]}
    // ... other props
/>

When showKeepSelectedOption is enabled, a checkbox labeled "Keep selected after bulk action" appears in the selection alert. Users can check this to prevent their selections from being cleared after bulk actions are performed.

Important: Use the revalidate function instead of forcing component re-mounts (e.g., with key props) to refresh data. This preserves the selection state and allows the "keep selected" functionality to work properly.

Alternative Usage with onRowSelect

You can also access the revalidate function through the onRowSelect callback:

<DataTable
    endpoint="/api/data"
    columns={columns}
    onRowSelect={(selectedIds, clearSelectionsAfterAction, revalidate) => {
        // Store revalidate function for use in your bulk actions
        console.log(`${selectedIds.length} items selected`);
        // Use revalidate() when you need to refresh data
    }}
    // ... other props
/>

Importing CSS & Overriding Theme Colors

Before using Tablewind, be sure to import its CSS file into your project (for example, in your global stylesheet or in Next.js’s src/app/globals.css):

@import 'tailwindcss';
@import 'tablewind/tablewind.css';

To customize Tablewind’s colors, override the following CSS variables in your own stylesheet. For example:

:root {
    --dark-tablewind-accent: #yourCustomColor;
}

The available override variables are:

--dark-tablewind-accent
--dark-tablewind-accent-hover
--light-tablewind-accent
--light-tablewind-accent-hover

--dark-tablewind-text-primary
--dark-tablewind-text-secondary
--light-tablewind-text-primary
--light-tablewind-text-secondary

--dark-tablewind-border-primary
--light-tablewind-border-primary

--dark-tablewind-bg-primary
--dark-tablewind-bg-primary-hover
--light-tablewind-bg-primary
--light-tablewind-bg-primary-hover

--dark-success-alert-bg
--dark-success-alert-text
--light-success-alert-bg
--light-success-alert-text

--dark-reset-filters-bg
--dark-reset-filters-bg-hover
--dark-reset-filters-text
--light-reset-filters-bg
--light-reset-filters-bg-hover
--light-reset-filters-text

--dark-button-delete-bg
--dark-button-delete-bg-hover
--dark-button-delete-text
--light-button-delete-bg
--light-button-delete-bg-hover
--light-button-delete-text

--dark-button-edit-bg
--dark-button-edit-bg-hover
--dark-button-edit-text
--light-button-edit-bg
--light-button-edit-bg-hover
--light-button-edit-text

--dark-button-cancel-bg
--dark-button-cancel-bg-hover
--dark-button-cancel-text
--light-button-cancel-bg
--light-button-cancel-bg-hover
--light-button-cancel-text

--dark-button-save-bg
--dark-button-save-bg-hover
--dark-button-save-text
--light-button-save-bg
--light-button-save-bg-hover
--light-button-save-text

--dark-button-pagination-bg
--dark-button-pagination-bg-hover
--dark-button-pagination-text
--light-button-pagination-bg
--light-button-pagination-bg-hover
--light-button-pagination-text

--dark-button-pagination-disabled-bg
--dark-button-pagination-disabled-text
--light-button-pagination-disabled-bg
--light-button-pagination-disabled-text

--dark-pagination-text
--light-pagination-text

--dark-switch-bg
--light-switch-bg

--dark-show-filters-bg
--dark-show-filters-bg-hover
--dark-show-filters-text
--light-show-filters-bg
--light-show-filters-bg-hover
--light-show-filters-text

--dark-header-bg
--light-header-bg

--dark-table-divider
--light-table-divider

--dark-table-header-bg
--light-table-header-bg

--dark-header-ring
--light-header-ring

--dark-bulk-dropdown-bg
--dark-bulk-dropdown-bg-hover
--dark-bulk-dropdown-text
--dark-bulk-dropdown-ring
--dark-bulk-dropdown-divider
--light-bulk-dropdown-bg
--light-bulk-dropdown-bg-hover
--light-bulk-dropdown-text
--light-bulk-dropdown-ring
--light-bulk-dropdown-divider

--dark-multi-select-item-bg
--dark-multi-select-item-text
--light-multi-select-item-bg
--light-multi-select-item-text

Local Development & Testing

Building the Library

To build the library locally:

npm run build

This will:

1. Compile TypeScript files using tsc
2. Bundle the library using Rollup
3. Output the compiled files to the dist/ directory

Testing Locally in Another Project

To test the library locally before publishing:

1. Build and pack the library:

   npm run build
   npm pack

   This creates a .tgz file (e.g., tablewind-4.1.0.tgz)

2. Install in your test project:

   cd /path/to/your/test-project
   npm install /path/to/tablewind/tablewind-4.1.0.tgz
   # Or with pnpm:
   pnpm add /path/to/tablewind/tablewind-4.1.0.tgz
   # Or with yarn:
   yarn add /path/to/tablewind/tablewind-4.1.0.tgz

3. Test your changes in the test project

4. To update after making changes:

   # In tablewind directory
   npm run build
   npm pack
      
   # In test project (npm)
   npm install /path/to/tablewind/tablewind-4.1.0.tgz --force
   # Or with pnpm:
   pnpm add /path/to/tablewind/tablewind-4.1.0.tgz --force
   # Or with yarn:
   yarn add /path/to/tablewind/tablewind-4.1.0.tgz --force

Note: The GitHub Actions pipeline automatically handles building and deployment to npm when pushing tags or releases.

Contributing

Contributions are welcome! However, whilst this has been open sourced, it was built to solve a specific set of use cases I have with my projects. If you have ideas for new features or improvements, please open an issue or submit a pull request, however it will only get merged if it will work with my projects.

License

This project is licensed under the MIT License.

Changelog

For a complete list of changes, see the CHANGELOG.md file.

Funding

If you find this project useful and would like to support its development, please consider donating via one of the platforms below:

GitHub Sponsors

Thank you for your support!