Table

Usage

import { Table, type TableColumn } from "@tulipfarm/sprout/table";

const columns: TableColumn<Order>[] = [
  { key: "customer", header: "Customer", sort: true, filter: "text" },
  { key: "crop", header: "Crop", filter: "select", group: true, options: crops },
  { key: "boxes", header: "Boxes", align: "right", sort: true, aggregate: "sum", edit: "number" },
];

<Table
  aria-label="Orders"
  data={orders}
  columns={columns}
  getRowId={(row) => row.id}
  searchable
  selectable
  onRowSave={(row, changes) => save(row.id, changes)}
/>

variant is "plain" (default) or"grid". Grid tables sit in a bordered scroll region capped at 60dvh, with a pinned header. narrow is"scroll" (default) or "stack", which turns rows into cards when the table is narrower than 36rem.

Columns

Each column reads row[key]. cell changes what shows, but sort, filter, and edit still use the raw value.sort adds a sort button. filter is"text", "number", "select","date", or "boolean". edit is"text", "number", "select","date", or "checkbox". optionsfeeds select filters and editors. group lets people group by the column. aggregate ("sum","count", "min", "max","mean") shows totals on group rows and in the footer.hint adds an info tooltip. width,pin, and hidden set the starting layout.

Rows

getRowHref or onRowClick turns the first cell into a link or button that covers the row. actions adds a pinned actions cell. onRowSave adds Edit, Save, and Cancel; if it rejects, the row stays open and shows the error.selectable adds checkboxes and callsonSelectionChange with row ids. Shift+click a checkbox to set every row since the last one picked. getSubRowsnests rows. onRowReorder adds drag handles.onRowDrop accepts files dropped on a row.pageSize adds pages, and virtual draws only the rows in view. loading shows skeleton rows, andempty shows when no rows match.

State and URLs

The table keeps its own state. Pass state to control any part, and onStateChange to hear every change. Withmanual, the server sorts, filters, and pages; passrowCount. persistKey saves column widths, order, pinning, and visibility to localStorage.

import { useTableUrlState } from "@tulipfarm/sprout/table-nuqs";

const url = useTableUrlState({ prefix: "orders-" });

<Table aria-label="Orders" data={orders} columns={columns} getRowId={(row) => row.id} {...url} />

useTableUrlState keeps sort, filters, search, grouping, and page in the URL with nuqs, so a shared link opens the same view. Installnuqs and add its adapter.

Accessibility

The table renders native table elements. Headings carryaria-sort. Checkboxes, editors, drag handles, and resize handles all work from the keyboard: drag handles use Space and the Arrow keys, and resize handles use the Arrow keys. Group rows usearia-expanded. Virtual rows set aria-rowcountand aria-rowindex. The stack layout keeps table roles and labels each value with its column name.

Theme tokens

Row dividers use --sprout-line; grid dividers and the frame use --sprout-input. Hover and grid header tints are--sprout-table-hover and --sprout-table-head-bg. Selected rows use --sprout-primary-subtle.