Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Tables
sidebarTitle: Tables
description: Add, change, or remove columns on built-in list tables (products, orders, customers, …), or define a table for your own resource.
---
<Note>
Examples here import from `@spree/dashboard`, which re-exports the framework and the design system for host applications. A **distributed plugin** imports `@spree/dashboard-core` and `@spree/dashboard-ui` directly instead — it extends the shell rather than shipping it. See [plugin overview](/developer/dashboard/plugins/overview).
</Note>
Every list page in the dashboard renders through `<ResourceTable>`, which reads its column definitions from a **table registry** keyed by table name (`products`, `orders`, `customers`, …). That gives you two levers:
1. **Extend a built-in table** — add, patch, or remove columns (including their filters) without forking the page.
2. **Define your own table** — declare columns once with `defineTable`, then render them with `<ResourceTable>` on your own page.
## Add a column to a built-in table
Imperatively, from `src/plugins.ts` (or a plugin entry):
```tsx
import { tables } from '@spree/dashboard'
tables.products.addColumn({
key: 'brand',
label: 'Brand',
default: true, // visible out of the box
render: (product) => product.brand?.name ?? '—',
})
```
Or declaratively through `defineDashboardPlugin` — same effect, grouped with your other extensions:
```tsx
defineDashboardPlugin({
tables: {
products: {
add: [{ key: 'brand', label: 'Brand', default: true, render: (p) => p.brand?.name ?? '—' }],
},
},
})
```
New columns append after the existing ones. Column keys must be unique per table — adding a duplicate throws with a message telling you to use `updateColumn` instead.
<Note>
**Timing is taken care of.** Built-in tables register when their page first loads, which may be after your code runs. Mutations against a table that isn't registered yet are queued and replayed the moment it appears — and mutations against a table that never registers simply never fire. That means extending an optional feature's table is safe even when that feature isn't installed.
</Note>
## Modify or remove built-in columns
```tsx
tables.products.updateColumn('price', { label: 'Retail price' })
tables.products.removeColumn('cost_price')
```
Declaratively:
```tsx
defineDashboardPlugin({
tables: {
products: {
update: { price: { label: 'Retail price' } },
remove: ['cost_price'],
},
},
})
```
`updateColumn` patches shallowly — pass only the fields you want to change. `removeColumn` of an unknown key is a no-op.
## Column definition
```ts
interface ColumnDef<T> {
key: string // unique per table; also the default Ransack sort/filter attribute
label: string // header text — use i18n.t(...) for translated labels
render?: (row: T) => ReactNode // cell renderer; defaults to rendering row[key] as text
className?: string // cell class (e.g. 'text-right tabular-nums')
default?: boolean // part of the visible column set out of the box
sortable?: boolean // header toggles Ransack sort on the attribute
filterable?: boolean // appears in the filter panel
ransackAttribute?: string // backend attribute when it differs from key
displayable?: boolean // set false for filter-only entries (no column rendered)
}
```
### Filter types
When a column is `filterable`, `filterType` decides which filter UI it gets:
| `filterType` | Filter UI | Extra fields |
|---|---|---|
| `'string'` (default) | Text input with contains/equals operators | — |
| `'boolean'` | Yes/no toggle | — |
| `'number'` | Numeric comparisons | — |
| `'currency'` | Pick from the store's currencies | — |
| `'locale'` | Pick from the store's languages | — |
| `'date'` | Date range picker (store-timezone aware) | — |
| `'enum'` | Fixed option list | `filterOptions: [{ value, label }]` (required) |
| `'resource'` | Multi-select autocomplete against another resource | `filterResource` (required) — `queryKey`, `search`, `hydrate`, `getOptionLabel` |
| `'tags'` | Tag autocomplete | `taggableType` (required), e.g. `'Spree::Product'` |
A `'resource'` filter searches as the admin types and resolves already-selected IDs back to labels on page reload:
```tsx
tables.products.addColumn({
key: 'brand_id',
label: 'Brand',
displayable: false, // filter only — no column in the table
filterable: true,
filterType: 'resource',
filterResource: {
queryKey: 'brands',
search: (query) => brandsClient.list({ q: { name_cont: query } }),
hydrate: (ids) => brandsClient.list({ q: { id_in: ids } }),
getOptionLabel: (brand) => brand.name,
},
})
```
Filtering and sorting are executed by the Admin API (Ransack), not in the browser — `key` (or `ransackAttribute`) must be a filterable/sortable attribute the API allows.
## Define your own table
For your own list page, declare the table once — typically right next to your `defineDashboardPlugin` call:
```tsx
import { defineTable } from '@spree/dashboard'
defineTable<Brand>('brands', {
title: 'Brands',
searchParam: 'search',
searchPlaceholder: 'Search by name…',
defaultSort: { field: 'name', direction: 'asc' },
emptyMessage: 'No brands yet',
columns: [
{ key: 'name', label: 'Name', sortable: true, filterable: true, default: true },
{ key: 'products_count', label: 'Products', default: true, className: 'text-right tabular-nums' },
{ key: 'created_at', label: 'Created', sortable: true, default: false },
],
})
```
Then render it from your page component:
```tsx
<ResourceTable<Brand>
tableKey="brands" // which table definition to read
queryKey="brands" // TanStack Query cache key
queryFn={(params) => brandsClient.list(params)}
searchParams={searchParams}
/>
```
`<ResourceTable>` handles pagination, sorting, the filter panel, column visibility, and URL round-tripping of all of it. See [Routes](/developer/dashboard/customization/routes) for the page around it — the [example Brands plugin](https://github.com/spree/spree/tree/main/packages/dashboard-plugin-example) shows the complete wiring.
## Bulk actions, row actions, reordering
These are **props on `<ResourceTable>`**, composed by the page that renders the table:
```tsx
<ResourceTable<Brand>
// …
bulkActions={[{ key: 'archive', label: 'Archive selected', onSelect: async (rows) => { /* … */ } }]}
rowActions={(row) => <BrandRowMenu brand={row} />}
/>
```
Use them freely on your own pages. They are **not registry-driven** — a plugin can't inject bulk or row actions into a built-in page's table today. If a built-in page needs an injection point, that's what [slots](/developer/dashboard/customization/slots) are for.
## Reference
- [`table-registry.ts`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/lib/table-registry.ts) — `defineTable`, `tables`, the full `ColumnDef` union
- [`<ResourceTable>`](https://github.com/spree/spree/blob/main/packages/dashboard-core/src/components/resource-table.tsx) — props for bulk actions, row actions, drag-reordering
- [Example Brands plugin](https://github.com/spree/spree/tree/main/packages/dashboard-plugin-example) — a real `defineTable` + `<ResourceTable>` + products-column extension