BetterTable Props

<BetterTable /> is copied into your app by better-tables init (see UI & CLI) — import it from your local path:

import { BetterTable } from '@/components/better-tables-ui/table/table';

Pass data plus either a table definition (supplies identity and columns) or both id and columns. id alone is not enough — the component throws without columns.

Identity & columns

Prop	Type	Notes
`id`	`string`	Unique table instance id (keys the state store and URL params). Defaults to `table.tableName` when `table` is given
`name`	`string`	Human-readable display name. Defaults to `table.tableName`
`columns`	`ColumnDefinition[]`	Column definitions. Defaults to `table.columns`. Server aggregates: `t.count` / `t.aggregate`
`table`	`TableDefinition`	A `defineTable()` / `tables.define()` definition — sugar for `columns`/`id`/`name` (explicit props still win). Enables auto columns resolution when paired with `adapter`

Data & fetching

Prop	Type	Notes
`data`	`TData[]` (required)	The rows to render
`adapter`	`TableAdapter`	Optional — powers lazy filter options, facets, auto-column resolution, and adapter cell-edit saves
`totalCount`	`number`	Filtered total for pagination — always pass `result.total` with server pagination
`loading`	`boolean`	Render the loading state
`error`	`Error \| null`	Render the error state
`onRetry`	`() => void`	Retry button handler for the error state
`emptyMessage`	`string`	Empty-state text (wins over `emptyState.description`)

Initial state

Prop	Type
`initialFilters`	`FilterState[] \| FilterGroupNode` — a `FilterGroupNode` tree seeds the initial query, but the filter bar edits flat: the first user edit replaces the tree with a flat implicit-AND array (tree editing is not shipped)
`initialSorting`	`SortingState`
`initialPagination`	`PaginationState`
`initialSelectedRows`	`Set<string>`
`initialColumnVisibility`	`ColumnVisibility`
`defaultVisibleColumns`	`string[]` — ids visible by default; others start hidden

Change callbacks (controlled usage)

Prop	Fires when
`onFiltersChange(filters)`	Filter state changes
`onSortingChange(sorting)`	Sort state changes
`onPaginationChange(pagination)`	Page or page size changes
`onPageChange(page)`	Page changes
`onPageSizeChange(pageSize)`	Page size changes
`onSelectionChange(selected)`	Row selection changes
`onRowClick(row)`	A row is clicked

Typical server-driven wiring: react to the callbacks, refetch via tables.fetchData, pass fresh data + totalCount back in.

Filtering behavior

Prop	Notes
`autoShowFilteredColumns`	Auto-reveal a column while it has an active filter (default `true`). Removing the filter re-hides the column only when `defaultVisibleColumns` is provided (and the column isn't in it); without that prop, revealed columns stay visible
`isFilterProtected(filter)`	Return `true` to lock a filter — shown with a lock icon, not removable
`groups`	Manual filter-dropdown grouping (`FilterGroup[]`)
`autoGroupFilters`	Automatic grouping config — see Filtering

Editing

Prop	Notes
`editing`	`false` disables all inline editing
`saveAction`	Serializable server action from `tables.cellEditAction(def)`
`onCellEdit`	Full-control save callback (wins over every other save path)
`onCellEditError`	Called when a save fails (after rollback)

See Inline editing for the save-resolution order.

URL sync

Prop	Notes
`urlSync`	`{ adapter: UrlSyncAdapter, config?: UrlSyncConfig }` — the component runs the sync internally; see URL State

Rendering & layout

Prop	Notes
`virtualized`	`true` or `{ height?, rowHeight?, overscan? }` — see Large datasets
`className`	Root class name
`rowConfig`	`getId(row)` (row identity — required for selection/editing when rows have no `id` field) and `onClick(row)` are wired; the remaining `RowConfig` fields (`isSelectable`, `isExpandable`, `expandedContent`, `className`, `style`) are contract-only today — the copied `table.tsx` doesn't read them yet
`emptyState`	`{ description?, icon? }` empty-state config (`emptyMessage` wins for text)
`errorState`	Error-state config
`actions`	Bulk actions on selected rows — see Selection & actions

Feature flags

features toggles whole subsystems:

Flag	Default	Effect
`filtering`	`true`	Filter bar + filter dropdowns
`sorting`	`true`	Header sort controls
`pagination`	`true`	Pagination footer
`columnVisibility`	`true`	Column show/hide menu
`rowSelection`	`false`	Checkbox column + selection state — see Selection & actions
`columnReordering`	`false`	Drag-and-drop header reordering
`headerContextMenu`	—	Right-click header menu

<BetterTable columns={columns} data={data} features={{ pagination: false, rowSelection: true }} />

Turning pagination off renders every row — pair with virtualized for big datasets.

Those are the only feature flags. Bulk-action controls appear for selected rows when actions is non-empty and at least one action is visible (isVisible can hide them) — there's no bulkActions flag — and virtualization is the virtualized prop, not a feature flag. Initial filters use the initialFilters prop and the loading state (skeleton rows) uses the loading boolean prop.

On this page