DataTable

Sorting, search and column filters, pagination, checkbox row selection and column visibility on top of Table. useDataTable holds the state; DataTable renders it. No dependencies.

import { Badge, DataTable, type DataTableColumn, useDataTable } from "@meridui/react";

const columns: DataTableColumn<Member>[] = [
  { id: "name", header: "Name", accessor: "name", sortable: true, hideable: false },
  { id: "email", header: "Email", accessor: "email" },
  { id: "role", header: "Role", accessor: "role", sortable: true },
  {
    id: "status",
    header: "Status",
    accessor: "status",
    sortable: true,
    cell: (row) => <Badge tone={row.status === "Active" ? "success" : "neutral"}>{row.status}</Badge>,
  },
  { id: "projects", header: "Projects", accessor: "projects", sortable: true, align: "end" },
];

export function Members({ members }: { members: Member[] }) {
  const table = useDataTable({ data: members, columns, defaultPageSize: 5 });
  return (
    <DataTable
      table={table}
      caption="Team members"
      selectable
      getRowLabel={(row) => row.name}
      pageSizeOptions={[5, 10]}
    />
  );
}

Import

import { DataTable, useDataTable, type DataTableColumn } from "@meridui/react";

Anatomy

const table = useDataTable({ data, columns });

<DataTable table={table} caption="…" />

• Columns describe each field: accessor (a key or a function) feeds sorting, search and the default cell; cell renders anything else.
• useDataTable is headless: it returns the current page of rows and every setter. Each piece of state works controlled or uncontrolled.
• DataTable renders a toolbar (search, Columns menu, your toolbar), the Table with sortable headers and optional checkboxes, and a footer with the status line, a rows-per-page select and Pagination.

Examples

Column filters, default sort and hidden columns

Put your own filter controls in toolbar and drive them with setColumnFilter. A column's filterFn replaces the default "contains" match.

const table = useDataTable({
  data: members,
  columns,
  defaultSort: { columnId: "projects", direction: "descending" },
  defaultHiddenColumns: ["email"],
});

<DataTable
  table={table}
  caption="Team members by role"
  toolbar={
    <NativeSelect
      size="sm"
      aria-label="Role"
      value={table.columnFilters.role ?? ""}
      onChange={(event) => table.setColumnFilter("role", event.target.value)}
    >
      <option value="">All roles</option>
      <option value="Owner">Owner</option>
      {/* … */}
    </NativeSelect>
  }
/>

Headless

Render your own markup from the same state when DataTable's layout does not fit, for example a list of cards on mobile.

const table = useDataTable({ data, columns });

// Everything DataTable renders is available for your own markup:
table.rows;              // current page, filtered and sorted
table.toggleSort("name");
table.setGlobalFilter("ada");
table.setPage(2);
table.toggleRow(table.getRowId(row));
table.selectedRows;      // across pages
table.toggleColumn("email", false);

The hook works on the rows you pass in. For server-side sorting or paging, fetch with your own state and render Table directly.

API reference

DataTableColumn

useDataTable

Every state has a controlled prop, a default… prop and an on…Change callback.

It returns rows, filteredRows, visibleColumns, page, pageCount, pageSelection ("all" | "some" | "none"), selectedRows and the setters toggleSort, setGlobalFilter, setColumnFilter, setPage, setPageSize, toggleRow, togglePage, clearSelection and toggleColumn. Changing a filter or the page size returns to page 1.

DataTable

Accepts every Table prop.

DataTableLabels: search, searchPlaceholder, columns, selectPage, selectRow(rowLabel), selected(count, total), results(count), empty, rowsPerPage, pagination, previousPage, nextPage, page(n).

Styling

Rows, headers and cells are the Table's own (.mrd-table__*); selected rows get data-selected.

Accessibility

The table keeps native table semantics with a <caption>. Sortable headers are buttons inside <th aria-sort>; every checkbox has a name ("Select Ada Lovelace", "Select all rows on this page") and the header checkbox shows the mixed state. The status line is a polite live region that announces the number of results after a search and the selection count; the search box is described by it.

Guidelines

Related

• Table: the markup DataTable builds on.
• Data tables pattern: layout and bulk actions.
• Pagination: the footer control.