tblx

Headless state management hooks and context for data tables. Zero dependencies, maximum flexibility.

Installation

``bash
npm install tblx
`

Features

- 🎯 Headless - No UI components, just state management
- 🪝 Hooks-based - React hooks for all state operations
- 🔌 Context Provider - Ready-to-use TblxProvider for compound components
- 📦 Zero dependencies - Only requires React as a peer dependency
- 🔧 Fully typed - Complete TypeScript support
- 🚀 Lightweight - Minimal bundle size

Usage

$3

`tsx
import { TblxProvider, useTblxContext } from 'tblx';

const columns = [
{ key: 'name', label: 'Name', sortable: true },
{ key: 'email', label: 'Email' },
];

function MyTable() {
const { rows, state, handleSearchChange } = useTblxContext();

return (


);
}

function App() {
const [users, setUsers] = useState([]);

const handleStateChange = async ({ nextState }) => {
const data = await fetchUsers(nextState);
setUsers(data);
};

return (
rows={users}
columns={columns}
onStateChange={handleStateChange}
>


);
}
`

$3

`tsx
import { useTblx, tblxConsoleLogger } from 'tblx';

function MyTable() {
const {
state,
handleFilterChange,
handleSearchChange,
handleSortChange,
handlePageChange,
} = useTblx({
initialState: { page: 1, limit: 20 },
onStateChange: ({ event, nextState }) => {
console.log('State changed:', event, nextState);
},
debug: tblxConsoleLogger,
});

return (



);
}
`

$3

`tsx
import { useTblxSelection } from 'tblx';

function MyTableWithSelection({ rows }) {
const {
selectedRowIds,
handleRowSelect,
handleSelectAll,
clearSelection,
} = useTblxSelection({ rows });

return (










{rows.map((row) => (




))}



type="checkbox" onChange={(e) => handleSelectAll(e.target.checked)} />	Name
type="checkbox" checked={selectedRowIds.includes(row.id)} onChange={(e) => handleRowSelect(row.id, e.target.checked)} />	{row.name}


);
}
`

$3

`tsx
import { useTblxColumnConfig, generateTableId } from 'tblx';

const columns = [
{ key: 'name', label: 'Name', sortable: true },
{ key: 'email', label: 'Email' },
{ key: 'role', label: 'Role' },
];

function MyConfigurableTable() {
const storageKey = generateTableId(columns);

const {
configuredColumns,
toggleColumnVisibility,
reorderColumns,
resetConfig,
} = useTblxColumnConfig({
columns,
enableVisibility: true,
enableReorder: true,
storageKey,
});

return (



);
}
`

API Reference

$3

Context provider for table state management. Use with compound components.

Props:
- rows: T[] - Array of row data (must have id property)
- columns: TblxColumn[] - Column definitions
- initialState?: TblxState - Initial state
- onStateChange?: (params) => void - Callback when state changes
- hasMore?: boolean - Whether more data is available (for pagination)
- totalCount?: number - Total number of items
- id?: string - Unique ID for localStorage persistence
- debug?: TblxDebugFn - Debug logging function
- className?: string - CSS class for wrapper div

$3

Hook to access TblxProvider context. Must be used within TblxProvider.

Returns: TblxContextValue with all state and handlers.

$3

Standalone hook for table state management (without Provider).

Options:
- initialState?: TblxState
- enableFilterVisibilityToggler?: boolean
- onStateChange?: (params) => void
- debug?: TblxDebugFn

$3

Hook for row selection management.

Options:
- rows: T[] - Array of row objects with id property
- onSelectionChange?: (selectedRowIds: T["id"][]) => void - Callback when selection changes

$3

Hook for column visibility and reordering.

Options:
- columns: TblxColumn[]
- enableReorder?: boolean
- enableVisibility?: boolean
- storageKey?: string
- onColumnConfigChange?: (columnConfig: ColumnConfig[]) => void - Callback when column config changes

$3

- debounce(fn, wait) - Debounce function utility
- tblxConsoleLogger - Default console debug logger
- generateTableId(columns) - Generate unique table ID for storage

Types

`typescript
type TblxState = {
filters?: TblxInputValue;
search?: string;
sortBy?: Array<{ key: string; direction: "asc" | "desc" }>;
page?: number;
limit?: number;
filtersVisible?: boolean;
};

type TblxColumn = TblxDataColumn | TblxActionColumn;

type TblxDataColumn = {
type?: "data";
key: keyof T;
label: string;
className?: string;
sortable?: boolean;
render?: (row: T) => unknown;
};

type TblxActionColumn = {
type: "action";
key: string;
label: string;
className?: string;
render: (row: T) => unknown;
};
``

License

MIT