Table

Table and its subcomponents render native table, thead, tbody, tfoot, tr, td, and th elements through Reactberry's Text element. Use them for tabular data, with TablePagination and the hooks for in-memory sorting, filtering and paging. TablePagination and the three hooks are client-side ("use client"); the hooks hold state with React useState.

Import#

import {
  Table,
  TableHeader,
  TableBody,
  TableFooter,
  TableRow,
  TableCell,
  TableHeaderCell,
  TablePagination,
  useTableControls,
  useTableFilters,
  useFilteredTableControls,
} from "@reactberry/system/blocks";

Usage#

import {
  Table,
  TableHeader,
  TableBody,
  TableRow,
  TableCell,
  TableHeaderCell,
  TablePagination,
  useTableControls,
} from "@reactberry/system/blocks";
import { Box, Button } from "@reactberry/system/elements";

type User = {
  id: number;
  name: string;
  email: string;
  age: number;
  status: "active" | "inactive";
};

export default function UsersTable({ users }: { users: User[] }) {
  const controls = useTableControls({ data: users, initialItemsPerPage: 10 });

  const toggleSort = (key: string) =>
    controls.handleSort(
      key,
      controls.sortKey === key && controls.sortDirection === "asc" ? "desc" : "asc",
    );

  return (
    <Box>
      <Table>
        <TableHeader>
          <TableRow>
            <TableHeaderCell>
              <Button as="button" type="button" variant="ghost" $size="small" onClick={() => toggleSort("name")}>
                Name
              </Button>
            </TableHeaderCell>
            <TableHeaderCell>Email</TableHeaderCell>
            <TableHeaderCell align="right">Age</TableHeaderCell>
          </TableRow>
        </TableHeader>
        <TableBody>
          {controls.currentData.map((user) => (
            <TableRow key={user.id}>
              <TableCell align="left">{user.name}</TableCell>
              <TableCell align="left">{user.email}</TableCell>
              <TableCell align="right">{user.age}</TableCell>
            </TableRow>
          ))}
        </TableBody>
      </Table>
      <TablePagination
        currentPage={controls.currentPage}
        totalPages={controls.totalPages}
        totalItems={controls.totalItems}
        itemsPerPage={controls.itemsPerPage}
        onPageChange={controls.handlePageChange}
        showPageSize
        onPageSizeChange={controls.handlePageSizeChange}
      />
    </Box>
  );
}

Examples#

Sorting and page size#

useTableControls sorts and paginates rows in memory. Build sort controls inside TableHeaderCell; showPageSize with onPageSizeChange adds a page size select.

Filtering#

useFilteredTableControls filters rows with one predicate per filter key, then sorts and paginates the result. data holds the rows for the current page.

Footer row#

TableFooter renders a tfoot; colSpan is passed to the td.

API#

Table#

Renders Text with as="table" and width="100%". All props (HTML table attributes and Text/Box style props) are spread onto it after the defaults.

TableHeader, TableBody, TableFooter#

Render Text as thead, tbody, and tfoot respectively. They add no styles; all props are spread onto the element.

TableRow#

Renders Text as tr. All props are spread onto it.

TableCell#

Renders a td via Text with position="relative", border="1px solid", and a fixed height="2rem". Forwards its ref to the td.

Remaining props are spread onto the td before width, colSpan, rowSpan, and height, so height cannot be overridden.

TableHeaderCell#

Renders a th via Text with skin="row.header", border="1px solid", borderColor="surface", fontSize="xxs", and fontWeight="700". Children are wrapped in an inner div.

Remaining props are spread onto the th after the default styles.

TablePagination#

A client component that renders an item count, an optional page size select, and previous/next and page number buttons. No other props are accepted.

useTableControls#

Sorts and paginates an array in memory. The default sort compares row[key]; strings are compared case-insensitively with localeCompare, and null/undefined values sort last.

Parameters

useTableControls(options) takes a UseTableControlsOptions<T> object:

Returns

UseTableControlsReturn<T>:

useTableFilters#

Filters an array with one predicate per filter key.

Parameters

useTableFilters(options) takes a UseTableFiltersOptions<T, F> object:

Returns

UseTableFiltersReturn<T, F>:

useFilteredTableControls#

useFilteredTableControls(filterOptions, controlOptions) runs useTableFilters with filterOptions and passes filteredData into useTableControls. controlOptions is Omit<UseTableControlsOptions<T>, "data">. It returns every field from both hooks plus data, which equals currentData.

Accessibility#

• All parts render native table elements (table, thead, tbody, tfoot, tr, th, td).
• Pagination buttons are Button elements without as="button", so they render as span with role="button" and tabIndex={0}. They have no keyboard handler, and disabled only applies styles (pointer-events: none).
• Page buttons have aria-label values such as "Go to page 2" and the active page sets aria-current="page". The previous and next buttons are labelled "Previous page" and "Next page".
• The page size select is a native element with inline styles and is not programmatically labelled by the "Items per page:" text.

Notes#

• There is no SortableTableHeader export and Table has no striped, hoverable, compact, bordered, or stickyHeader props, despite references in src/blocks/Table/README.md and src/docs/api/blocks/Table.md.
• filterFunctions and initialFilters are memo dependencies; define them outside the component or memoise them to avoid recomputation on every render.
• Changing filters does not reset the page, but useTableControls clamps currentPage to the last valid page.
• In TablePagination, the next button is disabled only when currentPage === totalPages - 1; with totalPages of 0 it remains enabled.