@liji-table/react

A headless, high-performance React table hook built on top of @liji-table/core.
It provides all advanced table logic — sorting, filtering, pagination, resizing, selection, export, and pinning — while leaving full UI control to the developer.

Logic handled. UI owned by you.

📌 Why @liji-table/react?

Most table libraries tightly couple logic + UI, making customization difficult and performance unpredictable.

@liji-table/react solves this by:

• Running all logic in a core engine
• Exposing React-friendly hooks
• Allowing any UI framework or design system

This makes it ideal for dashboards, admin panels, analytics apps, and enterprise software.

🧱 Architecture Overview

Your UI (React JSX) ↓ useUniversalTable() ↓ @liji-table/core (Framework-agnostic engine)

• @liji-table/react → React lifecycle & event bindings
• @liji-table/core → Sorting, filtering, pagination, state, performance
• Zero DOM assumptions
• Zero CSS coupling

✨ Key Features Explained

⚙️ Headless Design

You write the <table>, <thead>, <tbody>, or even <div>-based layouts.
The hook only provides data + actions.

🔄 Sorting

• Toggle ascending / descending / none
• Programmatic control
• Works on strings, numbers, booleans

🔍 Filtering & Search

• Column-level filtering
• Global search across all visible columns
• Case-insensitive by default

📄 Pagination

• Page index & page size control
• Automatic total page calculation
• Safe boundary handling

↔️ Column Resizing (High Performance)

• Uses direct DOM manipulation during drag
• React state updates only on mouse release
• No re-render lag

🧩 Column Reordering

• Native drag & drop support
• Disabled automatically while resizing
• State preserved across data updates

🧲 Column Pinning

• Pin columns left or right
• Useful for checkboxes, IDs, or actions

✅ Row Selection

• Per-row selection
• Select all rows on current page
• Useful for bulk actions

📤 Export

• Export filtered data
• Download CSV instantly
• No external dependency

📦 Installation

npm install @liji-table/react @liji-table/core

🚀 Basic Example

import { useUniversalTable } from "@liji-table/react";

const columns = [
  { id: "name", header: "Name", sortable: true },
  { id: "email", header: "Email" },
  { id: "sales", header: "Sales", sortable: true }
];

export default function Example({ data }) {
  const table = useUniversalTable(data, columns);

  return (
    <table>
      <thead>
        <tr>
          {table.visibleColumns.map((col, index) => (
            <th
              key={col.id}
              {...table.getHeaderProps(index, col.id)}
              style={{ width: table.state.columnWidths[col.id] }}
            >
              {col.header}
              <span {...table.getResizerProps(col.id)} />
            </th>
          ))}
        </tr>
      </thead>

      <tbody>
        {table.rows.map(row => (
          <tr key={row.id}>
            {table.visibleColumns.map(col => (
              <td key={col.id}>{row[col.id]}</td>
            ))}
          </tr>
        ))}
      </tbody>
    </table>
  );
}

🧠 Hook Return Values

📊 State & Data

| Property | Description | |--------|------------| | state | Full table state snapshot | | rows | Current page rows | | totalPages | Total page count | | allColumns | All columns | | visibleColumns | Columns not hidden | | selectedIds | Selected row IDs |

🛠 Actions API

🔍 Search & Filter

setSearch(query)
setFilter(columnId, value)

🔄 Sorting

toggleSort(columnId)
setSortDirection(columnId, direction)

📄 Pagination

setPage(pageIndex)
setPageSize(size)
nextPage()
prevPage()

🧩 Column Controls

toggleVisibility(columnId)
setColumnAlign(columnId, align)
pinColumn(columnId, 'left' | 'right' | null)
autoResizeAllColumns()

📤 Export

exportData()
downloadCSV("export.csv")

🎛 UI Helper Functions

These helpers are designed to be attached directly to DOM elements.

getHeaderProps(index, columnId)
getResizerProps(columnId)
isResizing

⚡ Performance Guarantees

• Core initialized once
• No state loss when data changes
• Resize does not trigger React renders
• Optimized for large datasets

🧩 When to Use This Library

✅ Recommended

• Admin dashboards
• Analytics tools
• Enterprise software
• Custom design systems

❌ Not Recommended

• If you want a pre-styled table
• If you don’t need advanced features