Getting started

This guide walks you through adding a read-only table page from scratch. You need a working backend table first — see Backend getting started or confirm with your team.

Read first

New to ApiTables UI? Spend 10 minutes on Key concepts.

What you will build

A client page that:

Fetches structure from load-table/{tableName}
Renders ReactApiTable with loading state
Automatically queries and displays paginated rows

Prerequisites

Requirement	Why
Backend `load-table` for your table	Supplies columns, filters, actions
Backend `query-table` for same `tableName`	Supplies row data
`'use client'` page under `app/[locale]/...`	Hooks and Redux require client component
Auth session / token	Same as other API calls in the app

Confirm the load path with backend — example: /api-table/control-tables/load-table/orders.

Minimal page

'use client';

import { useEffect } from 'react';
import useTableStructure from '@/app/ApiTables/hooks/useTableStructure';
import ReactApiTable from '@/app/ApiTables/ReactApiTable';

export default function OrdersPage() {
  const { getTableStructure, tableStructure, tableStructureLoading } = useTableStructure();

  useEffect(() => {
    getTableStructure({ table: '/api-table/control-tables/load-table/orders' });
  }, []);

  if (tableStructureLoading) {
    return <div>Loading table…</div>;
  }

  return (
    <ReactApiTable
      table={tableStructure}
      tableStructureLoading={tableStructureLoading}
    />
  );
}

Line-by-line

Line	Purpose
`'use client'`	Enables hooks in App Router
`useTableStructure`	GET hook — stores response in `tableStructure`
`getTableStructure({ table: '...' })`	Path to structure endpoint (not query)
`tableStructureLoading`	Prevent render before structure exists
`ReactApiTable`	Wraps provider, controller, grid UI

Paths & imports

Docs use ./ApiTables/. In app code import via @/app/ApiTables/....

Verify in browser

Check	Expected
Network: GET load-table	`success: true`, `columns` array
Network: POST query-table	`items` with data
UI	Column headers match backend labels
Pagination	Changes page → new query POST

If structure fails: fix backend or auth first — see Troubleshooting.

Optional props (when you need more)

<ReactApiTable
  table={tableStructure}
  tableStructureLoading={tableStructureLoading}
  params={{ warehouseId: 'x' }}
  customElement={<MyToolbar />}
/>

Prop	Purpose
`params`	Merged into every `query-table` body — scope rows to parent context
`customElement`	React node above table — Custom elements
`controller`	Replace `ApiTablesController` for advanced cases
`children`	Rendered inside `ApiTablesProvider` before the table

What to learn next

Task	Read
Full client flow	Architecture overview, Data flow
Structure fields	Table structure
Filters / sort	Filters, Sorting
Row or bulk actions	Row actions, Bulk actions
Custom modal	Adding a custom control
Refresh from parent form	Out-of-scope refresher

Example paths in the app

Feature	Structure path
Categories	`/api-table/control-tables/load-table/categories`
Products	`/api-table/control-tables/load-table/products`

Copy from a working feature in the same app when unsure.

Checklist before PR

Loading state while structure fetches
Correct load-table path confirmed with backend
Table renders columns and rows in dev
No hard-coded column definitions in React
Page is 'use client'

On this page