# Coding agents (https://react-datatable.com/docs/coding-agents)

`react-datatable` works well with coding agents because the table is installed as normal source code inside your app.

After installation, agents can inspect the table implementation, your product code, your column definitions, your custom cells, and your tests in one repository. They do not need to treat the table as a black-box framework boundary.

<ImageZoom src="/docs-media/overview/agentic-development-coding-agent-workflow.png" alt="A coding agent workflow showing a prompt about react-datatable docs and integration work, with an agent picker open beside the conversation." className="my-7 w-full rounded-xs border-0" />

## Give the agent the docs entrypoint [#give-the-agent-the-docs-entrypoint]

When you want an agent to install or modify the table, give it the documentation index first:

* [llms.txt](/docs/llms.txt) for a compact map of the docs
* [llms-full.txt](/docs/llms-full.txt) for the expanded docs corpus

That gives the agent the current install flow, component API, examples, and feature guides without requiring it to browse the site page by page.

## Install with an agent [#install-with-an-agent]

For a new app, keep the prompt direct:

```txt
Read https://react-datatable.com/docs/llms.txt, then install react-datatable into this app with:

npx @react-datatable/cli install --token <license-token>

After installation, render a CustomersTable with static rows, stable column IDs, and getRowId. Run the relevant typecheck or build before you finish.
```

For an existing table, name the product task instead of describing the table from scratch:

```txt
Read https://react-datatable.com/docs/llms-full.txt. In the customers table, add a Plan column with a text-list filter and keep the row height stable for virtualization. Use the existing column patterns and run the smallest relevant check.
```

## Good agent tasks [#good-agent-tasks]

Agents are useful for focused integration work:

* installing the source into a framework app
* adding or refining columns
* creating custom cells
* wiring an online query function to your API route
* adding current-view persistence, URL sync, or saved views
* adapting toolbar, preview, row, or cell UI to your product

They are also useful after installation because the copied source is local. The agent can follow the implementation instead of guessing at hidden package behavior.

## What to verify [#what-to-verify]

Pick the smallest check that matches the change:

<PackageManagerCommandTabs
  commands="{
  pnpm: `pnpm test
pnpm run typecheck
pnpm run build:local-basic
pnpm run build:online-basic
pnpm run test:copy-kit`,
  npm: `npm test
npm run typecheck
npm run build:local-basic
npm run build:online-basic
npm run test:copy-kit`,
  yarn: `yarn test
yarn typecheck
yarn build:local-basic
yarn build:online-basic
yarn test:copy-kit`,
  bun: `bun test
bun run typecheck
bun run build:local-basic
bun run build:online-basic
bun run test:copy-kit`,
}"
/>

For visual changes, also inspect the affected table in the browser. For behavior changes, ask the agent to name which table state or API contract changed.

## Where to go next [#where-to-go-next]

Install the source from [Installation](/docs/installation), then render the first table in [Getting started](/docs/quickstart/getting-started).


# Data loading (https://react-datatable.com/docs/concepts/data-loading)

Data loading is the question of **who owns the row set after the user changes the table**.

The visible table can look the same in every mode. Search, filters, sorting, grouping, selection, preview, and display controls still belong to the table surface. What changes is where the final rows come from.

## Local Data [#local-data]

Use local data when the browser can hold and transform the full working set.

```tsx
<Datatable tableKey="customers" columns={columns} data={rows} getRowId={(row) => row.id} />
```

In this mode, the table receives rows through `data` and applies search, filters, sorting, and grouping in the browser.

This is the simplest model. It is a good fit for:

* small and medium datasets
* route loaders that already fetched the rows
* tables where client-side filtering is enough
* prototypes before the backend contract is final

## Online Data [#online-data]

Use online data when the server owns the result set.

In this mode, the table turns its current state into a query and asks your backend for rows. The query includes the things users changed: filters, sorting, search, grouping, and navigation.

```txt
table state -> online query -> backend result -> visible rows
```

This is the right model when:

* the dataset is too large for the browser
* permissions must be enforced on the backend
* totals, facets, or grouped results must match server truth
* the table should load page by page or window by window

The table owns the interaction. Your backend owns which rows match.

## Pagination and Infinite Scroll [#pagination-and-infinite-scroll]

Online mode still needs a navigation style.

**Pagination** gives users explicit pages. Use it for back-office workflows where totals, page size, and repeatable navigation matter.

**Infinite scroll** treats the result as one long sequence. Use it when the product should feel continuous and the user is browsing through many matching rows.

Both styles use the same table state. They only differ in how the next server window is requested.

## Rendering Is Separate [#rendering-is-separate]

Virtualization is not a data-loading mode.

Data loading decides **which rows are available**. Virtualization decides **how many available rows are mounted in the DOM**.

That means:

* local tables can be virtualized
* paginated tables can be virtualized
* infinite tables can be virtualized
* virtualization does not replace a backend query model

Keeping those ideas separate makes the API easier to reason about.

## First Paint [#first-paint]

If your route already loaded the first server result, pass it as initial online data. The table can use it for first paint as long as it matches the resolved table state.

This matters because saved views, persistence, and URL state can change the opening query. The table should not keep prefetched rows for the wrong filters or sorting.

## Use This Rule [#use-this-rule]

Choose the data mode by ownership:

* browser owns the row set: use local data
* server owns the row set: use online data
* the question is DOM size, not row ownership: use virtualization

## Next Steps [#next-steps]

* Choose a practical mode in [Choose a data mode](/docs/guides/choose-a-data-mode).
* Review the exact server contract in [Online API](/docs/reference/online-api).
* Tune rendering in [Tune virtualization](/docs/guides/tune-virtualization).


# Persistence and Sharing (https://react-datatable.com/docs/concepts/persistence-and-sharing)

Tables need memory, but not all memory means the same thing.

`react-datatable` separates remembered state into three concepts:

* private persistence
* saved views
* URL sharing

They can store similar table state, but they have different product meanings.

## Private Persistence [#private-persistence]

Private persistence answers: **continue where I left off**.

It quietly remembers one user's current table setup. That can include filters, sorting, grouping, visible columns, column order, sizing, and the active view.

A typical case is a team meeting. You filter the customers table, scroll to the right area, and open one customer to discuss the details on a separate route. When you press the browser back button, you expect to return to the same filtered table, at the same page and scroll position, without rebuilding the context by hand.

In `react-datatable`, persisted table state restores the filter and layout context. Runtime restoration uses the same table identity to bring back pagination and scroll position during SPA navigation.

This should feel automatic. The user does not name anything. They return to the table and it feels familiar.

Use persistence for personal working state.

## Saved Views [#saved-views]

Saved views answer: **take me back to this named setup**.

A saved view is deliberate. It has a name and can become part of the product workflow: "Renewals", "At risk accounts", "My open issues", or "Finance review".

Saved views can also support defaults:

* a workspace default for the team
* a user default for one person

Use saved views when a table setup should be reusable, named, or shared as a team convention.

## URL Sharing [#url-sharing]

URL sharing answers: **show someone this view right now**.

The URL should carry only the state needed to reproduce the meaningful view: usually search, filters, sorting, grouping, and filter mode.

It should not carry every personal display preference. A copied link should communicate the useful context, not another user's private workspace.

Use URL state for one-off sharing and deep links.

## The Difference [#the-difference]

Use this mental model:

| Feature     | Meaning                 | Visibility        |
| ----------- | ----------------------- | ----------------- |
| Persistence | Continue my work        | Private           |
| Saved views | Return to a named setup | Private or shared |
| URL state   | Open this exact context | Shared by link    |

This separation keeps the table predictable. A private preference should not accidentally become a team default. A shared link should not permanently change someone's remembered state.

## Defaults and Remembered State [#defaults-and-remembered-state]

Defaults are starting points. Persisted state is recent work.

If a user has no remembered state, a workspace or user default view can shape the first load. If they do have remembered state, the table should usually restore that instead.

Shared URL state still wins because opening a link is intentional.

## Copy Link vs URL Sync [#copy-link-vs-url-sync]

There are two ways to use URLs.

**Copy link** exports the current shareable state when the user asks for it. This is usually the calmer default for product tables.

**Continuous URL sync** keeps the address bar updated as the table changes. Use it when the URL itself is part of the product experience.

Both use the same idea: URLs carry shared context, not every private table preference.

## Use This Rule [#use-this-rule]

Put state in the place that matches its meaning:

* personal and automatic: persistence
* named and reusable: saved views
* portable and temporary: URL sharing

## Next Steps [#next-steps]

* See startup precedence in [State Lifecycle](/docs/concepts/state-lifecycle).
* Configure private memory in [Add current-view persistence](/docs/guides/add-current-view-persistence).
* Configure named views in [Add saved views](/docs/guides/add-saved-views).
* Configure links in [Add copy links](/docs/guides/add-copy-links) and [Add URL sync](/docs/guides/add-url-sync).


# State Lifecycle (https://react-datatable.com/docs/concepts/state-lifecycle)

The table can receive state from several places. It may have product defaults, saved views, persisted user state, and URL parameters all available at the same time.

The lifecycle exists so those sources produce **one opening state**, not a series of visible jumps.

## The Startup Problem [#the-startup-problem]

On first load, these sources may all have an opinion:

* built-in defaults
* `initialState`
* workspace default view
* user default view
* persisted current state
* URL state from a shared link

If they apply one by one as they load, the table can briefly show the wrong filters, the wrong active view, or the wrong first server query.

## The Startup Flow [#the-startup-flow]

The table uses a simple sequence:

```txt
load candidate state
        ↓
merge one initial state
        ↓
render the ready table
        ↓
start ongoing sync
```

The important part is that ongoing sync starts after the opening state is resolved. Persistence and URL sync should not write temporary mount state back into storage.

## Priority [#priority]

When multiple sources exist, later sources win:

```txt
defaults
  -> initialState
  -> workspace default view
  -> user default view
  -> persisted current state
  -> URL state
```

This priority keeps each source in its expected role.

Workspace defaults provide a team baseline. User defaults personalize that baseline. Persisted state restores where someone left off. URL state wins because opening a shared link is an explicit action.

## Why Persisted State Beats Defaults [#why-persisted-state-beats-defaults]

Defaults are starting points. Persisted state is recent work.

If a user already has remembered state for a table, reopening that table should continue from their last working setup instead of resetting to a default view.

Defaults matter most the first time someone opens a table, or after remembered state is cleared.

## Why URL State Wins [#why-url-state-wins]

A copied link should be predictable.

If a link says "show customers filtered by Enterprise and sorted by renewal date", the recipient should see that view even if they have their own stored table preferences.

That is why URL state is applied last during startup.

## Online Data Depends on This [#online-data-depends-on-this]

For online tables, opening state is also the first query.

The table should resolve state first, then ask the backend for rows. Otherwise the user can see a loading flash for a query that was never the intended view.

## Use This Rule [#use-this-rule]

Think of startup state as a coordinated handoff:

* collect all state sources
* choose one initial state
* render from that state
* then allow persistence, URL sync, and view dirty-state behavior to continue

## Next Steps [#next-steps]

* Learn how memory is divided in [Persistence and Sharing](/docs/concepts/persistence-and-sharing).
* Add private state memory in [Add current-view persistence](/docs/guides/add-current-view-persistence).
* Add shareable links in [Add URL sync](/docs/guides/add-url-sync).


# Table anatomy (https://react-datatable.com/docs/concepts/table-anatomy)

This page names the main parts of a react-datatable table: the toolbar, applied state bar, grid, preview panel, bulk actions, and footer. Use it when you want to point at a specific part of the table without having to say "that thing above the rows" or "the menu near the right edge."

<ImageZoom src="/docs-media/concepts/table-anatomy/table-anatomy-overview.png" alt="An annotated full-table anatomy view showing the toolbar, applied state bar, grid, view-columns button, bulk action island, floating preview panel, and pagination footer." className="my-7 w-full rounded-xs border-0" />

## How the table is put together [#how-the-table-is-put-together]

In the source, `DataTableBody` brings the visible table regions together:

* the toolbar
* the applied state bar
* the grid itself
* optional visibility and bulk-selection affordances
* optional preview and pagination surfaces

Those pieces work as one table, but each part has its own job. Naming them makes product discussions clearer: "change the toolbar" means something different from "change the applied state bar" or "change the grid."

## 1. Toolbar [#1-toolbar]

The toolbar is the top control row rendered by `DataTableToolbar`. It gives users a place to start table-wide changes before they enter the grid itself.

Depending on configuration, the toolbar can include:

* **Quick search** for global text search
* **Filter button** for column-filter workflows
* **Views dropdown** for saved views
* **Display options button** for presentation controls
* **Copy link** for sharing the current table state

On narrower layouts, the same controls wrap into multiple rows, but they are still the same toolbar region.

## 2. Applied state bar [#2-applied-state-bar]

Directly under the toolbar, `DataTableAppliedFilters` renders the applied state bar. This region shows the state that is currently affecting the result set or presentation, especially:

* active filters
* active sorting chips when ordering badges are visible

This matters because react-datatable separates **choosing state** from **seeing what state is active**. A user may open filtering from the toolbar, apply several filters, and then manage or clear those filters from the applied state bar. That makes the bar part of the table's visible feedback loop.

<ImageZoom src="/docs-media/concepts/table-anatomy/table-anatomy-toolbar-and-applied-state-bar.png" alt="A detail view of the toolbar and applied state bar showing quick search, filter controls, active state chips, views, display options, and copy-link actions." className="my-7 w-full rounded-xs border-0" />

## 3. Grid [#3-grid]

The grid is the main scrolling table region rendered through `VirtualizedGrid`. This is where users read rows, compare values, sort from headers, resize columns, navigate with the keyboard, and interact with grouped or selected rows.

The grid region includes several important sub-areas:

* **Column headers** for labels, sort affordances, and resize handles
* **Data rows** for the primary record surface
* **Group rows** when grouping is active
* **Selection column** when row selection is enabled
* **Sticky or frozen columns** when left columns stay pinned during scroll

The grid is the central region of the product, with support behaviors living around it.

<ImageZoom src="/docs-media/concepts/table-anatomy/table-anatomy-grid.png" alt="A grid detail view showing the selection column, sticky columns, column headers, data rows, and grouped rows." className="my-7 w-full rounded-xs border-0" />

## 4. View-columns button [#4-view-columns-button]

When enabled, the **view-columns button** is the `+` control pinned near the right edge of the grid. It is a fast column-visibility affordance for people who are already working inside the table and want to change visible columns without reopening the toolbar flow.

Treat it as a companion to display options, not a separate visibility system.

<ImageZoom src="/docs-media/concepts/table-anatomy/table-anatomy-view-columns-button.png" alt="A detail view of the view-columns control and column visibility panel near the right edge of the table." className="my-7 w-full rounded-xs border-0" />

## 5. Bulk action island [#5-bulk-action-island]

When selection is enabled and rows are selected, `BulkActionIsland` appears above the table content. This region has one job: turn selection into action.

It typically shows:

* the selected count
* a clear-selection action
* the trigger that opens the bulk action dialog

The island only appears when it is relevant. That makes it a contextual surface rather than a permanent part of the layout.

<ImageZoom src="/docs-media/concepts/table-anatomy/table-anatomy-bulk-action-island.png" alt="A detail view of the bulk action island with selected-row state and the bulk action dialog open." className="my-7 w-full rounded-xs border-0" />

## 6. Floating preview panel [#6-floating-preview-panel]

When row preview is enabled and open, `FloatingPreview` renders a floating panel above the main table layout. This region is for lightweight inspection without leaving the current table context.

A few anatomy details matter here:

* it is an overlay, not part of the grid flow
* it can persist position in session storage when configured with a table key
* it is separate from row selection and separate from full row navigation

That separation is useful language during product work: "open the preview" means something different from "select the row" or "open the record page."

<ImageZoom src="/docs-media/concepts/table-anatomy/table-anatomy-floating-preview-panel.png" alt="A detail view of the floating preview panel opened over the table for a selected record." className="my-7 w-full rounded-xs border-0" />

## 7. Pagination footer or loading footer [#7-pagination-footer-or-loading-footer]

In online pagination mode, the footer below the grid becomes the pagination surface. This region includes:

* page-size selection
* current range summary
* previous and next controls
* direct page navigation

In other data modes, the lower edge of the table may instead express loading, empty, or virtual scrolling behavior. The important anatomy idea is that navigation and result-range feedback live below the grid, not inside the toolbar.

<ImageZoom src="/docs-media/concepts/table-anatomy/table-anatomy-pagination-footer.png" alt="A detail view of the pagination footer showing page size, result range, previous and next navigation, and direct page controls." className="my-7 w-full rounded-xs border-0" />

## How these regions work together [#how-these-regions-work-together]

A typical workflow crosses several regions:

1. start in the toolbar with search, filters, views, or display options
2. confirm active state in the applied state bar
3. inspect or manipulate rows in the grid
4. branch into contextual regions like bulk actions, preview, or pagination when needed

That flow is why the docs treat react-datatable as one coordinated table surface rather than a standalone grid plus unrelated extras.

## Where to go next [#where-to-go-next]

* For row ownership and server-backed tables, read [Data loading](/docs/concepts/data-loading).
* For first-render state precedence, read [State Lifecycle](/docs/concepts/state-lifecycle).
* For implementation detail on a specific region, continue into the relevant Guides pages such as [Add global search](/docs/guides/add-global-search), [Configure display options](/docs/guides/configure-display-options), [Add row selection](/docs/guides/add-row-selection), or [Add row preview](/docs/guides/add-row-preview).


# Custom React cells (https://react-datatable.com/docs/customization/custom-react-cells)

Custom React cells are the main customization tool for changing **how a field renders** without changing **how the table works**.

Use them after the column contract is already clear.

<MediaPlaceholder title="Custom cell examples in a live table">
  Show one realistic table with a linked company cell, status badge, owner/avatar cell, and row action menu visible together.
</MediaPlaceholder>

## Custom cells sit on top of the column contract [#custom-cells-sit-on-top-of-the-column-contract]

A custom cell extends the column definition.

The column still decides the durable behavior:

* the stable column ID
* the underlying value source
* filter and sort behavior
* grouping support
* saved-state compatibility

The custom cell decides how that field should appear in the product UI.

That distinction keeps rendering and behavior predictable.

## Reach for a custom cell when plain text stops being enough [#reach-for-a-custom-cell-when-plain-text-stops-being-enough]

Custom cells are a good fit when the product needs a field to:

* combine several row fields into one surface
* link to a detail page
* show badges, icons, avatars, or status treatments
* expose a small inline action
* reflect workflow meaning instead of only raw stored values

If the column behavior is wrong, fix the column contract first. If the behavior is right but the UI is too generic, a custom cell is usually the right layer.

## The renderer receives row and value context [#the-renderer-receives-row-and-value-context]

`DatatableColumn` supports a `cell` renderer using the TanStack-style cell context.

```tsx
import type { DatatableColumn } from "./react-datatable"

type Customer = {
  id: string
  company: string
  owner: string
  tier: "free" | "pro" | "enterprise"
}

const columns: DatatableColumn<Customer>[] = [
  {
    id: "company",
    accessorKey: "company",
    header: "Company",
    filterType: "text",
    cell: ({ row, getValue }) => (
      <a href={"/customers/" + row.original.id}>
        {String(getValue())}
      </a>
    ),
  },
]
```

For simple formatting, `getValue()` is often enough. For richer domain UI, `row.original` is usually the real source of truth.

## Use `row.original` for multi-field product UI [#use-roworiginal-for-multi-field-product-ui]

Many useful cells render small row summaries instead of a single field value.

```tsx
cell: ({ row }) => (
  <div className="min-w-0">
    <div className="font-medium">{row.original.company}</div>
    <div className="text-muted-foreground text-sm">{row.original.owner}</div>
  </div>
)
```

This is the normal pattern when one visual cell needs several row attributes.

The important part is to keep the *behavioral* column identity stable even when the rendered UI becomes richer.

## Keep expensive work outside the renderer [#keep-expensive-work-outside-the-renderer]

Cells run in the hottest rendering path of the table.

That means the best custom cells are visually rich but computationally boring.

Good pattern:

```tsx
const money = new Intl.NumberFormat("en", {
  style: "currency",
  currency: "USD",
  maximumFractionDigits: 0,
})

cell: ({ row }) => money.format(row.original.arr)
```

Less healthy pattern:

* creating formatters on every render
* doing heavy synchronous transforms inside the cell
* deriving large view models repeatedly during scroll
* making network calls from cells

A cell should usually render quickly from data that is already available.

## Interactive cells need to cooperate with the table [#interactive-cells-need-to-cooperate-with-the-table]

Buttons, menus, toggles, and links are valid reasons to use custom cells, but they need extra care.

```tsx
cell: ({ row }) => (
  <button aria-label={"Open actions for " + row.original.company}>
    Actions
  </button>
)
```

When a cell becomes interactive, check that it still coexists cleanly with:

* row selection
* keyboard navigation
* row preview/open-row actions
* focus order
* accessibility labeling

A good custom cell adds product interaction without making the grid feel unpredictable.

## Not every rich row detail belongs in a cell [#not-every-rich-row-detail-belongs-in-a-cell]

Custom cells are great for compact, high-signal UI.

They are usually the wrong place for:

* long descriptions
* activity feeds
* complex forms
* large stacks of actions
* detail views that need sustained attention

Those heavier experiences generally belong in row preview surfaces or detail routes.

<Callout title="Use preview for heavier detail">
  If a design asks one row cell to act like a mini detail page, that is usually a sign the information should move into preview UI or an open-row flow instead.
</Callout>

## Preserve predictable row height when possible [#preserve-predictable-row-height-when-possible]

The table uses virtualization, so custom cells should avoid wildly unstable vertical layout.

A cell can be visually expressive without becoming layout-chaotic.

Prefer:

* compact stacked text
* known-size icons, badges, and avatars
* concise action surfaces
* predictable wrapping rules

Be careful with:

* unbounded text blocks
* async content that changes height dramatically after render
* large controls that make one row much taller than its neighbors

## Keep customization local to presentation [#keep-customization-local-to-presentation]

A helpful principle is:

* use the column contract to define behavior
* use the custom cell to define presentation
* use row presentation hooks to define state-aware styling

That separation keeps a custom cell from becoming a hidden place where filtering rules, row state, and styling logic all pile up together.

## Accessibility checklist for custom cells [#accessibility-checklist-for-custom-cells]

Before you call a custom cell done, check that:

* links and buttons have clear text or `aria-label`
* icon-only controls are still understandable
* focusable elements can be reached by keyboard
* the content still makes sense without color alone
* inline controls do not accidentally block normal table navigation

## Use this litmus test [#use-this-litmus-test]

A good custom cell should answer yes to both questions:

1. **Does this make the product table easier to understand or use?**
2. **Would the table still behave predictably if this cell were duplicated across hundreds of rows?**

If the second answer is no, the UI may be too heavy for a cell surface.

## Where to go next [#where-to-go-next]

* For the behavioral contract underneath the renderer, read [Define columns](/docs/guides/define-columns).
* For the higher-level layer map, read [Customization overview](/docs/customization/customization-overview).
* For copyable renderer patterns, read [Custom cells gallery](/docs/examples/custom-cells-gallery).
* For heavier per-row detail, read [Add row preview](/docs/guides/add-row-preview) now and the preview customization page once it lands.


# Customization overview (https://react-datatable.com/docs/customization/customization-overview)

Customization in `react-datatable` works through a set of boundaries for shaping the table to a product while keeping the core interaction model intact.

This page explains those boundaries.

## The table is meant to be adapted, not treated as a sealed widget [#the-table-is-meant-to-be-adapted-not-treated-as-a-sealed-widget]

`react-datatable` lives as source in your repository.

That changes the customization story.

You are not limited to a tiny theme API or a fixed plugin marketplace. You can:

* define product-specific columns
* render custom React cells
* style rows and cells from table state
* wire previews, actions, and persistence to your product model
* extend the copied source when a product need truly sits below the public surface

The goal is **clear layers of customization**.

## Start by deciding which layer the change belongs to [#start-by-deciding-which-layer-the-change-belongs-to]

Most table changes fall into one of these layers:

1. **column contract** — what the field means and how the table behaves around it
2. **rendering layer** — how cells and rows look in the product
3. **presentation hooks** — how interaction state affects styling and DOM attributes
4. **integration layer** — how the table connects to previews, routes, persistence, or product workflows
5. **source-level extension** — deeper changes inside copied table code when the public surface is not enough

If you choose the wrong layer, the table can still work, but it usually becomes harder to reason about.

## Column definition is the first customization layer [#column-definition-is-the-first-customization-layer]

The most important customization work usually starts before any fancy rendering.

A column definition decides:

* the stable column ID
* the data the table reads from
* whether the column sorts or groups
* which filter UI the column should use
* what cell renderer should appear

That means column definition is the product contract between your domain data and the table's behavior.

If this layer is weak, later cell customization tends to compensate for missing structure instead of building on a clean foundation.

## Custom React cells are for product-specific rendering [#custom-react-cells-are-for-product-specific-rendering]

Once the column contract is solid, custom cells let the product speak in its own UI language.

Use them when a cell needs to:

* combine multiple fields
* show badges, icons, menus, or inline actions
* link to a detail page
* communicate workflow-specific meaning instead of raw values

This is the right layer for *how a field should render*, not for re-implementing table mechanics.

A helpful rule is: let the table own filtering, sorting, grouping, and navigation; let the custom cell own domain-specific presentation.

## Row presentation hooks are for state-aware styling, not data modeling [#row-presentation-hooks-are-for-state-aware-styling-not-data-modeling]

Some customization needs focus on how the table should look when state changes.

`rowPresentation` exists for that layer.

It lets product code react to table-owned interaction state such as:

* selection
* active-row focus
* preview-open state
* group-header versus data-row status

Use this layer when ordinary CSS selectors are not enough and the product needs stable classes or `data-*` attributes derived from table state.

That is different from custom cells:

* **custom cells** shape the rendered content inside a column
* **presentation hooks** shape styling and attributes around row/cell state

## Preview, actions, and product flows belong at the integration layer [#preview-actions-and-product-flows-belong-at-the-integration-layer]

Many product teams first think of customization as visual work, but a lot of important table adaptation is behavioral integration.

For example:

* opening a record detail route
* toggling a preview panel
* attaching analytics-safe row attributes
* connecting persistence or views to workspace/user identity

These are product-level behaviors that sit *around* the table.

The table provides structure and state for them, but your application decides what those actions actually mean.

## Customization should preserve core table responsibilities [#customization-should-preserve-core-table-responsibilities]

A good customization keeps the table's underlying responsibilities recognizable.

The table should still own things like:

* row and column state coordination
* filtering and sorting behavior
* keyboard navigation semantics
* virtualization and rendering performance boundaries
* persistence and URL state rules

If a customization begins to rewrite those concerns indirectly from a cell renderer or ad hoc CSS, that is usually a sign the change belongs in a deeper layer.

## Source ownership gives you one more escape hatch [#source-ownership-gives-you-one-more-escape-hatch]

Because the table source is local, there is a final layer available when the public surfaces are not enough.

That can be the right choice for changes like:

* a new reusable column or renderer primitive
* a new adapter capability
* a bug fix in state coordination
* a product-specific extension that should live near the table internals

But this layer should be used deliberately.

Source-level edits are powerful because they happen close to the real behavior. They are also riskier because they can blur the distinction between product integration and core mechanics.

## Use this decision guide [#use-this-decision-guide]

When deciding how to implement a change, ask:

### Is this about what the field means? [#is-this-about-what-the-field-means]

Use column definition.

### Is this about how the field should render? [#is-this-about-how-the-field-should-render]

Use a custom cell.

### Is this about styling rows or cells from interaction state? [#is-this-about-styling-rows-or-cells-from-interaction-state]

Use row presentation hooks.

### Is this about opening product workflows or storing product state? [#is-this-about-opening-product-workflows-or-storing-product-state]

Use the integration surfaces around the table.

### Is the public surface genuinely insufficient? [#is-the-public-surface-genuinely-insufficient]

Then consider editing the copied source directly.

## What good customization looks like [#what-good-customization-looks-like]

The best customized tables feel product-specific while keeping table behavior coherent.

They usually share three traits:

* the column contract stays stable and explicit
* product-specific rendering lives in the right UI layer
* deeper source changes happen intentionally, with narrow scope

<Callout title="Think in boundaries, not hacks">
  When a customization request arrives, the most useful first question is usually not "can the table do this?" It is "which layer should own this?" That question tends to produce cleaner APIs, clearer docs, and less fragile product code.
</Callout>

## Where to go next [#where-to-go-next]

* For the behavioral contract of fields, read [Define columns](/docs/guides/define-columns).
* For product-specific cell rendering, read [Custom React cells](/docs/customization/custom-react-cells).
* For state-aware styling, read [Styling rows and cells](/docs/customization/styling-rows-and-cells).


# Customizing filter UI (https://react-datatable.com/docs/customization/customizing-filter-ui)

Use this page when the default filtering behavior is right, but the filtering **surface** still needs to feel more like your product.

The safest path is to customize the existing filter experience first, then replace deeper UI only when the shipped surface no longer matches the workflow.

<MediaPlaceholder title="Filter button plus popover with product-specific filter labels and options">
  Show the toolbar filter button, searchable filter list, text-list/date submenus, and applied chips using realistic product wording.
</MediaPlaceholder>

## Start by separating filter behavior from filter UI [#start-by-separating-filter-behavior-from-filter-ui]

A useful boundary is:

* the **column contract** decides which fields are filterable and what filter types they use
* the **filter UI** decides how those filters are presented to the user
* the **backend or local row model** decides how filter payloads actually affect results

That means many product-specific filter changes do **not** require replacing core filtering logic.

## Customize the names users see first [#customize-the-names-users-see-first]

The filter picker uses the column's filter-facing name before it falls back to the header.

That makes `meta.filterName` the first place to tune the labels shown in the interface.

```tsx
const columns: DatatableColumn<Customer>[] = [
  {
    id: "owner",
    accessorKey: "ownerName",
    header: "Owner",
    filterType: "text-list",
    meta: {
      filterName: "Account owner",
    },
    filterOptions: {
      options: owners.map((owner) => ({ value: owner.id, label: owner.name })),
    },
  },
]
```

Use this when the visible header is short but the filter picker needs clearer task-oriented language.

## Use filter icons and option labels to match product language [#use-filter-icons-and-option-labels-to-match-product-language]

The built-in filter list also supports column-level icon and label customization through metadata and options.

```tsx
{
  id: "status",
  accessorKey: "status",
  header: "Status",
  filterType: "text-list",
  meta: {
    filterName: "Customer status",
    filterIcon: StatusIcon,
  },
  filterOptions: {
    options: [
      { value: "active", label: "Active customer" },
      { value: "trial", label: "Trial account" },
      { value: "paused", label: "Paused" },
    ],
  },
}
```

This is usually enough to make the filter surface feel product-aware without touching the underlying components.

For option-list filters, option rows can also render custom React. Use `filterOptions.renderOption` when a plain label is not enough:

```tsx
{
  id: "owner",
  accessorFn: (row) => row.owner.name,
  header: "Owner",
  filterType: "text-list",
  filterOptions: {
    options: owners.map((owner) => ({ value: owner.name, label: owner.name })),
    renderOption: (option) => {
      const owner = owners.find((item) => item.name === option.value)

      return (
        <>
          {owner ? <OwnerAvatar owner={owner} /> : null}
          <span className="truncate">{option.label}</span>
        </>
      )
    },
  },
}
```

This only changes option presentation. Filtering still uses the selected option values. `renderOption` is available for `text-list`, `id-list`, and `boolean` filters.

## Pick filter types that produce the UI you want [#pick-filter-types-that-produce-the-ui-you-want]

The built-in filter picker currently branches by `filterType`.

In practice that means:

* `text` and `number` open through the modal editor flow
* `text-list` and `date` open through inline submenu editors
* only implemented filter types appear in the searchable filter list

If you want a compact pick-list experience, `text-list` is often the best fit. If you want freeform matching, use `text`. If you want range or comparison editing, use `number` or `date`.

The UI shape is part of the filter-type choice, not just the backend payload choice.

## Keep the toolbar entry point aligned with the table's scope [#keep-the-toolbar-entry-point-aligned-with-the-tables-scope]

The toolbar's filter button is the main entry point for column filtering.

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  data={rows}
  toolbar={{
    filterButton: true,
    appliedState: {
      showFilters: true,
    },
  }}
/>
```

If you turn on filtering, leave applied chips visible unless the table is intentionally minimalist. The built-in experience works best when users can both **open** filters and **see** active filters in the same surface.

## Use applied chips as part of the UI design, not an afterthought [#use-applied-chips-as-part-of-the-ui-design-not-an-afterthought]

Filter UI includes both the editor and the visible state it leaves behind.

The applied-state bar is where users confirm, remove, and compare active filters over time.

That means filter customization should include:

* clear filter names
* human-readable option labels
* a toolbar layout that leaves enough room for the applied-state bar to matter

If the filter picker is polished but the applied chips are confusing, the experience still feels unfinished.

## Use the shipped UI when it is enough [#use-the-shipped-ui-when-it-is-enough]

The default filter UI is a good fit when you need to customize:

* filter labels
* icons
* option-list labels
* option-list rows with `renderOption`
* which columns appear in the picker
* whether filter chips are visible

In those cases, stay within the built-in surface. It is cheaper, more consistent, and easier to maintain.

## Move from configuration to replacement when you need to [#move-from-configuration-to-replacement-when-you-need-to]

You are probably beyond simple configuration when the product needs:

* a radically different filter workflow than the searchable picker
* custom editors for filter types the built-in UI does not implement
* filter controls embedded somewhere other than the toolbar/applied-state pattern
* a domain-specific interaction model that does not map cleanly to the current modal/submenu flows

At that point, you are designing a different filtering product surface.

## Be honest about partially implemented filter types [#be-honest-about-partially-implemented-filter-types]

The type system includes `custom`, but the built-in UI is strongest for:

* `text`
* `text-list`
* `number`
* `date`
* `boolean`
* `id-list`

Treat `custom` as an extension seam unless you are also building the editor experience yourself.

<Callout title="Do not promise more UI than the shipped components provide">
  If a filter type exists in TypeScript but not in the actual picker/editor flow your users see, document it as an extension point rather than implying it is turnkey.
</Callout>

## Use this customization ladder [#use-this-customization-ladder]

When filter UI needs work, move in this order:

1. choose better `filterType` values
2. improve `meta.filterName`, `meta.filterIcon`, and option labels
3. tune which columns are filterable at all
4. keep applied chips visible and understandable
5. only then consider replacing deeper UI components

That sequence usually gets the product where it needs to go with much less complexity.

## Verify the filter surface in context [#verify-the-filter-surface-in-context]

Before you call the filter UI done, check that:

* the filter picker uses the words your users expect
* list-style filters have clear human labels
* the modal versus submenu behavior matches the kind of question each filter asks
* active chips are understandable after the picker closes
* the UI does not imply support for filter types you have not actually implemented

## Where to go next [#where-to-go-next]

* For adding filter behavior itself, read [Add column filters](/docs/guides/add-column-filters).
* For the surrounding surface where the filter button lives, read [Table anatomy](/docs/concepts/table-anatomy).
* For the broader customization layer map, read [Customization overview](/docs/customization/customization-overview).


# Customizing preview UI (https://react-datatable.com/docs/customization/customizing-preview-ui)

Use this page when basic row preview already works, but the **panel surface and interaction model** still need to match your product.

Preview customization is about making inspection feel intentional: light when it should stay in-table, heavier only when the workflow really needs it.

<MediaPlaceholder title="Preview panel states, placement, and close affordance">
  Show one realistic table with the floating preview open, the close button visible, and a second annotation calling out the panel repositioned to avoid covering important columns.
</MediaPlaceholder>

## 1. Start by deciding what preview should do in your product [#1-start-by-deciding-what-preview-should-do-in-your-product]

Preview is for **inspection in place**.

That means a good preview usually helps users:

* check row details without leaving the grid
* compare nearby rows quickly
* confirm context before opening a full record

If the design really wants editing, multi-step actions, or route-level context, that is usually an `onOpenRow` job instead of a preview customization job.

## 2. Customize preview content through `renderPreview` [#2-customize-preview-content-through-renderpreview]

The first customization seam is the preview body itself.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  preview={{
    renderPreview: ({ row, rowId, close }) => (
      <CustomerPreviewCard customer={row} rowId={rowId} onClose={close} />
    ),
  }}
/>
```

`renderPreview` receives:

* `row` for the active record
* `rowId` for stable actions, analytics, or links
* `close()` so your preview content can dismiss the panel directly

This is the right place for product-specific summary UI, not for rewriting how preview state itself is managed.

## 3. Keep preview content denser than a full detail page [#3-keep-preview-content-denser-than-a-full-detail-page]

The built-in surface is a floating panel with a bounded width and height plus internal scrolling.

That makes it a strong fit for:

* summary fields
* owner, status, dates, and metadata
* a small cluster of focused actions
* short related context that helps the user decide what to do next

It is a weak fit for:

* long forms
* multi-step editing flows
* very wide comparison layouts
* content that only makes sense as a whole routed screen

A preview should feel like a fast inspection layer, not a cramped copy of the detail page.

## 4. Decide whether the floating panel should be draggable [#4-decide-whether-the-floating-panel-should-be-draggable]

`FloatingPreview.tsx` enables dragging by default.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  preview={{
    floating: {
      draggable: true,
      storageKey: "customers-preview",
    },
    renderPreview: ({ row }) => <CustomerPreviewCard customer={row} />,
  }}
/>
```

Use draggable preview when the panel may otherwise cover important table columns and users benefit from moving it out of the way.

Set `draggable: false` when:

* the table sits in a tightly controlled layout
* consistency matters more than user-controlled placement
* dragging would compete with another interaction model on the page

## 5. Use `storageKey` deliberately [#5-use-storagekey-deliberately]

The floating preview position is stored in `sessionStorage` when a stable key exists.

The current implementation uses:

* `preview.floating.storageKey` if you provide one
* otherwise the top-level `tableKey`

That is a useful default, but it is still a product decision.

Give the preview its own `storageKey` when the panel position should stay stable across visits to the same table workflow. Skip that persistence when preview placement is not important enough to preserve.

## 6. Preview open/close state is transient [#6-preview-openclose-state-is-transient]

The panel position can persist. The fact that a row is currently open in preview should not be treated like saved table state.

That boundary matters.

Preview visibility reflects what the user is inspecting *right now*. It is not part of a durable layout contract like filters, sorting, or views.

If a product wants deep-linkable inspection state, that is usually a route or URL-state design question, not ordinary preview customization.

## 7. Customize preview behavior without blurring it with row navigation [#7-customize-preview-behavior-without-blurring-it-with-row-navigation]

The grid already treats preview as part of row interaction:

* clicking a data row can open preview when preview is configured
* `Space` can toggle preview from the active row
* `Esc` closes preview before clearing broader interaction state
* keyboard movement can carry preview along with the active row

These defaults are useful, but they need to fit the product workflow.

If users cannot tell whether a row click means preview, selection, or navigation, the product needs a clearer interaction contract before more UI polish will help.

## 8. Use `onTogglePreviewRow` for product side effects, not the preview body [#8-use-ontogglepreviewrow-for-product-side-effects-not-the-preview-body]

If the product needs analytics or side effects around preview activity, use `rowActions.onTogglePreviewRow`.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  rowActions={{
    onTogglePreviewRow: ({ rowId, nextOpen }) => {
      trackPreviewToggle(rowId, nextOpen)
    },
  }}
  preview={{
    renderPreview: ({ row }) => <CustomerPreviewCard customer={row} />,
  }}
/>
```

This keeps instrumentation and workflow hooks at the row-action boundary instead of burying them inside the preview content component.

## 9. Source-level preview customization starts with `FloatingPreview.tsx` [#9-source-level-preview-customization-starts-with-floatingpreviewtsx]

When prop-level customization is not enough, the narrow source seam is `features/preview/FloatingPreview.tsx`.

That is the right place to change things like:

* the panel chrome
* close affordance styling
* header layout
* container sizing
* drag-handle treatment
* the outer shell around your `renderPreview` content

Be more careful when changing:

* viewport clamping
* persistence behavior
* drag math
* open/close semantics
* keyboard expectations tied to preview state

Those behaviors shape how the table feels, not just how the panel looks.

<Callout title="Change the shell before the rules">
  If the product only needs a different preview presentation, keep the existing preview state model and replace the panel shell first. That is the safer customization seam.
</Callout>

## 10. Review preview in the real table context [#10-review-preview-in-the-real-table-context]

Before you call preview customization done, check that:

* the content helps inspection without turning into a mini app
* the panel does not cover critical table data in a frustrating way
* dragging and stored position behave predictably when enabled
* the close affordance is obvious and easy to reach
* `Space` and `Esc` still make sense in the overall row workflow
* row click, selection, preview, and full navigation still feel distinct

## Where to go next [#where-to-go-next]

* For the initial feature wiring, read [Add row preview](/docs/guides/add-row-preview).
* For the broader map of customization layers, read [Customization overview](/docs/customization/customization-overview).
* For the lighter row-level rendering layer before preview, read [Custom React cells](/docs/customization/custom-react-cells).
* For deeper source edits to shipped surfaces, read [Replacing built-in UI elements](/docs/customization/replacing-built-in-ui-elements).


# Customizing saved view UI (https://react-datatable.com/docs/customization/customizing-saved-view-ui)

Use this guide when saved views are the right feature, but the shipped dropdown and dialogs still need to match your product language and collaboration model.

<MediaPlaceholder title="Views dropdown plus create, rename, and share dialogs">
  Show the views trigger with an active view selected, the dirty-state dot visible, separate Private and Workspace sections in the dropdown, and focused crops of the create and rename dialogs.
</MediaPlaceholder>

## 1. Start by deciding whether your product should expose views at all [#1-start-by-deciding-whether-your-product-should-expose-views-at-all]

Saved views are for **named presets**.

Use them when users should be able to:

* return to a meaningful table setup later
* share a preset with teammates
* promote a preset to a personal or workspace default

Do not use them as a substitute for quiet autosave. That job belongs to `persistState`.

## 2. Shape the visible views workflow from the top-level `views` config [#2-shape-the-visible-views-workflow-from-the-top-level-views-config]

The views trigger only appears when both pieces exist:

* a `views` adapter configuration
* `toolbar.views: true`

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  toolbar={{
    views: true,
  }}
  views={{
    adapter: trpcViewAdapter,
    workspaceId: workspace.id,
    userId: currentUser.id,
  }}
/>
```

This is the first customization boundary: decide whether the surface exists before you change its labels or layout.

## 3. Treat adapter capability as part of the UI design [#3-treat-adapter-capability-as-part-of-the-ui-design]

The shipped saved view UI changes based on adapter support.

`react-datatable` checks whether the adapter can:

* share views with a workspace
* set user defaults
* set workspace defaults

That means the product should only promise actions the adapter can really perform.

For example:

* `localStorageDatatableViewAdapter` supports private views and user defaults
* it does **not** support sharing or workspace defaults
* a backend adapter can support the full collaboration workflow

If the table is anonymous, public, or single-user, disable collaboration-oriented affordances explicitly.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  toolbar={{ views: true }}
  views={{
    adapter: localStorageDatatableViewAdapter,
    userId: currentUser.id,
    enableWorkspaceSharing: false,
    enableUserDefaults: true,
  }}
/>
```

## 4. Keep the two list sections meaningful: Private and Workspace [#4-keep-the-two-list-sections-meaningful-private-and-workspace]

The current dropdown groups views into:

* **Private** — views that are not shared and not acting as shared defaults
* **Workspace** — shared views plus views carrying workspace or user-default meaning

That grouping is useful because it tells users whether a view is personal or social.

When you customize the labels or visual design, preserve that distinction.

A saved view should not look identical whether it is:

* visible only to one user
* shared with the workspace
* acting as a default for everyone

## 5. Customize naming and labels to fit the product domain [#5-customize-naming-and-labels-to-fit-the-product-domain]

Most view-surface customization starts with language.

Good candidates for product-specific wording include:

* what your product calls a “view”
* create and rename dialog descriptions
* share-action wording
* default labels and helper text
* empty-state text for first-time users

The shipped UI currently uses generic language such as:

* `Views`
* `Create new view`
* `Share with workspace`
* `Set as my default`
* `Set workspace default`

If your product has a clearer term such as “Queue,” “Preset,” or “Saved search,” this is a good source-level customization target.

## 6. Preserve the dirty-state workflow even if the visuals change [#6-preserve-the-dirty-state-workflow-even-if-the-visuals-change]

The current views trigger shows a dot when the active saved view has unsaved changes.

Inside the dropdown, an active dirty view can expose:

* `Update` for overwriting the active view
* `Save as` for creating a new view from the current state

That is an important behavior contract.

It tells users three different things clearly:

* which named preset is active
* whether they have drifted away from it
* whether they are editing the current preset or creating a new one

You can restyle these controls, but avoid collapsing them into a single ambiguous save action.

## 7. Decide carefully which users can rename, delete, share, or default a view [#7-decide-carefully-which-users-can-rename-delete-share-or-default-a-view]

The shipped menu already gates actions by ownership and capability.

Examples from the current source:

* rename and delete only appear for the view owner
* share only appears for private views when sharing is supported
* workspace default only appears for shared views
* user defaults are shown only when default management is enabled

That means UI customization should not be only decorative.

It should also keep permission meaning legible.

A helpful pattern is:

* keep destructive actions secondary
* make ownership obvious when views are shared
* avoid showing unavailable actions as dead controls

## 8. Use the dialogs to clarify what state a view actually captures [#8-use-the-dialogs-to-clarify-what-state-a-view-actually-captures]

The create dialog currently promises to save:

* filters
* sorting
* column layout
* display options

That is a good baseline because it reminds users that a view is a durable table preset, not just a bookmark.

If your product adds stronger sharing or governance language, the create and rename dialogs are often the right place to explain it.

For example, you may want to clarify:

* whether defaults affect only the current user
* whether sharing is irreversible
* whether a workspace default becomes the first experience for teammates

## 9. Separate views customization from persistence customization [#9-separate-views-customization-from-persistence-customization]

Saved views and current-view persistence reuse a similar state snapshot while serving different product surfaces.

Keep these roles distinct in the UI:

* **persistence** remembers private in-progress work automatically
* **saved views** are named presets users manage intentionally
* **URL sharing** sends a specific query state through a link

If a customization starts making views feel like invisible autosave, the product meaning gets blurry fast.

<Callout title="Name the memory model clearly">
  When teams say “the table should remember what I was doing,” that usually means `persistState`. When they say “I need a reusable setup I can choose again,” that means saved views. Keep the UI language aligned with that difference.
</Callout>

## 10. Edit the copied source when you need a different workflow [#10-edit-the-copied-source-when-you-need-a-different-workflow]

The shipped surface is implemented in the copied views components, including:

* `DatatableViewDropdown.tsx`
* `ViewsDropdownContent.tsx`
* `ViewItem.tsx`
* `CreateViewDialog.tsx`
* `RenameViewDialog.tsx`

Edit those files directly when the product needs deeper changes such as:

* different grouping or section rules
* a richer share flow
* custom badges for ownership or defaults
* extra metadata in each view row
* a different trigger shape or menu layout

When you do, keep the underlying model intact:

* active view selection
* dirty-state detection
* adapter capability gating
* ownership-based actions
* distinction between private, shared, and default states

## 11. Verify the views surface like a collaboration workflow, not a single button [#11-verify-the-views-surface-like-a-collaboration-workflow-not-a-single-button]

Before shipping a customized saved view UI, check that:

* the trigger only appears when views are truly enabled
* private versus workspace meaning is visually clear
* unsupported actions are hidden, not implied
* dirty-state update/save-as actions remain understandable
* rename, delete, and sharing flows respect ownership
* default actions match the adapter's real capabilities
* the UI still distinguishes named presets from autosaved current state

## Where to go next [#where-to-go-next]

* For the memory model behind this UI, read [Persistence and Sharing](/docs/concepts/persistence-and-sharing).
* For the practical setup of the feature itself, read [Add saved views](/docs/guides/add-saved-views).
* For the toolbar cluster that contains this trigger, read [Customizing toolbar and controls](/docs/customization/customizing-toolbar-and-controls).
* For deeper source-level swaps after prop-level customization runs out, read [Replacing built-in UI elements](/docs/customization/replacing-built-in-ui-elements).


# Customizing toolbar and controls (https://react-datatable.com/docs/customization/customizing-toolbar-and-controls)

Use this guide when the default toolbar structure is close to right, but the control mix still needs to match your product.

The toolbar is already a composed surface. Most customization starts by deciding **which built-in controls belong there** before you replace any deeper UI.

<MediaPlaceholder title="Toolbar with quick search, filters, views, display options, copy link, and custom action slot content">
  Show a realistic toolbar with quick search and filters on the left, views plus display controls on the right, and one product-specific action called out as a source-level extension.
</MediaPlaceholder>

## 1. Start by choosing whether the toolbar exists at all [#1-start-by-choosing-whether-the-toolbar-exists-at-all]

The toolbar can be disabled entirely or enabled with defaults.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  toolbar={false}
/>
```

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  toolbar={true}
/>
```

Use `false` only when the table is intentionally minimal or the surrounding screen already provides the same controls elsewhere.

## 2. Turn individual built-in controls on and off from `toolbar` [#2-turn-individual-built-in-controls-on-and-off-from-toolbar]

Most real customization starts with the object form.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  toolbar={{
    quickSearch: {
      placeholder: "Search customers...",
      debounceMs: 300,
    },
    filterButton: true,
    displayOptions: true,
    copyLink: false,
    views: true,
    appliedState: {
      showFilters: true,
      showSorting: true,
    },
  }}
/>
```

This decides whether the toolbar shows:

* quick search
* the filter button
* the display-options button
* the copy-link button
* the saved-views dropdown
* the applied sorting and filter chip bar below the toolbar

## 3. Treat the toolbar and applied-state bar as one workflow [#3-treat-the-toolbar-and-applied-state-bar-as-one-workflow]

The toolbar is where users *change* table state. The applied-state bar is where they *see and clear* that state.

That means toolbar customization should usually include a decision about `appliedState` too.

```tsx
toolbar={{
  filterButton: true,
  appliedState: {
    showFilters: true,
    showSorting: false,
  },
}}
```

A common healthy pattern is:

* keep filter chips visible when filtering matters
* hide sorting chips only when sorting is mostly a quiet default
* avoid removing both the entry point and the visible feedback for the same control

## 4. Some toolbar controls depend on top-level features [#4-some-toolbar-controls-depend-on-top-level-features]

A toolbar button exposes a feature entry point, while the feature's deeper behavior lives in its own configuration and state model.

Two important examples:

* `toolbar.views: true` only shows the views dropdown if the top-level `views` adapter config also exists
* `toolbar.displayOptions: true` only shows the button; the top-level `displayOptions` prop still decides what appears inside the popover

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  toolbar={{
    views: true,
    displayOptions: true,
  }}
  views={{
    adapter: trpcViewAdapter,
    workspaceId: workspace.id,
  }}
  displayOptions={{
    sections: {
      grouping: false,
      columnVisibility: true,
      displaySettings: true,
    },
  }}
/>
```

The toolbar controls the **entry point**. The top-level feature config controls the **behavior behind it**.

## 5. Tune quick search and filters to match the table's real job [#5-tune-quick-search-and-filters-to-match-the-tables-real-job]

The toolbar source places quick search and the filter button on the left because they are the primary query controls.

Keep that logic intact unless the workflow truly differs.

Good uses:

* quick search for fast broad lookup
* filter button for field-specific narrowing
* applied chips for visible active state

Less healthy uses:

* hiding query controls while expecting users to understand active filtering
* adding too many top-level controls until search and filters stop feeling primary

If query behavior needs work, customize the underlying guides first instead of treating the toolbar as a cosmetic shell.

## 6. Use views, display options, and copy link as secondary controls [#6-use-views-display-options-and-copy-link-as-secondary-controls]

The shipped toolbar keeps these controls on the right as secondary table-management actions:

* **Views** for named working states
* **Display options** for presentation controls
* **Copy link** for sharing the current URL state

That separation is useful because it keeps querying distinct from layout and sharing.

If a product hides one of these controls, do it because the workflow truly does not need it, not because the button cluster feels visually busy.

## 7. Expect the toolbar to wrap on narrow widths [#7-expect-the-toolbar-to-wrap-on-narrow-widths]

The copied source already changes layout on smaller containers.

In narrow mode it becomes a multi-row surface:

1. quick search plus filter button
2. views on the left and display/copy controls on the right
3. the Match all/Match any toggle when active filters require it

That means toolbar customization should be judged in both wide and narrow layouts.

A control mix that looks fine on desktop can become cramped or confusing once it wraps.

## 8. Use `viewColumnsButton` when visibility changes belong near the grid [#8-use-viewcolumnsbutton-when-visibility-changes-belong-near-the-grid]

Not every control has to live in the toolbar.

`viewColumnsButton` adds the pinned `+` affordance near the table grid for fast column visibility changes.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  toolbar={{
    displayOptions: true,
  }}
  viewColumnsButton={{
    show: true,
    width: 32,
  }}
/>
```

Use this when users frequently toggle visible columns while actively scanning rows, not only from the top toolbar.

## 9. The current limit: there is no public arbitrary toolbar slot [#9-the-current-limit-there-is-no-public-arbitrary-toolbar-slot]

The copied `DataTableToolbar` source has an internal `children` slot, while the public `Datatable` API shown in `props.types.ts` keeps toolbar composition fixed.

That means you can safely customize the shipped toolbar surface through:

* feature toggles
* quick-search config
* applied-state visibility
* top-level views and display-options configuration
* the separate `viewColumnsButton`

If you need product-specific buttons, extra segmented controls, or a different toolbar composition, you are beyond public configuration and into source-level customization.

<Callout title="Source ownership is the escape hatch here">
  Because the table lives in your repository, you can edit `DataTableToolbar.tsx` directly when the product needs custom controls beyond the current public API. Do that deliberately, and treat it as a deeper customization layer than ordinary prop tuning.
</Callout>

## 10. Verify the toolbar in context before shipping [#10-verify-the-toolbar-in-context-before-shipping]

Before you call the toolbar done, check that:

* primary query controls still feel primary
* applied chips stay visible when users need feedback
* views and display options only appear when their backing config exists
* the control mix still works after the layout wraps on narrow widths
* column-visibility controls live in the most natural place for the workflow
* extra product actions only enter the toolbar when prop-level customization is truly insufficient

## Where to go next [#where-to-go-next]

* For the surface this control cluster belongs to, read [Table anatomy](/docs/concepts/table-anatomy).
* For search behavior inside the toolbar, read [Add global search](/docs/guides/add-global-search).
* For the display-options popover behind one of these controls, read [Configure display options](/docs/guides/configure-display-options).
* For the broader decision of whether a change belongs in props or source, read [Customization overview](/docs/customization/customization-overview).


# Replacing built-in icons (https://react-datatable.com/docs/customization/replacing-built-in-icons)

The copied table source keeps built-in table icons behind one proxy file:

```txt
src/react-datatable/icons.tsx
```

That file currently re-exports Phosphor icons. The rest of the table imports from the local proxy instead of importing an icon library directly.

This means you can replace the table's built-in icon set without hunting through toolbar, filter, view, grid, dialog, and pagination components one by one.

## What the kit uses today [#what-the-kit-uses-today]

The core kit uses `@phosphor-icons/react` through `icons.tsx`.

Icons are used for table-owned controls such as:

* sort direction
* filters
* column visibility
* saved views
* copy link
* pagination
* dialogs
* empty and error states
* row preview close buttons
* bulk-action controls

The docs site and showcase examples also use `lucide-react` for product examples. Those are not part of the core table icon proxy.

## Replace the proxy, not every component [#replace-the-proxy-not-every-component]

Start by opening:

```tsx
// src/react-datatable/icons.tsx
```

The default file looks like this conceptually:

```tsx
export {
  ArrowDownIcon,
  ArrowUpIcon,
  CheckIcon,
  FunnelIcon,
  XIcon,
  // ...
} from "@phosphor-icons/react"

export type { Icon } from "@phosphor-icons/react"
```

If you want to use another icon set, keep the exported names stable and change what they point to.

## Example: replace built-ins with Lucide [#example-replace-built-ins-with-lucide]

Some Phosphor icons are passed a `weight` prop in the table source. Lucide icons do not use that prop, so wrap Lucide once and drop unsupported props there.

```tsx
import type { ComponentType, SVGProps } from "react"
import {
  ArrowDown,
  ArrowLeftRight,
  ArrowLeft,
  ArrowRight,
  ArrowUp,
  Bookmark,
  Calendar,
  Check,
  ChevronDown,
  Circle,
  Copy,
  Eye,
  EyeOff,
  Filter,
  GripVertical,
  Hash as HashIcon,
  Link,
  List as ListIcon,
  ListFilter,
  MoreHorizontal,
  Plus,
  RotateCcw,
  Ruler,
  Save,
  Search,
  Settings,
  SlidersHorizontal,
  Snowflake as SnowflakeIcon,
  Trash,
  TriangleAlert,
  Type,
  Users as UsersIcon,
  Workflow,
  X,
  type LucideIcon,
} from "lucide-react"

export type Icon = ComponentType<
  SVGProps<SVGSVGElement> & {
    size?: string | number
    weight?: unknown
  }
>

function asDatatableIcon(IconComponent: LucideIcon): Icon {
  return function DatatableIcon({ weight: _weight, ...props }) {
    return <IconComponent {...props} />
  }
}

export const ArrowCounterClockwiseIcon = asDatatableIcon(RotateCcw)
export const ArrowDownIcon = asDatatableIcon(ArrowDown)
export const ArrowUpIcon = asDatatableIcon(ArrowUp)
export const ArrowsLeftRight = asDatatableIcon(ArrowLeftRight)
export const CloseIcon = asDatatableIcon(X)
export const BookmarkSimpleIcon = asDatatableIcon(Bookmark)
export const CalendarBlank = asDatatableIcon(Calendar)
export const CaretDown = asDatatableIcon(ChevronDown)
export const CaretDownIcon = asDatatableIcon(ChevronDown)
export const CheckIcon = asDatatableIcon(Check)
export const ChevronDownIcon = asDatatableIcon(ChevronDown)
export const ChevronLeftIcon = asDatatableIcon(ArrowLeft)
export const ChevronRightIcon = asDatatableIcon(ArrowRight)
export const DotsSixVertical = asDatatableIcon(GripVertical)
export const DotsSixVerticalIcon = asDatatableIcon(GripVertical)
export const DotsThreeIcon = asDatatableIcon(MoreHorizontal)
export const MoreHorizontalIcon = asDatatableIcon(MoreHorizontal)
export const EyeIcon = asDatatableIcon(Eye)
export const EyeSlashIcon = asDatatableIcon(EyeOff)
export const FunnelIcon = asDatatableIcon(Filter)
export const FunnelSimpleIcon = asDatatableIcon(ListFilter)
export const Gear = asDatatableIcon(Settings)
export const Gradient = asDatatableIcon(Circle)
export const Hash = asDatatableIcon(HashIcon)
export const LinkIcon = asDatatableIcon(Link)
export const List = asDatatableIcon(ListIcon)
export const ListBullets = asDatatableIcon(ListIcon)
export const MagnifyingGlassIcon = asDatatableIcon(Search)
export const PlusIcon = asDatatableIcon(Plus)
export const RadioDotIcon = asDatatableIcon(Circle)
export const RulerIcon = asDatatableIcon(Ruler)
export const SlidersHorizontalIcon = asDatatableIcon(SlidersHorizontal)
export const Snowflake = asDatatableIcon(SnowflakeIcon)
export const SortAscendingIcon = asDatatableIcon(ArrowUp)
export const SortDescendingIcon = asDatatableIcon(ArrowDown)
export const TextT = asDatatableIcon(Type)
export const ToggleLeft = asDatatableIcon(Circle)
export const TrashIcon = asDatatableIcon(Trash)
export const Users = asDatatableIcon(UsersIcon)
export const WarningCircleIcon = asDatatableIcon(TriangleAlert)
export const WarningIcon = asDatatableIcon(TriangleAlert)
export const XIcon = asDatatableIcon(X)
export const AddIcon = PlusIcon
export const AlertIcon = WarningCircleIcon
export const SaveIcon = asDatatableIcon(Save)
export const SaveAsNewIcon = asDatatableIcon(Copy)
export const WorkflowIcon = asDatatableIcon(Workflow)
```

Treat this as a starting point. Pick the exact icons that fit your product language.

## Keep product icons out of the proxy [#keep-product-icons-out-of-the-proxy]

The proxy is for table-owned chrome.

Use column and cell code for product-specific icons:

```tsx
const columns = [
  {
    id: "status",
    accessorKey: "status",
    header: "Status",
    filterType: "text-list",
    meta: {
      filterName: "Status",
      filterIcon: StatusIcon,
    },
    cell: ({ row }) => <StatusCell status={row.original.status} />,
  },
]
```

That keeps the table's control icons separate from domain icons like status, priority, owner, health, or billing state.

## Check the result [#check-the-result]

After replacing the proxy, scan the table surfaces that use icons:

* toolbar buttons
* filter chips and filter editors
* display options
* saved views
* column header actions
* empty and error states
* pagination and calendar controls
* row preview and bulk-action surfaces

Then run TypeScript. If the icon set does not support a prop the table passes, adapt it in the proxy instead of changing every caller.

## Where to go next [#where-to-go-next]

* For changing the toolbar around those icons, read [Customizing toolbar and controls](/docs/customization/customizing-toolbar-and-controls).
* For filter-specific labels and icons, read [Customizing filter UI](/docs/customization/customizing-filter-ui).
* For replacing larger UI surfaces, read [Replacing built-in UI elements](/docs/customization/replacing-built-in-ui-elements).


# Replacing built-in UI elements (https://react-datatable.com/docs/customization/replacing-built-in-ui-elements)

Use this page when the shipped UI is **structurally close** to what you need, but a real product requirement now demands editing the copied source itself.

This is the point where `react-datatable` stops feeling like a package and starts behaving like product-owned UI.

<MediaPlaceholder title="Before/after comparison of one shipped control replaced with a product-owned version using copied source">
  Show the default toolbar or filter control beside a product-specific replacement, with annotations calling out what stayed stable: state hooks, table props, and interaction behavior.
</MediaPlaceholder>

## 1. Replace built-in UI only after configuration stops working [#1-replace-built-in-ui-only-after-configuration-stops-working]

Stay on the public surface first when the job is only to:

* hide or show shipped controls
* rename filter labels and options
* change how cells render
* tune display-options sections
* wire existing preview or views behavior into your app

Cross into source edits when the product needs something the public API does not expose cleanly, such as:

* a different control arrangement
* different button shapes, icons, or interaction patterns
* extra product actions in the toolbar
* a replacement filter entry flow
* a branded or workflow-specific control surface that still uses the same table state underneath

## 2. Choose the smallest replacement seam [#2-choose-the-smallest-replacement-seam]

Do not start by rewriting half the table.

Pick the narrowest component that owns the UI you actually need to change.

Common seams in the copied source include:

* `components/toolbar/DataTableToolbar.tsx` for control arrangement
* `components/toolbar/QuickSearch.tsx` for search input shape and clear-button behavior
* `components/toolbar/FilterButton.tsx` for the filter trigger and badge treatment
* `components/toolbar/DisplayOptionsButton.tsx` for the display-options entry point
* `components/DatatableViewDropdown/*` for saved-views trigger and dialog behavior

A narrow seam gives you a smaller diff, a clearer review surface, and fewer accidental behavior regressions.

## 3. Keep the contract, replace the shell [#3-keep-the-contract-replace-the-shell]

The safest replacement pattern is:

1. keep the same state hooks and inputs
2. keep the same output behavior
3. swap the rendered UI shell around them

For example, `QuickSearch.tsx` already owns the debounce, Cmd/Ctrl+F shortcut, Escape-to-clear behavior, and store sync. If your product needs a different search field visual treatment, edit that component before you touch broader table logic.

Likewise, `FilterButton.tsx` already owns the open state and active-filter badge count. If the product needs a different trigger layout, keep those behaviors and replace the button shell around them.

## 4. Rearranging toolbar controls is a source-level customization [#4-rearranging-toolbar-controls-is-a-source-level-customization]

The public `toolbar` prop toggles built-in controls while keeping composition within the shipped toolbar surface.

That makes `DataTableToolbar.tsx` the right seam when you need to:

* move controls into a different cluster
* insert a product-specific action beside shipped controls
* change wrapped-layout behavior on narrow widths
* promote or demote a control based on product workflow

When editing the toolbar, preserve the distinction between:

* **query controls** like quick search and filters
* **table-management controls** like views, display options, and copy link

That grouping is part of the table's usability and interaction clarity.

## 5. Preserve store subscriptions and state boundaries [#5-preserve-store-subscriptions-and-state-boundaries]

A lot of the shipped UI is intentionally narrow in what it subscribes to.

For example:

* `FilterButton` subscribes to `columnFilters.length`, not the whole filter array
* `QuickSearch` keeps a local input value, then debounces writes into the datatable store
* `DataTableToolbar` computes wrapped-layout details without owning query logic itself

When replacing built-in UI, keep those boundaries unless you have a strong reason not to.

If you casually widen subscriptions or move store logic into more components, the UI can still work while becoming noisier to maintain and easier to regress.

## 6. Replace interaction text and visuals freely, but be careful with semantics [#6-replace-interaction-text-and-visuals-freely-but-be-careful-with-semantics]

Safe things to customize aggressively:

* button text
* icons
* spacing and sizing
* class names and tokens
* arrangement of existing controls
* dialog and dropdown presentation details

Things to treat more carefully:

* keyboard shortcuts
* focus order
* badge meaning
* open/close interaction rules
* whether a control writes state immediately or only after confirmation

The product can absolutely look different. The dangerous part is changing what users can rely on without meaning to.

## 7. Prefer one owned wrapper over many scattered hacks [#7-prefer-one-owned-wrapper-over-many-scattered-hacks]

If several screens need the same replacement, consolidate it.

A healthy pattern is to make one deliberate product-owned version of the control or toolbar instead of scattering tiny overrides across many routes.

That gives you:

* one place to evolve the UI
* one place to review state behavior
* one place to update when the underlying table internals change

Because the source is local, your replacement can live right next to the shipped component and still stay easy to audit.

## 8. Do not smuggle core behavior changes into a cosmetic rewrite [#8-do-not-smuggle-core-behavior-changes-into-a-cosmetic-rewrite]

Source-level UI replacement is still a **UI** customization unless you explicitly decide otherwise.

If you are editing a built-in control, avoid quietly changing deeper behavior such as:

* URL serialization rules
* persistence merge order
* selection semantics
* filter payload meaning
* view-sharing permissions

Those are legitimate changes, and they belong to a deeper feature or state rewrite than swapping a button or replacing a dropdown shell.

<Callout title="Separate UI replacement from behavior changes">
  If a task changes both the visible control and the underlying rules, split the work mentally and verify each part on purpose. Cosmetic and behavioral edits bundled together are much harder to trust.
</Callout>

## 9. A practical replacement workflow [#9-a-practical-replacement-workflow]

When you replace a built-in UI element, follow this order:

1. identify the smallest owning component
2. read the current source and note which hooks and props it depends on
3. keep those contracts stable while changing the rendered shell
4. verify the control in the real table context
5. only then decide whether deeper refactoring is justified

This workflow keeps product customization fast without turning the copied table into a pile of ad hoc experiments.

## 10. Review the result like a product surface [#10-review-the-result-like-a-product-surface]

Before you call a replacement done, check that:

* the control still reaches the same table state it used before
* keyboard and focus behavior still make sense
* the replacement still works in narrow layouts where relevant
* state badges, labels, and empty states remain understandable
* the diff changed the intended component seam, not unrelated table logic
* future developers can still tell where product code ends and table mechanics begin

## Where to go next [#where-to-go-next]

* For prop-level control of the shipped toolbar before replacement, read [Customizing toolbar and controls](/docs/customization/customizing-toolbar-and-controls).
* For lighter filter-surface changes before component swaps, read [Customizing filter UI](/docs/customization/customizing-filter-ui).
* For the broader map of which layer should own a change, read [Customization overview](/docs/customization/customization-overview).
* For guidance on delegating narrow source edits safely, read [Coding agents](/docs/coding-agents).


# Styling rows and cells (https://react-datatable.com/docs/customization/styling-rows-and-cells)

Use this guide when the table needs visual states that ordinary CSS selectors cannot infer on their own.

`rowPresentation` is the styling seam for translating table-owned interaction state into your design system's classes and `data-*` attributes.

## 1. Treat styling as a separate customization layer from rendering [#1-treat-styling-as-a-separate-customization-layer-from-rendering]

A common mistake is to push every visual need into custom cell renderers.

That works for content, but it is the wrong layer for many styling concerns.

`rowPresentation` exists so the product can style rows and cells from table-owned state such as:

* selection
* active-row focus
* preview-open state
* whether a row is a data row or a group header

That makes it the right layer for **state-aware styling**, not content rendering.

## 2. Let the table own the state and your app own the styling decision [#2-let-the-table-own-the-state-and-your-app-own-the-styling-decision]

The table already knows whether a row is selected, active, or currently previewed.

`rowPresentation` lets your application consume that state and decide what classes or DOM attributes should appear.

```tsx
<Datatable
  tableKey="customers"
  rowPresentation={{
    getRowClassName: ({ isActive, isPreviewOpen }) =>
      isActive || isPreviewOpen ? "bg-primary/5" : undefined,
  }}
/>
```

This is the important split:

* the table decides **what state is true**
* your app decides **how that state should look**

## 3. Choose the right hook for the surface you want to style [#3-choose-the-right-hook-for-the-surface-you-want-to-style]

The API exposes separate hooks for rows and cells because those are different visual surfaces.

* `getRowClassName` styles the whole row shell
* `getCellClassName` styles an individual cell
* `getRowAttributes` adds row-level attributes
* `getCellAttributes` adds cell-level attributes

That lets you keep broad row treatment and precise cell treatment independent.

## 4. Branch on row kind when grouped tables need different treatment [#4-branch-on-row-kind-when-grouped-tables-need-different-treatment]

`getRowClassName` and `getRowAttributes` run for both normal data rows and group headers.

That is why the callback receives `rowKind`.

```tsx
getRowClassName={(info) => {
  if (info.rowKind === "group-header") return "font-medium text-muted-foreground"
  return info.isSelected ? "bg-muted" : undefined
}}
```

This is useful because grouped tables often need different styling logic for structural rows versus actual data rows, but they should still participate in one coherent styling system.

## 5. Use row styling for interaction state, not hidden business meaning [#5-use-row-styling-for-interaction-state-not-hidden-business-meaning]

A good use of row styling:

* selected rows get a muted background
* active keyboard row gets a stronger outline
* preview-open rows get a subtle emphasis
* group headers get a distinct structural treatment

A less healthy use:

* encoding important business meaning only through background color
* hiding core status semantics inside classes with no textual cue
* using row hooks to patch over missing data modeling in the column layer

The styling seam should reinforce meaning that already exists, not create the only source of meaning.

## 6. Use cell styling for local emphasis and per-column polish [#6-use-cell-styling-for-local-emphasis-and-per-column-polish]

`getCellClassName` is a good fit for targeted treatment such as:

* right-aligning numeric columns
* muting secondary metadata
* emphasizing a risk/status column
* applying stable per-column visual differences

Because it receives `columnId`, it can express per-column logic without requiring each custom cell to repeat the same styling rules.

```tsx
getCellClassName={({ columnId }) =>
  columnId === "revenue" ? "text-right tabular-nums" : undefined
}
```

## 7. Prefer attributes for testing and instrumentation seams [#7-prefer-attributes-for-testing-and-instrumentation-seams]

`getRowAttributes` and `getCellAttributes` support styling, testing, and instrumentation through one stable seam.

```tsx
getRowAttributes={({ rowKind, rowId }) => ({
  "data-row-kind": rowKind,
  "data-row-id": rowId,
})}
```

```tsx
getCellAttributes={({ columnId }) => ({
  "data-column-id": columnId,
})}
```

This is usually better than tying tests to visible text that may change frequently.

## 8. Keep selected, active, and preview-open states visually distinct [#8-keep-selected-active-and-preview-open-states-visually-distinct]

These three states can overlap while still carrying different interaction meaning.

* **selected** means included in selection state
* **active** means the keyboard/navigation cursor is on this row
* **preview-open** means the row is driving a preview surface

If all three use identical styling, the table becomes harder to read. Treat them as related but distinct signals.

## 9. Prefer hooks over ad hoc DOM reach-ins [#9-prefer-hooks-over-ad-hoc-dom-reach-ins]

Because virtualization, grouping, and selection change the rendered structure over time, styling hacks that depend on fragile DOM traversal tend to break.

`rowPresentation` is the stable surface for this job because it sits close to the table's own row-state model.

## 10. Use a simple boundary when deciding between styling and rendering [#10-use-a-simple-boundary-when-deciding-between-styling-and-rendering]

If the change is about **what content appears**, use a custom cell.\
If the change is about **how table-owned state should style the row or cell shell**, use `rowPresentation`.

That boundary keeps customization easier to maintain.

<Callout title="Think of rowPresentation as a styling adapter">
  It translates internal table state into your design system's classes and attributes, without forcing every individual cell renderer to understand selection, active-row state, or preview semantics.
</Callout>

## Where to go next [#where-to-go-next]

* For the broader customization map, read [Customization overview](/docs/customization/customization-overview).
* For content-level rendering changes, read [Custom React cells](/docs/customization/custom-react-cells).
* For the surrounding surface these styles act on, read [Table anatomy](/docs/concepts/table-anatomy).


# Avatar select cell (https://react-datatable.com/docs/examples/avatar-select-cell)

This example builds an owner picker with avatars, search, and an unassigned state.

<CustomCellPreviewCard>
  <CustomCellInlinePreview example="avatar-select" />
</CustomCellPreviewCard>

## Build the cell component [#build-the-cell-component]

The main point here is simple: custom cells are just React code. Start by building the cell UI the same way you would build any other React component.

```tsx
import { Check, ChevronsUpDown } from "lucide-react"
import { useState } from "react"
import { SearchableDropdown } from "@/components/searchable-dropdown"

type Owner = {
  id: string
  name: string
  initials: string
  color: string
}

export function AvatarSelectCell({
  value,
  owners,
  onChange,
}: {
  value: Owner | null
  owners: Owner[]
  onChange: (owner: Owner | null) => void
}) {
  const [open, setOpen] = useState(false)
  const items = [
    { id: "unassigned", name: "Unassigned", initials: "\u2014", color: "#94a3b8" } as Owner,
    ...owners,
  ]

  return (
    <SearchableDropdown
      open={open}
      onOpenChange={setOpen}
      items={items}
      getItemKey={(item) => item.id}
      filterFn={(item, search) => item.name.toLowerCase().includes(search.trim().toLowerCase())}
      onSelect={(item) => onChange(item.id === "unassigned" ? null : item)}
      renderItem={(item, selected) => (
        <span className="flex items-center gap-1.5 text-[12px] leading-4">
          <span
            className="inline-flex size-5 shrink-0 items-center justify-center rounded-full text-[10px] font-semibold text-white"
            style={{ backgroundColor: item.color }}
          >
            {item.initials}
          </span>
          <span className="flex-1 truncate">{item.name}</span>
          {selected ? <Check aria-hidden="true" className="ml-auto size-4" /> : null}
        </span>
      )}
      searchPlaceholder="Assign owner..."
      width="w-[240px]"
    >
      <button className="flex h-7 w-full items-center gap-1.5 rounded-md px-1.5 py-1 text-left text-[12px] leading-4 hover:bg-accent" type="button">
        <span
          className="inline-flex size-5 shrink-0 items-center justify-center rounded-full text-[10px] font-semibold text-white"
          style={{ backgroundColor: value?.color ?? "#cbd5e1" }}
        >
          {value?.initials ?? "\u2014"}
        </span>
        <span className="min-w-0 flex-1 truncate">{value?.name ?? "Unassigned"}</span>
        <ChevronsUpDown aria-hidden="true" className="size-3.5 text-muted-foreground" />
      </button>
    </SearchableDropdown>
  )
}
```

This component renders the current owner, opens the picker, and calls `onChange` when someone picks a new value.

<DetailsBlock title="SearchableDropdown helper">
  ```tsx
  import { useEffect, useRef } from "react"
  import { Input } from "@/components/ui/input"
  import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

  export function SearchableDropdown<T>({
    open,
    onOpenChange,
    items,
    renderItem,
    getItemKey,
    onSelect,
    searchPlaceholder = "Search...",
    filterFn,
    width = "w-56",
    children,
  }: SearchableDropdownProps<T>) {
    const searchInputRef = useRef<HTMLInputElement>(null)
    const { search, setSearch, selectedIndex, handleKeyDown, filteredItems } = useDropdownKeyboardNav({
      items,
      onSelect: (item) => {
        onSelect(item)
        onOpenChange(false)
      },
      filterFn,
      onEscape: () => onOpenChange(false),
    })

    useEffect(() => {
      if (!open) {
        setSearch("")
      }
    }, [open, setSearch])

    return (
      <Popover open={open} onOpenChange={onOpenChange}>
        {children && <PopoverTrigger asChild>{children}</PopoverTrigger>}
        <PopoverContent className={width + " z-[100] overflow-hidden p-0"} align="start">
          <div className="flex flex-col" onKeyDown={handleKeyDown}>
            <div className="bg-popover sticky top-0 z-10 border-b p-0.5">
              <Input
                ref={searchInputRef}
                value={search}
                onChange={(event) => setSearch(event.target.value)}
                placeholder={searchPlaceholder}
                className="inline-input h-8 border-none bg-transparent px-2 py-1"
              />
            </div>

            <div className="scrollbar-hidden overflow-y-auto py-1">
              {filteredItems.map((item, index) => (
                <button
                  key={getItemKey(item)}
                  type="button"
                  onClick={() => {
                    onSelect(item)
                    onOpenChange(false)
                  }}
                  className={index === selectedIndex ? "bg-accent text-accent-foreground mx-1 rounded px-2 py-1.5 text-left" : "mx-1 rounded px-2 py-1.5 text-left hover:bg-accent"}
                >
                  {renderItem(item, index === selectedIndex)}
                </button>
              ))}
            </div>
          </div>
        </PopoverContent>
      </Popover>
    )
  }
  ```
</DetailsBlock>

The avatar cell uses a reusable dropdown helper. You do not need this exact helper in your own app, but it is worth showing here because it contains the search, popover, and keyboard behavior that make the picker work.

## Connect it to a column [#connect-it-to-a-column]

Next, wire the component into the column definition. The cell handles the UI. The column tells the table which field it is rendering.

<AccessorNote accessor="customCellDocSnippets[&#x22;avatar-select&#x22;].accessor" />

```tsx
const columns: DatatableColumn<CustomerRow>[] = [
  {
    id: "owner",
    header: "Owner",
    accessorFn: (row) => row.owner?.name ?? "Unassigned",
    width: 220,
    enableSorting: false,
    filterType: "text-list",
    filterOptions: {
      options: owners.map((owner) => ({ value: owner.name, label: owner.name })),
      renderOption: (option) => {
        const owner = owners.find((item) => item.name === option.value)

        return (
          <>
            {owner ? (
              <span
                className="inline-flex size-5 shrink-0 items-center justify-center rounded-full text-[10px] font-semibold text-white"
                style={{ backgroundColor: owner.color }}
              >
                {owner.initials}
              </span>
            ) : null}
            <span className="truncate">{option.label}</span>
          </>
        )
      },
    },
    cell: ({ row }) => (
      <AvatarSelectCell
        value={row.original.owner}
        owners={owners}
        onChange={(owner) => handleOwnerChange(row.original.id, owner)}
      />
    ),
  },
]
```

The cell renderer and the filter option renderer are separate extension points. The cell controls how the value appears inside the grid; `filterOptions.renderOption` controls how each owner appears in the built-in text-list filter menu.

## Full table example [#full-table-example]

This is the full pattern in one place: the table owns the row state, the custom cell emits the new owner, and the table owns the optimistic update and refetch.

The column order here is deliberate: keep the interactive owner picker near the front so people can actually see and use it without scrolling past low-value fields first.

In the example, `useCustomersPage(queryState)` stands in for your page-level data hook. That hook gives the table both the current rows and `refetchPage()`. The cell stays focused on rendering and interaction only.

```tsx
function CustomersTable() {
  // Your page-level data hook owns the current query and exposes a way to refresh it.
  const { rows: serverRows, refetchPage } = useCustomersPage(queryState)
  const [rows, setRows] = useState(serverRows)

  useEffect(() => {
    setRows(serverRows)
  }, [serverRows])

  const handleOwnerChange = async (id: string, owner: Owner | null) => {
    // Optimistic update: show the new owner in the table immediately.
    setRows((current) => current.map((row) => (row.id === id ? { ...row, owner } : row)))

    try {
      await api.customers.updateOwner({ id, ownerId: owner?.id ?? null })
      await refetchPage() // Re-sync the current query with server truth after the save.
    } catch {
      await refetchPage() // Restore server truth if the mutation failed.
    }
  }

  const columns = [
    { id: "name", header: "Contact", accessorKey: "name", width: 180 },
    {
      id: "owner",
      header: "Owner",
      accessorFn: (row) => row.owner?.name ?? "Unassigned",
      width: 220,
      filterType: "text-list",
      filterOptions: {
        options: owners.map((owner) => ({ value: owner.name, label: owner.name })),
        renderOption: (option) => {
          const owner = owners.find((item) => item.name === option.value)

          return (
            <>
              {owner ? (
                <span
                  className="inline-flex size-5 shrink-0 items-center justify-center rounded-full text-[10px] font-semibold text-white"
                  style={{ backgroundColor: owner.color }}
                >
                  {owner.initials}
                </span>
              ) : null}
              <span className="truncate">{option.label}</span>
            </>
          )
        },
      },
      cell: ({ row }) => (
        <AvatarSelectCell
          value={row.original.owner}
          owners={owners}
          onChange={(owner) => handleOwnerChange(row.original.id, owner)}
        />
      ),
    },
    { id: "company", header: "Company", accessorKey: "company", width: 190 },
    { id: "status", header: "Status", accessorKey: "status", width: 140 },
    { id: "health", header: "Health", accessorKey: "health", width: 140 },
    { id: "renewal", header: "Renewal", accessorKey: "renewal", width: 150 },
  ] satisfies DatatableColumn<CustomerRow>[]

  return <Datatable tableKey="custom-cells" data={rows} columns={columns} getRowId={(row) => row.id} toolbar={false} />
}
```

<CustomCellMiniTable example="avatar-select" title="Full table example" />

## Update flow [#update-flow]

This section matters because the cell UI is only half the job. For a real table, readers also need to know where the save logic lives and why the value appears to change immediately.

This example uses the normal production pattern: an optimistic update.

* the cell emits the new owner
* the table updates local row state immediately
* the table sends the mutation in the background
* on success, the table refetches the current query to sync with server truth
* on failure, the same refetch restores the correct server state

```tsx
const handleOwnerChange = async (id: string, owner: Owner | null) => {
  // Optimistic update: update local row state before the request finishes.
  setRows((current) => current.map((row) => (row.id === id ? { ...row, owner } : row)))

  try {
    await api.customers.updateOwner({ id, ownerId: owner?.id ?? null })
    await refetchPage() // Re-run the current table query to sync with server truth.
  } catch {
    await refetchPage() // Roll back to server truth if the save failed.
  }
}
```

If your table is local-only, you may not need a refetch at all. If it is backed by server data, keep the refetch in the table or page layer so the cell never has to know how persistence works.

<Callout title="Keep the responsibilities separate">
  The cell should render the owner picker and emit changes. The table or page layer should own row state, mutations, and refetching.
</Callout>


# Boolean toggle cell (https://react-datatable.com/docs/examples/boolean-toggle-cell)

Use this when a row owns one simple true-or-false state such as paying, enabled, or verified.

<InteractiveCellBadge />

<CustomCellPreviewCard codeHref="#build-the-react-component" codePreview="customCellDocSnippets[&#x22;boolean-toggle&#x22;].component">
  <CustomCellInlinePreview example="boolean-toggle" />
</CustomCellPreviewCard>

## Build the React component [#build-the-react-component]

This is one of the simplest interactive cells possible: render the switch and make sure it does not fight the row click behavior around it.

```tsx
import { Switch } from "@/components/ui/switch"

export function BooleanToggleCell({
  value,
  onChange,
}: {
  value: boolean
  onChange: (value: boolean) => void
}) {
  return (
    <div className="flex justify-center" onClick={(event) => event.stopPropagation()}>
      <Switch checked={value} onCheckedChange={onChange} />
    </div>
  )
}
```

## Wire it into a column definition [#wire-it-into-a-column-definition]

The field stays a boolean in the column contract. The cell only turns that boolean into a compact switch UI.

<AccessorNote accessor="customCellDocSnippets[&#x22;boolean-toggle&#x22;].accessor" />

```tsx
{
  id: "paying",
  header: "Paying",
  accessorKey: "paying",
  width: 100,
  enableSorting: false,
  enableFiltering: false,
  cell: ({ row }) => (
    <BooleanToggleCell
      value={row.original.paying}
      onChange={(paying) => updateRow(row.original.id, { paying })}
    />
  ),
}
```

## Render it in a small table [#render-it-in-a-small-table]

The demo table shows the switch in context so you can verify that the row still feels like a table row rather than a loose form.

```tsx
function PayingExampleTable() {
  const [rows, setRows] = useState(seedRows)

  const updateRow = (id: string, patch: Partial<CustomerRow>) => {
    setRows((current) => current.map((row) => (row.id === id ? { ...row, ...patch } : row)))
  }

  return <Datatable tableKey="custom-cells" data={rows} columns={columns(updateRow)} getRowId={(row) => row.id} toolbar={false} />
}
```

<CustomCellMiniTable example="boolean-toggle" />

## Persist changes with optimistic update [#persist-changes-with-optimistic-update]

For backend writes, optimistic boolean flips are straightforward: update the row, send the mutation, then refetch to confirm authority.

```tsx
async function updatePaying(id: string, paying: boolean) {
  setRows((current) => current.map((row) => (row.id === id ? { ...row, paying } : row)))

  try {
    await api.customers.updateBillingState({ id, paying })
    await refetchCustomers()
  } catch {
    await refetchCustomers()
  }
}
```

<Callout title="Key takeaway">
  Always stop event propagation for switch-like controls so the cell does not accidentally trigger row open or preview actions.
</Callout>


# Currency trend cell (https://react-datatable.com/docs/examples/currency-trend-cell)

Use this when people need to scan both a number and its direction at the same time.

<CustomCellPreviewCard codeHref="#build-the-react-component" codePreview="customCellDocSnippets[&#x22;currency-trend&#x22;].component">
  <CustomCellInlinePreview example="currency-trend" />
</CustomCellPreviewCard>

## Build the React component [#build-the-react-component]

This cell is still just presentation: a formatted number plus a small trend icon driven by row data already in memory.

```tsx
import { Minus, TrendingDown, TrendingUp } from "lucide-react"

type Trend = "up" | "down" | "flat"

const iconByTrend = {
  up: TrendingUp,
  down: TrendingDown,
  flat: Minus,
} satisfies Record<Trend, typeof TrendingUp>

const toneByTrend = {
  up: "text-emerald-600",
  down: "text-red-500",
  flat: "text-muted-foreground",
}

export function CurrencyTrendCell({
  value,
  trend,
}: {
  value: number
  trend: Trend
}) {
  const Icon = iconByTrend[trend]

  return (
    <span className="inline-flex items-center gap-1.5 text-[12px] leading-4 font-medium">
      <span>{"$" + value.toLocaleString()}</span>
      <Icon aria-hidden="true" className={"size-3 " + toneByTrend[trend]} />
    </span>
  )
}
```

## Wire it into a column definition [#wire-it-into-a-column-definition]

Keep the column anchored to the numeric revenue field, then let the renderer enrich the visual treatment with trend context.

<AccessorNote accessor="customCellDocSnippets[&#x22;currency-trend&#x22;].accessor" />

```tsx
{
  id: "revenue",
  header: "Revenue",
  accessorKey: "revenue",
  width: 160,
  enableSorting: false,
  enableFiltering: false,
  cell: ({ row }) => (
    <CurrencyTrendCell
      value={row.original.revenue}
      trend={row.original.revenueTrend}
    />
  ),
}
```

## Render it in a small table [#render-it-in-a-small-table]

The mini table keeps only the revenue cell custom so the table-level integration remains obvious.

```tsx
const columns: DatatableColumn<CustomerRow>[] = [
  { id: "name", header: "Contact", accessorKey: "name" },
  { id: "company", header: "Company", accessorKey: "company" },
  {
    id: "revenue",
    header: "Revenue",
    accessorKey: "revenue",
    cell: ({ row }) => (
      <CurrencyTrendCell
        value={row.original.revenue}
        trend={row.original.revenueTrend}
      />
    ),
  },
]

<Datatable tableKey="custom-cells" data={rows} columns={columns} getRowId={(row) => row.id} toolbar={false} />
```

<CustomCellMiniTable example="currency-trend" />

<Callout title="Key takeaway">
  This pattern works well when the extra visual signal stays tiny. If the metric needs real analysis, that belongs in preview or a detail view.
</Callout>


# Custom cells gallery (https://react-datatable.com/docs/examples/custom-cells-gallery)

Use this page when the table contract is already stable and you want a concrete cell implementation to copy.

The live interactive version is on the [landing page custom-cells section](/#custom-cells).

## Available examples [#available-examples]

* [Avatar select cell](/docs/examples/avatar-select-cell)
* [Single select cell](/docs/examples/single-select-cell)
* [Multi-select cell](/docs/examples/multi-select-cell)
* [Date select cell](/docs/examples/date-select-cell)
* [Editable text cell](/docs/examples/editable-text-cell)
* [Progress cell](/docs/examples/progress-cell)
* [Currency trend cell](/docs/examples/currency-trend-cell)
* [Link cell](/docs/examples/link-cell)
* [Boolean toggle cell](/docs/examples/boolean-toggle-cell)

## How to use this set [#how-to-use-this-set]

1. Open the cell page closest to what you need.
2. Copy the component implementation.
3. Keep sorting, filtering, grouping, and row identity in the column definition.
4. Adapt the visual treatment to your product without changing the underlying table contract accidentally.

<Callout title="Keep cells cheap and predictable">
  Pre-create formatters, memoize expensive children when needed, and push large detail or multistep workflows into row preview instead of overloading the hottest render path in the table.
</Callout>


# Date select cell (https://react-datatable.com/docs/examples/date-select-cell)

Use this when a row needs one compact date field such as renewal, due date, or scheduled handoff.

<InteractiveCellBadge />

<CustomCellPreviewCard codeHref="#build-the-react-component" codePreview="customCellDocSnippets[&#x22;date-select&#x22;].component">
  <CustomCellInlinePreview example="date-select" />
</CustomCellPreviewCard>

## Build the React component [#build-the-react-component]

The cell only needs to show the current date clearly and open a small picker. Keep the rest of the date logic outside the render path.

```tsx
import { CalendarIcon } from "lucide-react"
import { format } from "date-fns"
import { useState } from "react"
import { Calendar } from "@/components/ui/calendar"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

export function DateSelectCell({
  value,
  onChange,
}: {
  value: string
  onChange: (value: string) => void
}) {
  const [open, setOpen] = useState(false)
  const date = new Date(value + "T00:00:00Z")

  return (
    <Popover open={open} onOpenChange={setOpen}>
      <PopoverTrigger asChild>
        <button className="inline-flex h-7 items-center gap-1.5 rounded-md px-1.5 py-1 text-[12px] leading-4 hover:bg-accent" type="button">
          <CalendarIcon className="size-3 text-muted-foreground" />
          <span>{format(date, "MMM d, yyyy")}</span>
        </button>
      </PopoverTrigger>
      <PopoverContent align="start" className="w-auto p-3">
        <Calendar
          className="p-0"
          mode="single"
          selected={date}
          onSelect={(next) => {
            if (!next) return
            onChange(next.toISOString().slice(0, 10))
            setOpen(false)
          }}
        />
      </PopoverContent>
    </Popover>
  )
}
```

## Wire it into a column definition [#wire-it-into-a-column-definition]

The column still keeps the durable field identity. The cell just gives that date field a compact inline picker.

<AccessorNote accessor="customCellDocSnippets[&#x22;date-select&#x22;].accessor" />

```tsx
{
  id: "renewal",
  header: "Renewal",
  accessorKey: "renewal",
  width: 150,
  enableSorting: false,
  enableFiltering: false,
  cell: ({ row }) => (
    <DateSelectCell
      value={row.original.renewal}
      onChange={(renewal) => updateRow(row.original.id, { renewal })}
    />
  ),
}
```

## Render it in a small table [#render-it-in-a-small-table]

This table renders one custom renewal column beside plain text columns so the integration stays easy to copy.

```tsx
function RenewalExampleTable() {
  const [rows, setRows] = useState(seedRows)

  const updateRow = (id: string, patch: Partial<CustomerRow>) => {
    setRows((current) => current.map((row) => (row.id === id ? { ...row, ...patch } : row)))
  }

  return <Datatable tableKey="custom-cells" data={rows} columns={columns(updateRow)} getRowId={(row) => row.id} toolbar={false} />
}
```

<CustomCellMiniTable example="date-select" />

## Persist changes with optimistic update [#persist-changes-with-optimistic-update]

In production, optimistic date updates are usually enough: patch the row locally, send the mutation, then refetch for backend truth.

```tsx
async function updateRenewal(id: string, renewal: string) {
  setRows((current) => current.map((row) => (row.id === id ? { ...row, renewal } : row)))

  try {
    await api.customers.updateRenewal({ id, renewal })
    await refetchCustomers()
  } catch {
    await refetchCustomers()
  }
}
```

<Callout title="Key takeaway">
  Date cells work best when they stay compact and predictable. If you need scheduling workflows, that usually belongs outside the grid.
</Callout>


# Editable text cell (https://react-datatable.com/docs/examples/editable-text-cell)

Use this when a row needs lightweight inline text edits without turning the table into a spreadsheet.

<InteractiveCellBadge />

<CustomCellPreviewCard codeHref="#build-the-react-component" codePreview="customCellDocSnippets[&#x22;editable&#x22;].component">
  <CustomCellInlinePreview example="editable" />
</CustomCellPreviewCard>

## Build the React component [#build-the-react-component]

The React component is the whole story here: switch between read and edit mode, keep a local draft, and commit on blur or Enter.

```tsx
import { useEffect, useState } from "react"
import { Input } from "@/components/ui/input"

export function EditableCell({
  value,
  onChange,
}: {
  value: string
  onChange: (value: string) => void
}) {
  const [editing, setEditing] = useState(false)
  const [draft, setDraft] = useState(value)

  useEffect(() => {
    setDraft(value)
  }, [value])

  if (!editing) {
    return (
      <button
        className="w-full rounded-md px-1.5 py-1 text-left text-sm hover:bg-accent"
        onClick={() => setEditing(true)}
        type="button"
      >
        <span className="block truncate">{value}</span>
      </button>
    )
  }

  return (
    <Input
      autoFocus
      className="h-8 border-none bg-transparent px-1.5 text-sm shadow-none ring-1 ring-ring"
      onBlur={() => {
        onChange(draft.trim() || value)
        setEditing(false)
      }}
      onChange={(event) => setDraft(event.target.value)}
      onKeyDown={(event) => {
        if (event.key === "Enter") {
          onChange(draft.trim() || value)
          setEditing(false)
        }
        if (event.key === "Escape") {
          setDraft(value)
          setEditing(false)
        }
      }}
      value={draft}
    />
  )
}
```

## Wire it into a column definition [#wire-it-into-a-column-definition]

The column keeps a stable text field for the table. The cell only manages the local editing surface.

<AccessorNote accessor="customCellDocSnippets[&#x22;editable&#x22;].accessor" />

```tsx
{
  id: "notes",
  header: "Notes",
  accessorKey: "notes",
  width: 240,
  enableSorting: false,
  enableFiltering: false,
  cell: ({ row }) => (
    <EditableCell
      value={row.original.notes}
      onChange={(notes) => updateRow(row.original.id, { notes })}
    />
  ),
}
```

## Render it in a small table [#render-it-in-a-small-table]

The mini table shows the inline editor in context without stacking multiple editable cell types into the same demo.

```tsx
function NotesExampleTable() {
  const [rows, setRows] = useState(seedRows)

  const updateRow = (id: string, patch: Partial<CustomerRow>) => {
    setRows((current) => current.map((row) => (row.id === id ? { ...row, ...patch } : row)))
  }

  return <Datatable tableKey="custom-cells" data={rows} columns={columns(updateRow)} getRowId={(row) => row.id} toolbar={false} />
}
```

<CustomCellMiniTable example="editable" />

## Persist changes with optimistic update [#persist-changes-with-optimistic-update]

For backend sync, keep the optimistic patch small and let refetch clean up any validation or canonical formatting differences.

```tsx
async function updateNotes(id: string, notes: string) {
  setRows((current) => current.map((row) => (row.id === id ? { ...row, notes } : row)))

  try {
    await api.customers.updateNotes({ id, notes })
    await refetchCustomers()
  } catch {
    await refetchCustomers()
  }
}
```

<Callout title="Key takeaway">
  Inline text editing should feel lightweight. If the field needs validation rules, helper text, or multi-step input, move it out of the cell.
</Callout>


# Infinite Scroll Table (https://react-datatable.com/docs/examples/infinite-scroll-table)

This example keeps fetching and shaping rows on the server by using the datatable in **infinite online** mode, so users scan one continuous list instead of jumping between numbered pages. The live table below behaves like a real product surface: each interaction sends an `OnlineQueryInput` to this site’s demo API, and the table paints whatever rows, totals, and filter metadata come back. When someone opens a multi-select list filter, the response can include **facets** so each choice shows a count that matches the current filters; the field names and shapes are documented under [Online API](/docs/reference/online-api). Use viewport virtualization so the DOM stays bounded while the server returns scrolling windows.

<Callout title="Copy and adapt this example">
  Swap the column definitions and `query` function for your own route and data layer. Keep stable column IDs, a dataset-level `queryKey`, and backend-owned totals so the footer and filters stay honest.
</Callout>

<InfiniteScrollTableInlineExample />

Before you start, install the datatable source into your app and add the server helpers when you need them. See [Installation](/docs/installation) for the `npx @react-datatable/cli install` command and how to use your license token.

## 1. Shared row type [#1-shared-row-type]

Define the row shape **once** (for example in `shared/customer.ts` or `contracts/customer.ts`) and import it from both your React table and your API handler. That way the columns, `getRowId`, and `OnlineQueryResponse<Customer>` stay aligned with the JSON your route actually returns, without duplicating stringly-typed fields.

The browser still does not load the full dataset: the API returns one scrolling window of rows (plus totals metadata and `hasMore`) at a time, scoped by tenant, permissions, and whatever else your handler enforces.

```tsx
// shared (import from the same module in your Vite app and in your server process)
type Customer = {
  id: string
  company: string
  name: string
  status: string
  plan: string
  region: string
  seats: number
  revenue: number
  owner: string
  renewal: string
}
```

## 2. Define columns [#2-define-columns]

This step is **client-only**: you configure `DatatableColumn` so the table knows headers, widths, and which built-in filter and sort UIs to show. Give every column a stable `id`. When you add the route in **step 7**, reuse those same ids in your server column map so filters and sorts line up with what the table sends.

```tsx
// client
import type { DatatableColumn } from "./react-datatable"

const statuses = ["Active", "Trial", "Paused"] as const

const columns: DatatableColumn<Customer>[] = [
  {
    id: "company",
    header: "Company",
    accessorKey: "company",
    width: 240,
    enableSorting: true,
    enableFiltering: true,
    filterType: "text",
  },
  {
    id: "status",
    header: "Status",
    accessorKey: "status",
    width: 150,
    enableSorting: true,
    enableFiltering: true,
    enableGrouping: true,
    filterType: "text-list",
    filterOptions: {
      options: statuses.map((status) => ({ label: status, value: status })),
    },
  },
]
```

## 3. Online infinite mode [#3-online-infinite-mode]

Use `online` instead of `data`, and set `mode: "infinite"`. The table owns interaction state; the backend owns matching rows, totals, facets, and `hasMore` so the scroll range stays honest. Set `pageSize` and `prefetchRows` to control how large each server window is and how far ahead to load.

```tsx
// client
import { Datatable } from "./react-datatable"

<Datatable
  tableKey="customers"
  columns={columns}
  getRowId={(row) => row.id}
  online={{
    mode: "infinite",
    queryKey: ["customers", workspaceId],
    pageSize: 80,
    prefetchRows: 160,
    supportedGroupingColumns: ["status"],
    query: fetchCustomersPage,
  }}
  initialState={{
    sorting: [{ id: "company", desc: false }],
  }}
/>
```

## 4. Implement the query function [#4-implement-the-query-function]

The smallest useful implementation is a `fetch` that posts JSON and returns `OnlineQueryResponse<TData>`. The route sketch in step 7.6 uses `runInMemoryDatatableQuery` on every row you load for the tenant (unfiltered within that scope); the helper applies `input` in memory. That is easy to validate but does not scale if the slice is huge, so plan to replace it with a database-backed query while keeping the same route contract. See [Server helper API](/docs/reference/server-helper-api) and [Server query endpoint](/docs/guides/server-query-endpoint).

```tsx
// client
import type { OnlineQueryInput, OnlineQueryResponse } from "react-datatable-server"

async function fetchCustomersPage(input: OnlineQueryInput): Promise<OnlineQueryResponse<Customer>> {
  const response = await fetch("/api/customers/table", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(input),
  })

  if (!response.ok) {
    throw new Error("Failed to load customers")
  }

  return response.json()
}
```

## 5. Add the toolbar and selection configuration [#5-add-the-toolbar-and-selection-configuration]

Online mode moves row computation to the server; you can still expose search, filters, display options, selection, and bulk actions on the client.

```tsx
// client
toolbar={{
  quickSearch: { placeholder: "Search Customers..." },
  filterButton: true,
  displayOptions: true,
  copyLink: false,
  views: false,
}}
selection={{
  enabled: true,
  mode: "multi",
  showCheckboxOnHover: false,
  allowSelectAllMatching: true,
}}
```

## 6. Viewport virtualization [#6-viewport-virtualization]

Infinite loading decides **which server windows are fetched** as the user scrolls. Viewport virtualization decides **how many loaded rows the browser mounts**. They compose cleanly:

```tsx
// client
virtualization={{
  mode: "viewport",
  rowOverscanCount: 12,
}}
```

## 7. Implement the server-side route [#7-implement-the-server-side-route]

This walkthrough uses **Hono** and **Drizzle** so you have a concrete, copy-pasteable server file. You can use any web framework and data layer you like; what matters is that your handler accepts `OnlineQueryInput` as JSON and returns `OnlineQueryResponse` for the same row type as the table. Shape that handler like a normal HTTP API route: method, path, JSON body, and JSON response are covered in [Server query endpoint](/docs/guides/server-query-endpoint).

Expose one HTTP route (for example `POST /api/customers/table`) on your API process. It should read the JSON body as `OnlineQueryInput` and respond with `OnlineQueryResponse` for the same row type you share with the client in step 1.

### 7.1 Install packages [#71-install-packages]

<PackageManagerCommandTabs
  commands="{
  pnpm: `pnpm add hono drizzle-orm pg
pnpm add -D drizzle-kit @types/pg`,
  npm: `npm install hono drizzle-orm pg
npm install -D drizzle-kit @types/pg`,
  yarn: `yarn add hono drizzle-orm pg
yarn add -D drizzle-kit @types/pg`,
  bun: `bun add hono drizzle-orm pg
bun add --dev drizzle-kit @types/pg`,
}"
/>

### 7.2 Open Postgres and create a Drizzle client [#72-open-postgres-and-create-a-drizzle-client]

Create one `pg.Pool` from `DATABASE_URL` for the whole process, then pass it to `drizzle`. Reuse that `db` instance from your route handlers.

```ts
// server
import { drizzle } from "drizzle-orm/node-postgres"
import { Pool } from "pg"

const pool = new Pool({ connectionString: process.env.DATABASE_URL })
export const db = drizzle(pool)
```

### 7.3 Model the table with Drizzle [#73-model-the-table-with-drizzle]

Add a `pgTable` that matches your real migration: primary key, a tenant or `workspace_id` column for scoping, and every column your `DatatableColumn` definitions read through `accessorKey` or `accessorFn`.

```ts
// server/schema/customers.ts (example: grow this to match step 2 and your migrations)
import { integer, pgTable, text } from "drizzle-orm/pg-core"

export const customers = pgTable("customers", {
  id: text("id").primaryKey(),
  workspaceId: text("workspace_id").notNull(),
  company: text("company").notNull(),
  contactName: text("contact_name").notNull(),
  status: text("status").notNull(),
  plan: text("plan").notNull(),
  region: text("region").notNull(),
  seats: integer("seats").notNull(),
  revenue: integer("revenue").notNull(),
  owner: text("owner").notNull(),
  renewal: text("renewal").notNull(),
})
```

### 7.4 Map SQL rows to your shared row type [#74-map-sql-rows-to-your-shared-row-type]

`db.select()` returns rows in the shape of your Drizzle schema. Map each row to the same `Customer` (or product) interface the React table uses (for example, map `contact_name` in SQL to `name` in TypeScript) so the rest of the pipeline works with one type.

```ts
// server/map-customer.ts
import type { Customer } from "../../shared/customer"
import type { customers } from "./schema/customers"

type CustomerRow = typeof customers.$inferSelect

export function mapRow(row: CustomerRow): Customer {
  return {
    id: row.id,
    company: row.company,
    name: row.contactName,
    status: row.status,
    plan: row.plan,
    region: row.region,
    seats: row.seats,
    revenue: row.revenue,
    owner: row.owner,
    renewal: row.renewal,
  }
}
```

### 7.5 Import the same column definitions as the client [#75-import-the-same-column-definitions-as-the-client]

Import the `DatatableColumn<Customer>[]` from step 2 (in a real repo, move that array to a small shared module and import it from both Vite and the server bundle). The column `id` values are what the table sends in `filters` and `sorting`; your server logic must recognize those ids.

```ts
// server/customers-table-route.ts
import type { Customer } from "../../shared/customer"
import { customerOnlineColumns } from "../../shared/customer-online-columns"
// Export `customerOnlineColumns` once from shared/customer-online-columns.ts (the same
// array you use in step 2) so filters and sorts hit the same column ids on the server.
```

### 7.6 Implement `POST /api/customers/table` [#76-implement-post-apicustomerstable]

1. Resolve the signed-in user and `workspaceId` (or equivalent tenant scope).
2. `const input = (await c.req.json()) as OnlineQueryInput`.
3. Load rows for that scope only, for example `await db.select().from(customers).where(eq(customers.workspaceId, workspaceId))`.
4. Map rows with your mapper from 7.4 into `Customer[]`.
5. Turn `input` plus `data` into an `OnlineQueryResponse` (see the snippet below and the note that follows it).

Return `c.json(response)` with the correct `content-type` for JSON.

```ts
// server/customers-table-route.ts
import { Hono } from "hono"
import { eq } from "drizzle-orm"
import type { OnlineQueryInput } from "react-datatable-server"
import { runInMemoryDatatableQuery } from "react-datatable-server"
import { customerOnlineColumns } from "../../shared/customer-online-columns"
import { customers } from "./schema/customers"
import { db } from "./db"
import { mapRow } from "./map-customer"

export function registerCustomersTableRoute(app: Hono) {
  app.post("/api/customers/table", async (c) => {
    const workspaceId = c.req.header("x-workspace-id") ?? "demo_workspace"
    const input = (await c.req.json()) as OnlineQueryInput

    const rows = await db.select().from(customers).where(eq(customers.workspaceId, workspaceId))
    const data = rows.map(mapRow)

    const response = await runInMemoryDatatableQuery({
      data,
      columns: customerOnlineColumns,
      input,
      getRowId: (row) => row.id,
    })

    return c.json(response)
  })
}
```

`runInMemoryDatatableQuery` takes the **unfiltered** row array you pass as `data` (for example every mapped customer in the workspace) and applies the online query shape from `input` in process memory: filters, sorts, grouping, pagination or scroll windows, and the other fields the table sends. You do **not** pre-slice `data` to the rows the grid is showing; the helper returns the correct slice and metadata (including `hasMore` in infinite mode) in `OnlineQueryResponse`. That makes it a fast way to stand up the route and **verify online mode and column wiring** before you build real SQL.

It is **not** a good fit for large datasets, because each request loads the full scoped table (or whatever subset your `where` returns) into server RAM. When behavior looks right in the browser, move the same contract to a database-backed planner or query builder so filtering and paging happen in the engine instead of in Node. [Server query endpoint](/docs/guides/server-query-endpoint) is the place to start for that handoff.

### 7.7 Mount Hono and register the route [#77-mount-hono-and-register-the-route]

Create `const app = new Hono()`, call your register function from step 7.6, then export `app` for your runtime (Bun, Node with your adapter, etc.).

```ts
// server/app.ts
import { Hono } from "hono"
import { registerCustomersTableRoute } from "./customers-table-route"

const app = new Hono()
registerCustomersTableRoute(app)

export default app
```

The all-in-one server snippet under **Full examples** inlines the same mapper, columns, and handler in a single file instead of splitting them across modules.

The **same handler** also powers [Paginated Table](/docs/examples/paginated-table): the client sets `online.mode` to `"pagination"` and uses explicit pages instead of scroll windows; the server still reads `input.mode`, `input.offset`, and `input.limit` from the JSON body.

The live table above uses the full showcase columns, row preview, and CSV export wired to this site’s `/api/showcase/export`. The copyable blocks below are a smaller baseline you can paste into your own repository; follow [Server query endpoint](/docs/guides/server-query-endpoint) to implement `POST /api/customers/export` (or your chosen path) for the same `serverExecutor` contract.

## Full examples [#full-examples]

<details>
  <summary>
    Expand to copy a minimal infinite online table (React)
  </summary>

  ```tsx
  // client
  import { useMemo } from "react"
  import {
    Datatable,
    type DataTableBulkAction,
    type DataTableBulkServerActionRequest,
    type DatatableColumn,
  } from "./react-datatable"
  import type { OnlineQueryInput, OnlineQueryResponse } from "react-datatable-server"

  type Customer = {
    id: string
    company: string
    name: string
    status: "Active" | "Trial" | "Paused"
    plan: string
    region: string
    seats: number
    revenue: number
    owner: string
    renewal: string
  }

  const statuses = ["Active", "Trial", "Paused"] as const

  async function fetchCustomersPage(input: OnlineQueryInput): Promise<OnlineQueryResponse<Customer>> {
    const response = await fetch("/api/customers/table", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(input),
    })
    if (!response.ok) {
      throw new Error("Failed to load customers")
    }
    return response.json()
  }

  /** POST /api/customers/export. Same selection payload contract as the bulk-actions guide. */
  async function customersBulkServerExecutor(request: DataTableBulkServerActionRequest): Promise<void> {
    if (request.actionId !== "export-customers-csv") {
      return
    }

    const response = await fetch("/api/customers/export", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        selection: request.selection,
        payload: request.payload,
      }),
    })

    if (!response.ok) {
      throw new Error(`Export failed: ${response.status}`)
    }

    const blob = await response.blob()
    const url = URL.createObjectURL(blob)
    const link = document.createElement("a")
    link.href = url
    link.download = "customers-export.csv"
    link.click()
    URL.revokeObjectURL(url)
  }

  export function CustomersInfiniteTable({ workspaceId }: { workspaceId: string }) {
    const columns = useMemo<DatatableColumn<Customer>[]>(
      () => [
        {
          id: "company",
          header: "Company",
          accessorKey: "company",
          width: 240,
          enableSorting: true,
          enableFiltering: true,
          filterType: "text",
        },
        {
          id: "status",
          header: "Status",
          accessorKey: "status",
          width: 140,
          enableSorting: true,
          enableFiltering: true,
          enableGrouping: true,
          filterType: "text-list",
          filterOptions: {
            options: statuses.map((status) => ({ label: status, value: status })),
          },
        },
      ],
      []
    )

    const bulkActions = useMemo<DataTableBulkAction<Customer>[]>(
      () => [
        {
          id: "export-selection",
          title: "Export selected CSV",
          execution: "server",
          serverActionId: "export-customers-csv",
          buildServerPayload: () => ({ requestedBy: "customers-table" }),
        },
      ],
      []
    )

    return (
      <div className="h-[560px] overflow-hidden rounded-lg border">
        <Datatable
          tableKey="customers"
          columns={columns}
          getRowId={(row) => row.id}
          online={{
            mode: "infinite",
            queryKey: ["customers", workspaceId],
            pageSize: 80,
            prefetchRows: 160,
            supportedGroupingColumns: ["status"],
            query: fetchCustomersPage,
          }}
          toolbar={{
            quickSearch: { placeholder: "Search Customers..." },
            filterButton: true,
            displayOptions: true,
            copyLink: false,
            views: false,
          }}
          initialState={{
            sorting: [{ id: "company", desc: false }],
          }}
          virtualization={{ mode: "viewport", rowOverscanCount: 12 }}
          selection={{
            enabled: true,
            mode: "multi",
            showCheckboxOnHover: false,
            allowSelectAllMatching: true,
          }}
          bulkActions={{
            triggerLabel: "Actions",
            actions: bulkActions,
            serverExecutor: customersBulkServerExecutor,
          }}
        />
      </div>
    )
  }
  ```
</details>

<details>
  <summary>
    Expand to copy a minimal online table server (Hono + Drizzle)
  </summary>

  ```ts
  // server
  /**
   * customers-table-api.ts: single-file sketch you can split into schema/, routes/, etc.
   * Serves POST /api/customers/table for both pagination and infinite online modes.
   *
   * Teaching default: `runInMemoryDatatableQuery` runs the online planner on the scoped
   * row array. Replace that call with SQL-backed planning when the workspace slice is too
   * large to load whole; keep the same JSON request/response contract.
   */
  import { Hono } from "hono"
  import { drizzle } from "drizzle-orm/node-postgres"
  import { eq } from "drizzle-orm"
  import { Pool } from "pg"
  import { integer, pgTable, text } from "drizzle-orm/pg-core"
  import type { OnlineQueryInput } from "react-datatable-server"
  import { runInMemoryDatatableQuery } from "react-datatable-server"
  import type { DatatableColumn } from "./react-datatable"

  // --- Drizzle schema (match your migrations) ---
  const customers = pgTable("customers", {
    id: text("id").primaryKey(),
    workspaceId: text("workspace_id").notNull(),
    company: text("company").notNull(),
    contactName: text("contact_name").notNull(),
    status: text("status").notNull(),
    plan: text("plan").notNull(),
    region: text("region").notNull(),
    seats: integer("seats").notNull(),
    revenue: integer("revenue").notNull(),
    owner: text("owner").notNull(),
    renewal: text("renewal").notNull(),
  })

  type CustomerRow = typeof customers.$inferSelect

  type Customer = {
    id: string
    workspaceId: string
    company: string
    name: string
    status: "Active" | "Trial" | "Paused"
    plan: string
    region: string
    seats: number
    revenue: number
    owner: string
    renewal: string
  }

  function mapRow(row: CustomerRow): Customer {
    return {
      id: row.id,
      workspaceId: row.workspaceId,
      company: row.company,
      name: row.contactName,
      status: row.status as Customer["status"],
      plan: row.plan,
      region: row.region,
      seats: row.seats,
      revenue: row.revenue,
      owner: row.owner,
      renewal: row.renewal,
    }
  }

  const statuses = ["Active", "Trial", "Paused"] as const

  // --- Keep in sync with the React table (extract to shared/ in real apps) ---
  const customerOnlineColumns: DatatableColumn<Customer>[] = [
    {
      id: "company",
      header: "Company",
      accessorKey: "company",
      width: 240,
      enableSorting: true,
      enableFiltering: true,
      filterType: "text",
    },
    {
      id: "name",
      header: "Contact",
      accessorKey: "name",
      width: 190,
      enableSorting: true,
      enableFiltering: true,
      filterType: "text",
    },
    {
      id: "status",
      header: "Status",
      accessorKey: "status",
      width: 140,
      enableSorting: true,
      enableFiltering: true,
      enableGrouping: true,
      filterType: "text-list",
      filterOptions: {
        options: statuses.map((status) => ({ label: status, value: status })),
      },
    },
    {
      id: "plan",
      header: "Plan",
      accessorKey: "plan",
      width: 130,
      enableSorting: true,
      enableFiltering: true,
      enableGrouping: true,
      filterType: "text-list",
      filterOptions: {
        options: ["Starter", "Team", "Enterprise"].map((plan) => ({ label: plan, value: plan })),
      },
    },
    {
      id: "region",
      header: "Region",
      accessorKey: "region",
      width: 120,
      enableSorting: true,
      enableFiltering: true,
      enableGrouping: true,
      filterType: "text-list",
      filterOptions: {
        options: ["NA", "EU", "APAC"].map((region) => ({ label: region, value: region })),
      },
    },
    {
      id: "seats",
      header: "Seats",
      accessorKey: "seats",
      width: 110,
      enableSorting: true,
      enableFiltering: true,
      filterType: "number",
    },
    {
      id: "revenue",
      header: "Revenue",
      accessorKey: "revenue",
      width: 130,
      enableSorting: true,
      enableFiltering: true,
      filterType: "number",
    },
    {
      id: "owner",
      header: "Owner",
      accessorKey: "owner",
      width: 170,
      enableSorting: true,
      enableFiltering: true,
      filterType: "text",
    },
    {
      id: "renewal",
      header: "Renewal",
      accessorKey: "renewal",
      width: 140,
      enableSorting: true,
      enableFiltering: true,
      filterType: "date",
    },
  ]

  const pool = new Pool({ connectionString: process.env.DATABASE_URL })
  const db = drizzle(pool)

  const app = new Hono()

  app.post("/api/customers/table", async (c) => {
    // Replace with real session / tenant resolution.
    const workspaceId = c.req.header("x-workspace-id") ?? "demo_workspace"

    const input = (await c.req.json()) as OnlineQueryInput

    const rows = await db.select().from(customers).where(eq(customers.workspaceId, workspaceId))

    const data = rows.map(mapRow)

    const response = await runInMemoryDatatableQuery({
      data,
      columns: customerOnlineColumns,
      input,
      getRowId: (row) => row.id,
    })

    return c.json(response)
  })

  export default app
  ```

  For a minimal local run, create the pool from `DATABASE_URL`, start Hono on a port, and point the React `fetch` URL at `http://127.0.0.1:8787/api/customers/table` (or mount this `app` behind your framework’s dev proxy under `/api/customers/table`). When you outgrow the in-memory helper, follow [Server query planning](/docs/guides/server-query-planning) and [Server query execution](/docs/guides/server-query-execution) to push filters, sorts, and pagination into the database.
</details>

## Where to go next [#where-to-go-next]

* For the data-boundary decision, read [Choose a data mode](/docs/guides/choose-a-data-mode).
* For request and response shapes, read [Online API](/docs/reference/online-api).
* For explicit pages instead of continuous loading, read [Paginated Table](/docs/examples/paginated-table).
* For the HTTP contract used by online tables and server bulk payloads, read [Server query endpoint](/docs/guides/server-query-endpoint).


# Link cell (https://react-datatable.com/docs/examples/link-cell)

Use this when a field should open a detail route or external destination directly from the table.

<CustomCellPreviewCard codeHref="#build-the-react-component" codePreview="customCellDocSnippets[&#x22;link&#x22;].component">
  <CustomCellInlinePreview example="link" />
</CustomCellPreviewCard>

## Build the React component [#build-the-react-component]

This component keeps link navigation and row interaction from conflicting by stopping the row click from hijacking navigation.

```tsx
import { ExternalLink } from "lucide-react"

export function LinkCell({ href }: { href: string }) {
  const label = new URL(href).hostname.replace(/^www\./, "")

  return (
    <a
      className="inline-flex items-center gap-1.5 text-[12px] leading-4 text-foreground hover:underline"
      href={href}
      onClick={(event) => event.stopPropagation()}
      rel="noreferrer"
      target="_blank"
    >
      <span className="truncate">{label}</span>
      <ExternalLink aria-hidden="true" className="size-3.5 text-muted-foreground" />
    </a>
  )
}
```

## Wire it into a column definition [#wire-it-into-a-column-definition]

The column still exposes the field as a normal URL string while the cell decides how to render a friendlier label.

<AccessorNote accessor="customCellDocSnippets[&#x22;link&#x22;].accessor" />

```tsx
{
  id: "website",
  header: "Website",
  accessorKey: "website",
  width: 190,
  enableSorting: false,
  enableFiltering: false,
  cell: ({ row }) => <LinkCell href={row.original.website} />,
}
```

## Render it in a small table [#render-it-in-a-small-table]

The table demo keeps the website column custom and leaves the rest plain so the link behavior is easy to reason about.

```tsx
const columns: DatatableColumn<CustomerRow>[] = [
  { id: "name", header: "Contact", accessorKey: "name" },
  { id: "company", header: "Company", accessorKey: "company" },
  {
    id: "website",
    header: "Website",
    accessorKey: "website",
    cell: ({ row }) => <LinkCell href={row.original.website} />,
  },
]

<Datatable tableKey="custom-cells" data={rows} columns={columns} getRowId={(row) => row.id} toolbar={false} />
```

<CustomCellMiniTable example="link" />

<Callout title="Key takeaway">
  For interactive cells with anchors or buttons, always test them against row selection, preview, and keyboard navigation.
</Callout>


# Local Data Table (https://react-datatable.com/docs/examples/local-data-table)

This example shows how common features work together in one local-mode table. You you can copy, run, and then adapt to your own product. It builds a local table with typed rows, stable row IDs, search, filters, display options, selection, bulk actions, keyboard navigation, and preview using static in-file data with no custom cells.

<Callout title="Copy and adapt this example">
  For your product, swap the row type, columns, preview content, and bulk actions for your domain. Keep the same discipline around stable IDs, local-mode ownership, and feature layering.
</Callout>

<LocalCustomerTableInlineExample />

Before you start, install the datatable package and set it up. See [Installation](/docs/installation).

## 1. Row type and data [#1-row-type-and-data]

Define one `Customer` type and keep the data array in the same file so the example is fully copyable.

```tsx
// client
type Customer = {
  id: string
  name: string
  company: string
  status: "Active" | "Trial" | "Paused"
  plan: "Starter" | "Team" | "Enterprise"
  seats: number
  revenue: number
  owner: string
  region: "NA" | "EU" | "APAC"
  renewal: string
}

const rows: Customer[] = [
  { id: "cus_0001", name: "Ava Patel", company: "Northstar Labs", status: "Active", plan: "Enterprise", seats: 185, revenue: 42100, owner: "Jordan Lee", region: "NA", renewal: "2026-09-14" },
  { id: "cus_0002", name: "Noah Kim", company: "Blue Harbor Health", status: "Trial", plan: "Team", seats: 42, revenue: 7600, owner: "Marta Rossi", region: "EU", renewal: "2026-06-02" },
  { id: "cus_0003", name: "Emma Silva", company: "Orbit Retail Group", status: "Active", plan: "Team", seats: 96, revenue: 18300, owner: "Jordan Lee", region: "NA", renewal: "2026-11-08" },
  // ...16 additional rows with the same shape
]
```

This is a good local-mode shape because the browser owns the full dataset and the table can evaluate search, filters, sorting, grouping, and selection without a server query layer.

## 2. Define columns [#2-define-columns]

The example columns do more than render labels. They decide filtering, sorting, grouping, and widths with built-in behaviors only.

```tsx
// client
const columns: DatatableColumn<Customer>[] = [
  {
    id: "company",
    header: "Company",
    accessorKey: "company",
    width: 250,
    enableSorting: true,
    enableFiltering: true,
    filterType: "text",
  },
  {
    id: "name",
    header: "Contact",
    accessorKey: "name",
    width: 190,
    enableSorting: true,
    enableFiltering: true,
    filterType: "text",
  },
  {
    id: "status",
    header: "Status",
    accessorKey: "status",
    width: 140,
    enableSorting: true,
    enableFiltering: true,
    enableGrouping: true,
    filterType: "text-list",
    filterOptions: {
      options: statuses.map((status) => ({ label: status, value: status })),
    },
  },
  {
    id: "revenue",
    header: "Revenue",
    accessorKey: "revenue",
    width: 130,
    enableSorting: true,
    enableFiltering: true,
    filterType: "number",
    cell: ({ getValue }) => `$${Number(getValue()).toLocaleString()}`,
  },
]
```

The full example also includes `plan`, `seats`, `owner`, `region`, and `renewal` to demonstrate text, list, number, and date filters in one place.

## 3. Mount with stable row IDs [#3-mount-with-stable-row-ids]

The core table stays simple:

```tsx
// client
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  initialState={{
    sorting: [{ id: "name", desc: false }],
    showHorizontalLines: false,
    showVerticalLines: false,
  }}
/>
```

That gives the example a stable contract before any extra interaction layers are added.

## 4. Toolbar [#4-toolbar]

The runnable example turns on quick search, filters, and display options from the toolbar.

```tsx
// client
toolbar={{
  quickSearch: {
    placeholder: "Search 1,200 customers...",
  },
  filterButton: true,
  displayOptions: true,
  copyLink: false,
  views: false,
}}
```

This is a good local example mix because it focuses on browsing the current dataset, not URL sharing or saved views.

## 5. Selection and bulk actions [#5-selection-and-bulk-actions]

Selection is enabled together with a small bulk-actions registry.

```tsx
// client
selection={{
  enabled: true,
  mode: "multi",
  showCheckboxOnHover: false,
  allowSelectAllMatching: true,
}}
bulkActions={{
  triggerLabel: "Actions",
  actions: bulkActions,
}}
```

The example bulk actions intentionally do lightweight local work:

* export selected IDs
* mark selected customers as reviewed

Each action also clears selection and closes the dialog so the workflow feels complete after the operation finishes.

## 6. Keyboard navigation and preview [#6-keyboard-navigation-and-preview]

The example supports both keyboard-first navigation and a floating preview panel.

```tsx
// client
keyboardNavigation={{
  enabled: true,
}}
rowActions={{
  onOpenRow: ({ row }) => {
    setLastAction(`Opened ${row.company}.`)
  },
  onTogglePreviewRow: ({ row, nextOpen }) => {
    setLastAction(`${nextOpen ? "Previewing" : "Closed preview for"} ${row.company}.`)
  },
}}
preview={{
  floating: {
    draggable: true,
    storageKey: "react-datatable-local-basic",
  },
  renderPreview: ({ row }) => (
    <CustomerPreview customer={row} />
  ),
}}
```

This is a good example of the local table acting like a real product surface instead of a bare data grid.

## Full example (single file) [#full-example-single-file]

<details>
  <summary>
    Expand to copy the full local customer table example
  </summary>

  ```tsx
  // client
  import { useMemo, useState } from "react"
  import { Datatable, type DataTableBulkAction, type DatatableColumn } from "./react-datatable"

  type CustomerStatus = "Active" | "Trial" | "Paused"
  type CustomerPlan = "Starter" | "Team" | "Enterprise"
  type CustomerRegion = "NA" | "EU" | "APAC"

  type Customer = {
    id: string
    name: string
    company: string
    status: CustomerStatus
    plan: CustomerPlan
    seats: number
    revenue: number
    owner: string
    region: CustomerRegion
    renewal: string
  }

  const rows: Customer[] = [
    { id: "cus_0001", name: "Ava Patel", company: "Northstar Labs", status: "Active", plan: "Enterprise", seats: 185, revenue: 42100, owner: "Jordan Lee", region: "NA", renewal: "2026-09-14" },
    { id: "cus_0002", name: "Noah Kim", company: "Blue Harbor Health", status: "Trial", plan: "Team", seats: 42, revenue: 7600, owner: "Marta Rossi", region: "EU", renewal: "2026-06-02" },
    { id: "cus_0003", name: "Emma Silva", company: "Orbit Retail Group", status: "Active", plan: "Team", seats: 96, revenue: 18300, owner: "Jordan Lee", region: "NA", renewal: "2026-11-08" },
    { id: "cus_0004", name: "Liam Turner", company: "Cinder Logistics", status: "Paused", plan: "Starter", seats: 18, revenue: 2400, owner: "Priya Nair", region: "APAC", renewal: "2026-05-29" },
    { id: "cus_0005", name: "Mia Dubois", company: "Kepler Finance", status: "Active", plan: "Enterprise", seats: 220, revenue: 50900, owner: "Marta Rossi", region: "EU", renewal: "2026-12-01" },
    { id: "cus_0006", name: "Ethan Brooks", company: "Summit Bio", status: "Trial", plan: "Starter", seats: 24, revenue: 3200, owner: "Diego Alvarez", region: "NA", renewal: "2026-07-10" },
    { id: "cus_0007", name: "Sophia Chen", company: "Copperline Energy", status: "Active", plan: "Team", seats: 88, revenue: 15400, owner: "Jordan Lee", region: "EU", renewal: "2026-10-21" },
    { id: "cus_0008", name: "Lucas Meyer", company: "Atlas Devices", status: "Paused", plan: "Team", seats: 57, revenue: 9100, owner: "Priya Nair", region: "NA", renewal: "2026-08-03" },
    { id: "cus_0009", name: "Isabella Reed", company: "Helio Security", status: "Active", plan: "Enterprise", seats: 164, revenue: 33700, owner: "Diego Alvarez", region: "APAC", renewal: "2026-09-30" },
    { id: "cus_0010", name: "James Park", company: "Maple Education", status: "Trial", plan: "Team", seats: 39, revenue: 6900, owner: "Marta Rossi", region: "EU", renewal: "2026-06-27" },
    { id: "cus_0011", name: "Charlotte Gray", company: "Riverbend Media", status: "Active", plan: "Starter", seats: 31, revenue: 5100, owner: "Priya Nair", region: "NA", renewal: "2026-10-05" },
    { id: "cus_0012", name: "Benjamin Cole", company: "Stonegate Manufacturing", status: "Paused", plan: "Enterprise", seats: 142, revenue: 27100, owner: "Jordan Lee", region: "EU", renewal: "2026-07-19" },
    { id: "cus_0013", name: "Amelia Ward", company: "Vista Hospitality", status: "Active", plan: "Team", seats: 73, revenue: 12900, owner: "Diego Alvarez", region: "APAC", renewal: "2026-11-15" },
    { id: "cus_0014", name: "Henry Price", company: "Signal Works", status: "Trial", plan: "Starter", seats: 16, revenue: 2100, owner: "Marta Rossi", region: "NA", renewal: "2026-05-18" },
    { id: "cus_0015", name: "Harper Quinn", company: "Lumen Foods", status: "Active", plan: "Enterprise", seats: 198, revenue: 44800, owner: "Jordan Lee", region: "EU", renewal: "2026-12-12" },
    { id: "cus_0016", name: "Alexander Diaz", company: "Nimbus Telecom", status: "Paused", plan: "Team", seats: 64, revenue: 11200, owner: "Priya Nair", region: "APAC", renewal: "2026-08-24" },
    { id: "cus_0017", name: "Evelyn Scott", company: "Forge Mobility", status: "Active", plan: "Team", seats: 104, revenue: 20100, owner: "Diego Alvarez", region: "NA", renewal: "2026-09-07" },
    { id: "cus_0018", name: "Michael Evans", company: "Prism Insurance", status: "Trial", plan: "Starter", seats: 22, revenue: 2800, owner: "Marta Rossi", region: "EU", renewal: "2026-06-14" },
    { id: "cus_0019", name: "Abigail Hill", company: "Tidal Commerce", status: "Active", plan: "Enterprise", seats: 176, revenue: 39200, owner: "Jordan Lee", region: "NA", renewal: "2026-11-28" },
    { id: "cus_0020", name: "Daniel Young", company: "Pioneer Clinics", status: "Paused", plan: "Starter", seats: 28, revenue: 3600, owner: "Priya Nair", region: "APAC", renewal: "2026-07-01" },
  ]

  const statuses: CustomerStatus[] = ["Active", "Trial", "Paused"]
  const plans: CustomerPlan[] = ["Starter", "Team", "Enterprise"]
  const regions: CustomerRegion[] = ["NA", "EU", "APAC"]

  function CustomerPreview({ customer }: { customer: Customer }) {
    return (
      <article className="mx-auto max-w-lg text-sm text-foreground">
        <h3 className="m-0 text-xl font-semibold">{customer.company}</h3>
        <p className="m-0 mt-1 text-muted-foreground">{customer.name}</p>
        <dl className="mt-4 grid grid-cols-2 gap-x-6 gap-y-2">
          <dt className="text-muted-foreground">Status</dt>
          <dd className="m-0 text-right">{customer.status}</dd>
          <dt className="text-muted-foreground">Plan</dt>
          <dd className="m-0 text-right">{customer.plan}</dd>
          <dt className="text-muted-foreground">Owner</dt>
          <dd className="m-0 text-right">{customer.owner}</dd>
          <dt className="text-muted-foreground">Region</dt>
          <dd className="m-0 text-right">{customer.region}</dd>
          <dt className="text-muted-foreground">Seats</dt>
          <dd className="m-0 text-right">{customer.seats}</dd>
          <dt className="text-muted-foreground">Revenue</dt>
          <dd className="m-0 text-right">${customer.revenue.toLocaleString()}</dd>
          <dt className="text-muted-foreground">Renewal</dt>
          <dd className="m-0 text-right">{customer.renewal}</dd>
        </dl>
      </article>
    )
  }

  export function LocalCustomerTableExample() {
    const [lastAction, setLastAction] = useState("Ready: local rows loaded.")

    const columns = useMemo<DatatableColumn<Customer>[]>(() => [
      {
        id: "company",
        header: "Company",
        accessorKey: "company",
        width: 250,
        enableSorting: true,
        enableFiltering: true,
        filterType: "text",
      },
      {
        id: "name",
        header: "Contact",
        accessorKey: "name",
        width: 190,
        enableSorting: true,
        enableFiltering: true,
        filterType: "text",
      },
      {
        id: "status",
        header: "Status",
        accessorKey: "status",
        width: 130,
        enableSorting: true,
        enableFiltering: true,
        enableGrouping: true,
        filterType: "text-list",
        filterOptions: {
          options: statuses.map((status) => ({ label: status, value: status })),
        },
      },
      {
        id: "plan",
        header: "Plan",
        accessorKey: "plan",
        width: 130,
        enableSorting: true,
        enableFiltering: true,
        enableGrouping: true,
        filterType: "text-list",
        filterOptions: {
          options: plans.map((plan) => ({ label: plan, value: plan })),
        },
      },
      {
        id: "region",
        header: "Region",
        accessorKey: "region",
        width: 120,
        enableSorting: true,
        enableFiltering: true,
        enableGrouping: true,
        filterType: "text-list",
        filterOptions: {
          options: regions.map((region) => ({ label: region, value: region })),
        },
      },
      {
        id: "seats",
        header: "Seats",
        accessorKey: "seats",
        width: 110,
        enableSorting: true,
        enableFiltering: true,
        filterType: "number",
      },
      {
        id: "revenue",
        header: "Revenue",
        accessorKey: "revenue",
        width: 130,
        enableSorting: true,
        enableFiltering: true,
        filterType: "number",
        cell: ({ getValue }) => `$${Number(getValue()).toLocaleString()}`,
      },
      {
        id: "owner",
        header: "Owner",
        accessorKey: "owner",
        width: 170,
        enableSorting: true,
        enableFiltering: true,
        enableGrouping: true,
        filterType: "text-list",
        filterOptions: {
          options: Array.from(new Set(rows.map((row) => row.owner))).map((owner) => ({ label: owner, value: owner })),
        },
      },
      {
        id: "renewal",
        header: "Renewal",
        accessorKey: "renewal",
        width: 140,
        enableSorting: true,
        enableFiltering: true,
        filterType: "date",
      },
    ], [])

    const bulkActions = useMemo<DataTableBulkAction<Customer>[]>(() => [
      {
        id: "mark-reviewed",
        title: "Mark as reviewed",
        keywords: ["review", "done"],
        onSelect: (context) => {
          setLastAction(`Marked ${context.selectedCount} customer${context.selectedCount === 1 ? "" : "s"} as reviewed.`)
          context.clearSelection()
          context.closeDialog()
        },
      },
      {
        id: "export-selection",
        title: "Export selected IDs",
        keywords: ["export", "ids"],
        onSelect: (context) => {
          const ids = context.selectedRows.map((row) => row.id).join(", ")
          setLastAction(ids.length > 0 ? `Selected IDs: ${ids}` : "No rows selected.")
          context.clearSelection()
          context.closeDialog()
        },
      },
    ], [])

    return (
      <section className="rounded-xl border border-border bg-card p-4">
        <p className="mb-3 text-sm text-muted-foreground">{lastAction}</p>
        <div className="h-[560px] overflow-hidden rounded-lg border border-border">
          <Datatable
            tableKey="customers"
            data={rows}
            columns={columns}
            getRowId={(row) => row.id}
            toolbar={{
              quickSearch: {
                placeholder: "Search 20 customers...",
              },
              filterButton: true,
              displayOptions: true,
              copyLink: false,
              views: false,
            }}
            initialState={{
              sorting: [{ id: "company", desc: false }],
              showHorizontalLines: false,
              showVerticalLines: false,
            }}
            selection={{
              enabled: true,
              mode: "multi",
              showCheckboxOnHover: false,
              allowSelectAllMatching: true,
            }}
            bulkActions={{
              triggerLabel: "Actions",
              actions: bulkActions,
            }}
            keyboardNavigation={{
              enabled: true,
            }}
            rowActions={{
              onOpenRow: ({ row }) => {
                setLastAction(`Opened ${row.company}.`)
              },
              onTogglePreviewRow: ({ row, nextOpen }) => {
                setLastAction(`${nextOpen ? "Previewing" : "Closed preview for"} ${row.company}.`)
              },
            }}
            preview={{
              floating: {
                draggable: true,
                storageKey: "docs-local-customer-example",
              },
              renderPreview: ({ row }) => <CustomerPreview customer={row} />,
            }}
          />
        </div>
      </section>
    )
  }
  ```
</details>

## Where to go next [#where-to-go-next]

* For the setup boundary behind this example, read [Getting started](/docs/quickstart/getting-started).
* For the top-level contract decisions, read [Define your table](/docs/guides/define-your-table) and [Define columns](/docs/guides/define-columns).
* For a server-owned variant, continue to [Paginated Table](/docs/examples/paginated-table).


# Multi-select cell (https://react-datatable.com/docs/examples/multi-select-cell)

Use this when one field needs a small set of labels, tags, or categories without expanding into a full editor.

<InteractiveCellBadge />

<CustomCellPreviewCard codeHref="#build-the-react-component" codePreview="customCellDocSnippets[&#x22;multi-select&#x22;].component">
  <CustomCellInlinePreview example="multi-select" />
</CustomCellPreviewCard>

## Build the React component [#build-the-react-component]

The main job here is summarizing several values into one compact surface and exposing a small add/remove interaction.

```tsx
import { Check, Plus } from "lucide-react"
import { Badge } from "@/components/ui/badge"
import {
  Command,
  CommandEmpty,
  CommandInput,
  CommandItem,
  CommandList,
} from "@/components/ui/command"
import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover"

type Tag = {
  id: string
  name: string
  color: string
}

export function MultiSelectCell({
  value,
  options,
  onChange,
}: {
  value: Tag[]
  options: Tag[]
  onChange: (value: Tag[]) => void
}) {
  const selectedIds = new Set(value.map((tag) => tag.id))

  return (
    <Popover>
      <PopoverTrigger asChild>
        <button className="flex min-h-8 w-full flex-wrap items-center gap-1 rounded-md px-1.5 py-1 text-left hover:bg-accent" type="button">
          {value.length === 0 ? (
            <span className="inline-flex items-center gap-1 text-sm text-muted-foreground">
              <Plus className="size-3.5" /> Add tags
            </span>
          ) : (
            <>
              {value.slice(0, 2).map((tag) => (
                <Badge className="gap-1 rounded-full" key={tag.id} variant="secondary">
                  <span className="size-1.5 rounded-full" style={{ backgroundColor: tag.color }} />
                  {tag.name}
                </Badge>
              ))}
            </>
          )}
        </button>
      </PopoverTrigger>
      <PopoverContent align="start" className="w-[260px] p-0">
        <Command>
          <CommandInput placeholder="Add tags..." />
          <CommandList>
            <CommandEmpty>No tags found.</CommandEmpty>
            {options.map((tag) => {
              const selected = selectedIds.has(tag.id)
              return (
                <CommandItem
                  key={tag.id}
                  onSelect={() => {
                    const next = selected ? value.filter((item) => item.id !== tag.id) : [...value, tag]
                    onChange(next)
                  }}
                  value={tag.name}
                >
                  <span className="inline-flex size-4 items-center justify-center rounded-sm border border-border">
                    {selected ? <Check className="size-3" /> : null}
                  </span>
                  <span className="size-2 rounded-full" style={{ backgroundColor: tag.color }} />
                  <span>{tag.name}</span>
                </CommandItem>
              )
            })}
          </CommandList>
        </Command>
      </PopoverContent>
    </Popover>
  )
}
```

## Wire it into a column definition [#wire-it-into-a-column-definition]

The important detail is the accessor: the column still exposes a stable string representation for table semantics even though the UI renders badges from richer objects.

<AccessorNote accessor="customCellDocSnippets[&#x22;multi-select&#x22;].accessor" />

```tsx
{
  id: "tags",
  header: "Tags",
  accessorFn: (row) => row.tags.map((tag) => tag.name).join(", "),
  width: 260,
  enableSorting: false,
  enableFiltering: false,
  cell: ({ row }) => (
    <MultiSelectCell
      value={row.original.tags}
      options={tagOptions}
      onChange={(tags) => updateRow(row.original.id, { tags })}
    />
  ),
}
```

## Render it in a small table [#render-it-in-a-small-table]

The table example keeps only the tags column custom so you can see how the badge picker sits inside a normal Datatable.

```tsx
function TagsExampleTable() {
  const [rows, setRows] = useState(seedRows)

  const updateRow = (id: string, patch: Partial<CustomerRow>) => {
    setRows((current) => current.map((row) => (row.id === id ? { ...row, ...patch } : row)))
  }

  return <Datatable tableKey="custom-cells" data={rows} columns={columns(updateRow)} getRowId={(row) => row.id} toolbar={false} />
}
```

<CustomCellMiniTable example="multi-select" />

## Persist changes with optimistic update [#persist-changes-with-optimistic-update]

For server sync, treat the selected tags as a small optimistic patch and then refetch the authoritative row.

```tsx
async function updateTags(id: string, tags: Tag[]) {
  setRows((current) => current.map((row) => (row.id === id ? { ...row, tags } : row)))

  try {
    await api.customers.updateTags({ id, tagIds: tags.map((tag) => tag.id) })
    await refetchCustomers()
  } catch {
    await refetchCustomers()
  }
}
```

<Callout title="Key takeaway">
  If the tag UI starts to feel like a whole form, move that workflow into preview or a detail screen instead of overloading the cell.
</Callout>


# Paginated Table (https://react-datatable.com/docs/examples/paginated-table)

This example keeps fetching and shaping rows on the server by using the datatable in **paginated online** mode, so you get clear page boundaries instead of an infinitely growing list. The live table below behaves like a real product surface: each interaction sends an `OnlineQueryInput` to this site’s demo API, and the table paints whatever rows, totals, and filter metadata come back. When someone opens a multi-select list filter, the response can include **facets** so each choice shows a count that matches the current filters; the field names and shapes are documented under [Online API](/docs/reference/online-api).

<Callout title="Copy and adapt this example">
  Swap the column definitions and `query` function for your own route and data layer. Keep stable column IDs, a dataset-level `queryKey`, and backend-owned totals so the footer and filters stay honest.
</Callout>

<PaginatedTableInlineExample />

Before you start, install the datatable source into your app and add the server helpers when you need them. See [Installation](/docs/installation) for the `npx @react-datatable/cli install` command and how to use your license token.

## 1. Shared row type [#1-shared-row-type]

Define the row shape **once** (for example in `shared/customer.ts` or `contracts/customer.ts`) and import it from both your React table and your API handler. That way the columns, `getRowId`, and `OnlineQueryResponse<Customer>` stay aligned with the JSON your route actually returns, without duplicating stringly-typed fields.

The browser still does not load the full dataset: the API returns one page (plus totals metadata) at a time, scoped by tenant, permissions, and whatever else your handler enforces.

```tsx
// shared (import from the same module in your Vite app and in your server process)
type Customer = {
  id: string
  company: string
  name: string
  status: string
  plan: string
  region: string
  seats: number
  revenue: number
  owner: string
  renewal: string
}
```

## 2. Define columns [#2-define-columns]

This step is **client-only**: you configure `DatatableColumn` so the table knows headers, widths, and which built-in filter and sort UIs to show. Give every column a stable `id`. When you add the route in **step 7**, reuse those same ids in your server column map so filters and sorts line up with what the table sends.

```tsx
// client
import type { DatatableColumn } from "./react-datatable"

const statuses = ["Active", "Trial", "Paused"] as const

const columns: DatatableColumn<Customer>[] = [
  {
    id: "company",
    header: "Company",
    accessorKey: "company",
    width: 240,
    enableSorting: true,
    enableFiltering: true,
    filterType: "text",
  },
  {
    id: "status",
    header: "Status",
    accessorKey: "status",
    width: 150,
    enableSorting: true,
    enableFiltering: true,
    enableGrouping: true,
    filterType: "text-list",
    filterOptions: {
      options: statuses.map((status) => ({ label: status, value: status })),
    },
  },
]
```

## 3. Online pagination [#3-online-pagination]

Use `online` instead of `data`. The table owns interaction state; the backend owns matching rows, totals, and facets.

```tsx
// client
import { Datatable } from "./react-datatable"

<Datatable
  tableKey="customers"
  columns={columns}
  getRowId={(row) => row.id}
  online={{
    mode: "pagination",
    queryKey: ["customers", workspaceId],
    pageSize: 50,
    supportedGroupingColumns: ["status"],
    query: fetchCustomersPage,
  }}
  initialState={{
    sorting: [{ id: "company", desc: false }],
  }}
/>
```

## 4. Implement the query function [#4-implement-the-query-function]

The smallest useful implementation is a `fetch` that posts JSON and returns `OnlineQueryResponse<TData>`. The route sketch in step 7.6 uses `runInMemoryDatatableQuery` on every row you load for the tenant (unfiltered within that scope); the helper applies `input` in memory. That is easy to validate but does not scale if the slice is huge, so plan to replace it with a database-backed query while keeping the same route contract. See [Server helper API](/docs/reference/server-helper-api) and [Server query endpoint](/docs/guides/server-query-endpoint).

```tsx
// client
import type { OnlineQueryInput, OnlineQueryResponse } from "react-datatable-server"

async function fetchCustomersPage(input: OnlineQueryInput): Promise<OnlineQueryResponse<Customer>> {
  const response = await fetch("/api/customers/table", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(input),
  })

  if (!response.ok) {
    throw new Error("Failed to load customers")
  }

  return response.json()
}
```

## 5. Add the toolbar and selection configuration [#5-add-the-toolbar-and-selection-configuration]

Online mode moves row computation to the server; you can still expose search, filters, display options, selection, and bulk actions on the client.

```tsx
// client
toolbar={{
  quickSearch: { placeholder: "Search Customers..." },
  filterButton: true,
  displayOptions: true,
  copyLink: false,
  views: false,
}}
selection={{
  enabled: true,
  mode: "multi",
  showCheckboxOnHover: false,
  allowSelectAllMatching: true,
}}
```

## 6. Viewport virtualization [#6-viewport-virtualization]

Pagination decides **which rows the server returns**. Viewport virtualization decides **how many loaded rows the browser mounts**. They compose cleanly:

```tsx
// client
virtualization={{
  mode: "viewport",
  rowOverscanCount: 12,
}}
```

## 7. Implement the server-side route [#7-implement-the-server-side-route]

This walkthrough uses **Hono** and **Drizzle** so you have a concrete, copy-pasteable server file. You can use any web framework and data layer you like; what matters is that your handler accepts `OnlineQueryInput` as JSON and returns `OnlineQueryResponse` for the same row type as the table. Shape that handler like a normal HTTP API route: method, path, JSON body, and JSON response are covered in [Server query endpoint](/docs/guides/server-query-endpoint).

Expose one HTTP route (for example `POST /api/customers/table`) on your API process. It should read the JSON body as `OnlineQueryInput` and respond with `OnlineQueryResponse` for the same row type you share with the client in step 1.

### 7.1 Install packages [#71-install-packages]

<PackageManagerCommandTabs
  commands="{
  pnpm: `pnpm add hono drizzle-orm pg
pnpm add -D drizzle-kit @types/pg`,
  npm: `npm install hono drizzle-orm pg
npm install -D drizzle-kit @types/pg`,
  yarn: `yarn add hono drizzle-orm pg
yarn add -D drizzle-kit @types/pg`,
  bun: `bun add hono drizzle-orm pg
bun add --dev drizzle-kit @types/pg`,
}"
/>

### 7.2 Open Postgres and create a Drizzle client [#72-open-postgres-and-create-a-drizzle-client]

Create one `pg.Pool` from `DATABASE_URL` for the whole process, then pass it to `drizzle`. Reuse that `db` instance from your route handlers.

```ts
// server
import { drizzle } from "drizzle-orm/node-postgres"
import { Pool } from "pg"

const pool = new Pool({ connectionString: process.env.DATABASE_URL })
export const db = drizzle(pool)
```

### 7.3 Model the table with Drizzle [#73-model-the-table-with-drizzle]

Add a `pgTable` that matches your real migration: primary key, a tenant or `workspace_id` column for scoping, and every column your `DatatableColumn` definitions read through `accessorKey` or `accessorFn`.

```ts
// server/schema/customers.ts (example: grow this to match step 2 and your migrations)
import { integer, pgTable, text } from "drizzle-orm/pg-core"

export const customers = pgTable("customers", {
  id: text("id").primaryKey(),
  workspaceId: text("workspace_id").notNull(),
  company: text("company").notNull(),
  contactName: text("contact_name").notNull(),
  status: text("status").notNull(),
  plan: text("plan").notNull(),
  region: text("region").notNull(),
  seats: integer("seats").notNull(),
  revenue: integer("revenue").notNull(),
  owner: text("owner").notNull(),
  renewal: text("renewal").notNull(),
})
```

### 7.4 Map SQL rows to your shared row type [#74-map-sql-rows-to-your-shared-row-type]

`db.select()` returns rows in the shape of your Drizzle schema. Map each row to the same `Customer` (or product) interface the React table uses (for example, map `contact_name` in SQL to `name` in TypeScript) so the rest of the pipeline works with one type.

```ts
// server/map-customer.ts
import type { Customer } from "../../shared/customer"
import type { customers } from "./schema/customers"

type CustomerRow = typeof customers.$inferSelect

export function mapRow(row: CustomerRow): Customer {
  return {
    id: row.id,
    company: row.company,
    name: row.contactName,
    status: row.status,
    plan: row.plan,
    region: row.region,
    seats: row.seats,
    revenue: row.revenue,
    owner: row.owner,
    renewal: row.renewal,
  }
}
```

### 7.5 Import the same column definitions as the client [#75-import-the-same-column-definitions-as-the-client]

Import the `DatatableColumn<Customer>[]` from step 2 (in a real repo, move that array to a small shared module and import it from both Vite and the server bundle). The column `id` values are what the table sends in `filters` and `sorting`; your server logic must recognize those ids.

```ts
// server/customers-table-route.ts
import type { Customer } from "../../shared/customer"
import { customerOnlineColumns } from "../../shared/customer-online-columns"
// Export `customerOnlineColumns` once from shared/customer-online-columns.ts (the same
// array you use in step 2) so filters and sorts hit the same column ids on the server.
```

### 7.6 Implement `POST /api/customers/table` [#76-implement-post-apicustomerstable]

1. Resolve the signed-in user and `workspaceId` (or equivalent tenant scope).
2. `const input = (await c.req.json()) as OnlineQueryInput`.
3. Load rows for that scope only, for example `await db.select().from(customers).where(eq(customers.workspaceId, workspaceId))`.
4. Map rows with your mapper from 7.4 into `Customer[]`.
5. Turn `input` plus `data` into an `OnlineQueryResponse` (see the snippet below and the note that follows it).

Return `c.json(response)` with the correct `content-type` for JSON.

```ts
// server/customers-table-route.ts
import { Hono } from "hono"
import { eq } from "drizzle-orm"
import type { OnlineQueryInput } from "react-datatable-server"
import { runInMemoryDatatableQuery } from "react-datatable-server"
import { customerOnlineColumns } from "../../shared/customer-online-columns"
import { customers } from "./schema/customers"
import { db } from "./db"
import { mapRow } from "./map-customer"

export function registerCustomersTableRoute(app: Hono) {
  app.post("/api/customers/table", async (c) => {
    const workspaceId = c.req.header("x-workspace-id") ?? "demo_workspace"
    const input = (await c.req.json()) as OnlineQueryInput

    const rows = await db.select().from(customers).where(eq(customers.workspaceId, workspaceId))
    const data = rows.map(mapRow)

    const response = await runInMemoryDatatableQuery({
      data,
      columns: customerOnlineColumns,
      input,
      getRowId: (row) => row.id,
    })

    return c.json(response)
  })
}
```

`runInMemoryDatatableQuery` takes the **unfiltered** row array you pass as `data` (for example every mapped customer in the workspace) and applies the online query shape from `input` in process memory: filters, sorts, grouping, pagination, and the other fields the table sends. You do **not** pre-slice `data` to the current page; the helper returns the correct page and metadata in `OnlineQueryResponse`. That makes it a fast way to stand up the route and **verify online mode and column wiring** before you build real SQL.

It is **not** a good fit for large datasets, because each request loads the full scoped table (or whatever subset your `where` returns) into server RAM. When behavior looks right in the browser, move the same contract to a database-backed planner or query builder so filtering and paging happen in the engine instead of in Node. [Server query endpoint](/docs/guides/server-query-endpoint) is the place to start for that handoff.

### 7.7 Mount Hono and register the route [#77-mount-hono-and-register-the-route]

Create `const app = new Hono()`, call your register function from step 7.6, then export `app` for your runtime (Bun, Node with your adapter, etc.).

```ts
// server/app.ts
import { Hono } from "hono"
import { registerCustomersTableRoute } from "./customers-table-route"

const app = new Hono()
registerCustomersTableRoute(app)

export default app
```

The all-in-one server snippet under **Full examples** inlines the same mapper, columns, and handler in a single file instead of splitting them across modules.

The **same handler** also powers [Infinite Scroll Table](/docs/examples/infinite-scroll-table): the client only changes `online.mode` and how it interprets `offset` / `hasMore`; the server still reads `input.mode`, `input.offset`, and `input.limit` from the JSON body.

The live table above uses the full showcase columns, row preview, and CSV export wired to this site’s `/api/showcase/export`. The copyable blocks below are a smaller baseline you can paste into your own repository; follow [Server query endpoint](/docs/guides/server-query-endpoint) to implement `POST /api/customers/export` (or your chosen path) for the same `serverExecutor` contract.

## Full examples [#full-examples]

<details>
  <summary>
    Expand to copy a minimal paginated online table (React)
  </summary>

  ```tsx
  // client
  import { useMemo } from "react"
  import {
    Datatable,
    type DataTableBulkAction,
    type DataTableBulkServerActionRequest,
    type DatatableColumn,
  } from "./react-datatable"
  import type { OnlineQueryInput, OnlineQueryResponse } from "react-datatable-server"

  type Customer = {
    id: string
    company: string
    name: string
    status: "Active" | "Trial" | "Paused"
    plan: string
    region: string
    seats: number
    revenue: number
    owner: string
    renewal: string
  }

  const statuses = ["Active", "Trial", "Paused"] as const

  async function fetchCustomersPage(input: OnlineQueryInput): Promise<OnlineQueryResponse<Customer>> {
    const response = await fetch("/api/customers/table", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify(input),
    })
    if (!response.ok) {
      throw new Error("Failed to load customers")
    }
    return response.json()
  }

  /** POST /api/customers/export. Same selection payload contract as the bulk-actions guide. */
  async function customersBulkServerExecutor(request: DataTableBulkServerActionRequest): Promise<void> {
    if (request.actionId !== "export-customers-csv") {
      return
    }

    const response = await fetch("/api/customers/export", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        selection: request.selection,
        payload: request.payload,
      }),
    })

    if (!response.ok) {
      throw new Error(`Export failed: ${response.status}`)
    }

    const blob = await response.blob()
    const url = URL.createObjectURL(blob)
    const link = document.createElement("a")
    link.href = url
    link.download = "customers-export.csv"
    link.click()
    URL.revokeObjectURL(url)
  }

  export function CustomersPaginatedTable({ workspaceId }: { workspaceId: string }) {
    const columns = useMemo<DatatableColumn<Customer>[]>(
      () => [
        {
          id: "company",
          header: "Company",
          accessorKey: "company",
          width: 240,
          enableSorting: true,
          enableFiltering: true,
          filterType: "text",
        },
        {
          id: "status",
          header: "Status",
          accessorKey: "status",
          width: 140,
          enableSorting: true,
          enableFiltering: true,
          enableGrouping: true,
          filterType: "text-list",
          filterOptions: {
            options: statuses.map((status) => ({ label: status, value: status })),
          },
        },
      ],
      []
    )

    const bulkActions = useMemo<DataTableBulkAction<Customer>[]>(
      () => [
        {
          id: "export-selection",
          title: "Export selected CSV",
          execution: "server",
          serverActionId: "export-customers-csv",
          buildServerPayload: () => ({ requestedBy: "customers-table" }),
        },
      ],
      []
    )

    return (
      <div className="h-[560px] overflow-hidden rounded-lg border">
        <Datatable
          tableKey="customers"
          columns={columns}
          getRowId={(row) => row.id}
          online={{
            mode: "pagination",
            queryKey: ["customers", workspaceId],
            pageSize: 50,
            supportedGroupingColumns: ["status"],
            query: fetchCustomersPage,
          }}
          toolbar={{
            quickSearch: { placeholder: "Search Customers..." },
            filterButton: true,
            displayOptions: true,
            copyLink: false,
            views: false,
          }}
          initialState={{
            sorting: [{ id: "company", desc: false }],
          }}
          virtualization={{ mode: "viewport", rowOverscanCount: 12 }}
          selection={{
            enabled: true,
            mode: "multi",
            showCheckboxOnHover: false,
            allowSelectAllMatching: true,
          }}
          bulkActions={{
            triggerLabel: "Actions",
            actions: bulkActions,
            serverExecutor: customersBulkServerExecutor,
          }}
        />
      </div>
    )
  }
  ```
</details>

<details>
  <summary>
    Expand to copy a minimal paginated online table (Hono + Drizzle server)
  </summary>

  ```ts
  // server
  /**
   * customers-table-api.ts: single-file sketch you can split into schema/, routes/, etc.
   * Serves POST /api/customers/table for both pagination and infinite online modes.
   *
   * Teaching default: `runInMemoryDatatableQuery` runs the online planner on the scoped
   * row array. Replace that call with SQL-backed planning when the workspace slice is too
   * large to load whole; keep the same JSON request/response contract.
   */
  import { Hono } from "hono"
  import { drizzle } from "drizzle-orm/node-postgres"
  import { eq } from "drizzle-orm"
  import { Pool } from "pg"
  import { integer, pgTable, text } from "drizzle-orm/pg-core"
  import type { OnlineQueryInput } from "react-datatable-server"
  import { runInMemoryDatatableQuery } from "react-datatable-server"
  import type { DatatableColumn } from "./react-datatable"

  // --- Drizzle schema (match your migrations) ---
  const customers = pgTable("customers", {
    id: text("id").primaryKey(),
    workspaceId: text("workspace_id").notNull(),
    company: text("company").notNull(),
    contactName: text("contact_name").notNull(),
    status: text("status").notNull(),
    plan: text("plan").notNull(),
    region: text("region").notNull(),
    seats: integer("seats").notNull(),
    revenue: integer("revenue").notNull(),
    owner: text("owner").notNull(),
    renewal: text("renewal").notNull(),
  })

  type CustomerRow = typeof customers.$inferSelect

  type Customer = {
    id: string
    workspaceId: string
    company: string
    name: string
    status: "Active" | "Trial" | "Paused"
    plan: string
    region: string
    seats: number
    revenue: number
    owner: string
    renewal: string
  }

  function mapRow(row: CustomerRow): Customer {
    return {
      id: row.id,
      workspaceId: row.workspaceId,
      company: row.company,
      name: row.contactName,
      status: row.status as Customer["status"],
      plan: row.plan,
      region: row.region,
      seats: row.seats,
      revenue: row.revenue,
      owner: row.owner,
      renewal: row.renewal,
    }
  }

  const statuses = ["Active", "Trial", "Paused"] as const

  // --- Keep in sync with the React table (extract to shared/ in real apps) ---
  const customerOnlineColumns: DatatableColumn<Customer>[] = [
    {
      id: "company",
      header: "Company",
      accessorKey: "company",
      width: 240,
      enableSorting: true,
      enableFiltering: true,
      filterType: "text",
    },
    {
      id: "name",
      header: "Contact",
      accessorKey: "name",
      width: 190,
      enableSorting: true,
      enableFiltering: true,
      filterType: "text",
    },
    {
      id: "status",
      header: "Status",
      accessorKey: "status",
      width: 140,
      enableSorting: true,
      enableFiltering: true,
      enableGrouping: true,
      filterType: "text-list",
      filterOptions: {
        options: statuses.map((status) => ({ label: status, value: status })),
      },
    },
    {
      id: "plan",
      header: "Plan",
      accessorKey: "plan",
      width: 130,
      enableSorting: true,
      enableFiltering: true,
      enableGrouping: true,
      filterType: "text-list",
      filterOptions: {
        options: ["Starter", "Team", "Enterprise"].map((plan) => ({ label: plan, value: plan })),
      },
    },
    {
      id: "region",
      header: "Region",
      accessorKey: "region",
      width: 120,
      enableSorting: true,
      enableFiltering: true,
      enableGrouping: true,
      filterType: "text-list",
      filterOptions: {
        options: ["NA", "EU", "APAC"].map((region) => ({ label: region, value: region })),
      },
    },
    {
      id: "seats",
      header: "Seats",
      accessorKey: "seats",
      width: 110,
      enableSorting: true,
      enableFiltering: true,
      filterType: "number",
    },
    {
      id: "revenue",
      header: "Revenue",
      accessorKey: "revenue",
      width: 130,
      enableSorting: true,
      enableFiltering: true,
      filterType: "number",
    },
    {
      id: "owner",
      header: "Owner",
      accessorKey: "owner",
      width: 170,
      enableSorting: true,
      enableFiltering: true,
      filterType: "text",
    },
    {
      id: "renewal",
      header: "Renewal",
      accessorKey: "renewal",
      width: 140,
      enableSorting: true,
      enableFiltering: true,
      filterType: "date",
    },
  ]

  const pool = new Pool({ connectionString: process.env.DATABASE_URL })
  const db = drizzle(pool)

  const app = new Hono()

  app.post("/api/customers/table", async (c) => {
    // Replace with real session / tenant resolution.
    const workspaceId = c.req.header("x-workspace-id") ?? "demo_workspace"

    const input = (await c.req.json()) as OnlineQueryInput

    const rows = await db.select().from(customers).where(eq(customers.workspaceId, workspaceId))

    const data = rows.map(mapRow)

    const response = await runInMemoryDatatableQuery({
      data,
      columns: customerOnlineColumns,
      input,
      getRowId: (row) => row.id,
    })

    return c.json(response)
  })

  export default app
  ```

  For a minimal local run, create the pool from `DATABASE_URL`, start Hono on a port, and point the React `fetch` URL at `http://127.0.0.1:8787/api/customers/table` (or mount this `app` behind your framework’s dev proxy under `/api/customers/table`). When you outgrow the in-memory helper, follow [Server query planning](/docs/guides/server-query-planning) and [Server query execution](/docs/guides/server-query-execution) to push filters, sorts, and pagination into the database.
</details>

## Where to go next [#where-to-go-next]

* For the data-boundary decision, read [Choose a data mode](/docs/guides/choose-a-data-mode).
* For request and response shapes, read [Online API](/docs/reference/online-api).
* For continuous loading instead of pages, read [Infinite Scroll Table](/docs/examples/infinite-scroll-table).
* For the HTTP contract used by online tables and server bulk payloads, read [Server query endpoint](/docs/guides/server-query-endpoint).


# Progress cell (https://react-datatable.com/docs/examples/progress-cell)

Use this when a numeric field needs faster visual scanning than plain text can provide.

<CustomCellPreviewCard codeHref="#build-the-react-component" codePreview="customCellDocSnippets[&#x22;progress&#x22;].component">
  <CustomCellInlinePreview example="progress" />
</CustomCellPreviewCard>

## Build the React component [#build-the-react-component]

This is a pure presentation cell. It turns one numeric value into a compact bar plus label and stays very cheap to render.

```tsx
export function ProgressCell({ value }: { value: number }) {
  const tone = value >= 70 ? "bg-sky-500" : value >= 40 ? "bg-amber-500" : "bg-red-500"

  return (
    <span className="inline-flex items-center gap-1.5 text-[12px] leading-4 font-medium">
      <span>{value}</span>
      <span aria-hidden="true" className={"size-2 rounded-full " + tone} />
    </span>
  )
}
```

## Wire it into a column definition [#wire-it-into-a-column-definition]

Because the value is still just a number, the column contract stays extremely simple.

<AccessorNote accessor="customCellDocSnippets[&#x22;progress&#x22;].accessor" />

```tsx
{
  id: "health",
  header: "Health",
  accessorKey: "health",
  width: 160,
  enableSorting: false,
  enableFiltering: false,
  cell: ({ row }) => <ProgressCell value={row.original.health} />,
}
```

## Render it in a small table [#render-it-in-a-small-table]

The table demo shows the progress bar beside plain contact fields so the visual scan benefit is easy to feel.

```tsx
const columns: DatatableColumn<CustomerRow>[] = [
  { id: "name", header: "Contact", accessorKey: "name" },
  { id: "company", header: "Company", accessorKey: "company" },
  {
    id: "health",
    header: "Health",
    accessorKey: "health",
    cell: ({ row }) => <ProgressCell value={row.original.health} />,
  },
]

<Datatable tableKey="custom-cells" data={rows} columns={columns} getRowId={(row) => row.id} toolbar={false} />
```

<CustomCellMiniTable example="progress" />

<Callout title="Key takeaway">
  Progress cells are strongest when they stay dumb and cheap: one value in, one compact visual out.
</Callout>


# Single select cell (https://react-datatable.com/docs/examples/single-select-cell)

Use this for compact states like status, stage, or lifecycle where a small dropdown is enough.

<InteractiveCellBadge />

<CustomCellPreviewCard codeHref="#build-the-react-component" codePreview="customCellDocSnippets[&#x22;single-select&#x22;].component">
  <CustomCellInlinePreview example="single-select" />
</CustomCellPreviewCard>

## Build the React component [#build-the-react-component]

This is a good example of a cell that feels product-specific while still being ordinary React code.

```tsx
import { Check } from "lucide-react"
import {
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuItem,
  DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"

const toneByStatus = {
  Active: "#10b981",
  Trial: "#8b5cf6",
  Paused: "#f59e0b",
}

const statuses = ["Active", "Trial", "Paused"] as const

type Status = (typeof statuses)[number]

export function SingleSelectCell({
  value,
  onChange,
}: {
  value: Status
  onChange: (value: Status) => void
}) {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger asChild>
        <button className="flex w-full items-center gap-1.5 rounded-md px-1.5 py-1 text-left text-[12px] leading-4 hover:bg-accent" type="button">
          <span className="size-2 rounded-full" style={{ backgroundColor: toneByStatus[value] }} />
          <span>{value}</span>
        </button>
      </DropdownMenuTrigger>
      <DropdownMenuContent align="start" className="w-40">
        {statuses.map((status) => (
          <DropdownMenuItem key={status} className="text-[12px] leading-4" onClick={() => onChange(status)}>
            <span className="size-2 rounded-full" style={{ backgroundColor: toneByStatus[status] }} />
            <span>{status}</span>
            {status === value ? <Check aria-hidden="true" className="ml-auto size-4" /> : null}
          </DropdownMenuItem>
        ))}
      </DropdownMenuContent>
    </DropdownMenu>
  )
}
```

## Wire it into a column definition [#wire-it-into-a-column-definition]

Keep the finite state field anchored to the column contract, then let the cell own the compact dropdown treatment.

<AccessorNote accessor="customCellDocSnippets[&#x22;single-select&#x22;].accessor" />

```tsx
{
  id: "status",
  header: "Status",
  accessorKey: "status",
  width: 140,
  enableSorting: false,
  enableFiltering: false,
  cell: ({ row }) => (
    <SingleSelectCell
      value={row.original.status}
      onChange={(status) => updateRow(row.original.id, { status })}
    />
  ),
}
```

## Render it in a small table [#render-it-in-a-small-table]

The demo table uses one custom status column and plain surrounding columns so the pattern stays easy to scan.

```tsx
function StatusExampleTable() {
  const [rows, setRows] = useState(seedRows)

  const updateRow = (id: string, patch: Partial<CustomerRow>) => {
    setRows((current) => current.map((row) => (row.id === id ? { ...row, ...patch } : row)))
  }

  return <Datatable tableKey="custom-cells" data={rows} columns={columns(updateRow)} getRowId={(row) => row.id} toolbar={false} />
}
```

<CustomCellMiniTable example="single-select" />

## Persist changes with optimistic update [#persist-changes-with-optimistic-update]

If status changes should sync to a backend, optimistic update first and let the server remain authoritative after the mutation settles.

```tsx
async function updateStatus(id: string, status: Status) {
  setRows((current) => current.map((row) => (row.id === id ? { ...row, status } : row)))

  try {
    await api.customers.updateStatus({ id, status })
    await refetchCustomers()
  } catch {
    await refetchCustomers()
  }
}
```

<Callout title="Key takeaway">
  Good single-select cells stay visually small, keyboard-friendly, and honest about the underlying field they are editing.
</Callout>


# Add bulk actions (https://react-datatable.com/docs/guides/add-bulk-actions)

Use this guide when selected rows should trigger real work.

## Start from a clear selection model [#start-from-a-clear-selection-model]

Bulk actions should sit on top of a selection model users already understand.

Add them after you have:

* a table with `selection.enabled`
* clear distinction between selected rows, active row, and preview state
* at least one real multi-row task to support

If the product still cannot answer "what should happen after these rows are selected?", do not add a bulk action menu yet.

## Add the bulk actions config beside selection [#add-the-bulk-actions-config-beside-selection]

Bulk actions are enabled with the `bulkActions` prop.

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  selection={{
    enabled: true,
    allowSelectAllMatching: true,
  }}
  bulkActions={{
    triggerLabel: "Actions",
    actions,
    serverExecutor: async (request) => {
      await fetch("/api/customers/bulk", {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify(request),
      })
    },
  }}
/>
```

The action island only appears when there is at least one selected row.

> \[!NOTE]
> Screenshot placeholder: bulk action island visible above the table with selected rows, a clear selected count, and action wording that makes scope obvious.

## Action labels [#action-labels]

Users should be able to predict the outcome from the action title alone.

Good labels include:

* `Archive selected rows`
* `Assign selected customers`
* `Export all matching accounts`

Avoid vague labels like `Run`, `Apply`, or `Continue`.

That matters even more when selection might represent the whole filtered result instead of only visible rows.

## Use client actions for lightweight local work [#use-client-actions-for-lightweight-local-work]

Client actions are a good fit when the selected rows already exist in memory, the action only needs the loaded row data, and the work stays inside the current session.

```tsx
const actions = [
  {
    id: "copy-emails",
    title: "Copy emails",
    onSelect: async ({ selectedRows, selectedCount, clearSelection, closeDialog }) => {
      await navigator.clipboard.writeText(selectedRows.map((row) => row.email).join("\n"))
      toast.success(`Copied ${selectedCount} email${selectedCount === 1 ? "" : "s"}.`)
      clearSelection()
      closeDialog()
    },
  },
]
```

Use this path for things like:

* copying data to the clipboard
* opening a local confirm step
* updating app state that does not require a backend round trip

If the action mutates protected data, sends notifications, exports large datasets, or needs audit logs, move it to the server path instead.

## Use server actions when the backend owns the outcome [#use-server-actions-when-the-backend-owns-the-outcome]

Server actions are the safer default for durable work.

```tsx
const actions = [
  {
    id: "export",
    title: "Export customers CSV",
    execution: "server",
    serverActionId: "export-customers-csv",
    buildServerPayload: ({ selectedCount }) => ({
      requestedCount: selectedCount,
      requestedBy: currentUser.id,
    }),
  },
]
```

The table passes a `DataTableBulkServerActionRequest` to `serverExecutor`.

```ts
type DataTableBulkServerActionRequest = {
  actionId: string
  selection: DataTableSelectionDescriptor
  payload?: unknown
}
```

That request shape is what lets your backend distinguish explicit row IDs from an all-matching selection built from the current query.

## Add confirmation steps for destructive or expensive actions [#add-confirmation-steps-for-destructive-or-expensive-actions]

If an action deletes, archives, reassigns, bills, or launches a long-running job, give users a deliberate confirm step.

```tsx
{
  id: "archive",
  title: "Archive customers",
  getInitialStep: () => ({
    kind: "confirm",
    title: "Archive selected customers?",
    description: "Archived customers leave the active workspace view.",
    confirmLabel: "Archive",
    onConfirm: async ({ selectedRows, clearSelection, closeDialog }) => {
      await archiveCustomers(selectedRows)
      clearSelection()
      closeDialog()
    },
  }),
}
```

A strong confirmation step restates:

* what action will happen
* how many rows are affected
* whether the scope is selected rows or all matching rows
* any permission or irreversibility warning

> \[!NOTE]
> Screenshot placeholder: destructive bulk-action confirm dialog showing exact row count, action wording, and a clear warning about irreversible scope.

## Make all-matching scope explicit [#make-all-matching-scope-explicit]

When `allowSelectAllMatching` is enabled, the selected set may include rows that are not currently loaded in the browser.

That means your action labels, confirm step, and backend contract all need to say what will actually happen.

```ts
type DataTableSelectionDescriptor =
  | {
      kind: "explicit"
      ids: string[]
    }
  | {
      kind: "allMatching"
      query: OnlineQueryStateInput
      includedIds: string[]
      excludedIds: string[]
      totalMatchingRows: number
    }
```

For `allMatching`, the backend should recompute the target rows from the query and then apply any exclusions.

```ts
export async function runBulkAction(request: DataTableBulkServerActionRequest) {
  const targetIds =
    request.selection.kind === "explicit"
      ? request.selection.ids
      : await resolveMatchingIds(db, request.selection.query, request.selection.excludedIds)

  if (request.actionId === "customers.archive") {
    await db.update(customers).set({ archivedAt: new Date() }).where(inArray(customers.id, targetIds))
  }
}
```

Do not assume the browser will send every matching row ID for large online tables.

## Nested steps [#nested-steps]

Bulk actions can open an `items`, `confirm`, or `custom` step.

That is useful when one entry point should fan out into several related operations.

```tsx
const actions = [
  {
    id: "assign",
    title: "Assign…",
    getInitialStep: () => ({
      kind: "items",
      title: "Assign selected accounts",
      searchPlaceholder: "Find owner…",
      items: owners.map((owner) => ({
        id: owner.id,
        title: owner.name,
        execution: "server",
        serverActionId: "accounts.assign-owner",
        buildServerPayload: () => ({ ownerId: owner.id }),
      })),
    }),
  },
  {
    id: "archive",
    title: "Archive…",
    getInitialStep: () => ({
      kind: "confirm",
      title: "Archive selected accounts?",
      description: "Archived accounts leave the active pipeline.",
      confirmLabel: "Archive",
      execution: "server",
      serverActionId: "accounts.archive",
      buildServerPayload: () => ({ archiveReason: "user_requested" }),
      onConfirm: async () => {},
    }),
  },
  {
    id: "export",
    title: "Export…",
    getInitialStep: () => ({
      kind: "custom",
      title: "Choose export format",
      render: ({ executeServerAction, closeDialog }) => (
        <div className="space-y-2">
          <button onClick={async () => {
            await executeServerAction({ actionId: "accounts.export", payload: { format: "csv" } })
            closeDialog()
          }}>Export CSV</button>
          <button onClick={async () => {
            await executeServerAction({ actionId: "accounts.export", payload: { format: "xlsx" } })
            closeDialog()
          }}>Export XLSX</button>
        </div>
      ),
    }),
  },
]
```

Use:

* `items` for a short searchable list of choices
* `confirm` for one deliberate yes/no step
* `custom` when you need a tiny piece of app-owned UI such as format buttons or a date picker

Keep the step flow short. If the action becomes a full workflow with complex validation, it probably belongs in app-owned UI instead.

> \[!NOTE]
> Screenshot placeholder: bulk-action menu branching into a short secondary choice list such as “Assign…” or “Move to status…”, showing auxiliary step UI beyond the first action island.

## Clear selection after completion [#clear-selection-after-completion]

The built-in dialog clears selection and closes automatically after successful server execution.

For client actions, you control that behavior yourself with `clearSelection()` and `closeDialog()`.

Clear selection when completion means the working set is done.

Keep selection intact when users are likely to retry, compare outcomes, or run a second action immediately after an error.

## Errors and auditability [#errors-and-auditability]

For server-backed actions, your app should own:

* permission checks
* retry behavior
* long-running job status
* audit logs
* success and failure messaging near the table or in surrounding product UI

The table gives you the selection contract and command surface. Your app still owns operational safety.

## Verify bulk actions before you move on [#verify-bulk-actions-before-you-move-on]

Before you continue, confirm that:

* each action corresponds to a real multi-row task
* labels and confirmation text make scope obvious
* destructive or expensive actions require deliberate confirmation
* client actions only handle work that is safe to do locally
* server actions receive enough payload to audit the request
* all-matching selections are resolved server-side from query plus exclusions
* success and error behavior leave users confident about what happened

<Callout title="Next">
  See [Server query endpoint](/docs/guides/server-query-endpoint) for the HTTP contract used by server-backed bulk actions alongside online table requests. If selection still needs work, go back to [Add row selection](/docs/guides/add-row-selection).
</Callout>


# Add column filters (https://react-datatable.com/docs/guides/add-column-filters)

Use this guide when users need more precision than one global search box can provide.

The goal is to make the right columns filterable, pick filter types that match the data, and keep the built-in filter UI predictable for both users and app developers.

The filter UI can look similar in local and online mode. The important difference is where the filter payloads are actually applied.

<ImageZoom src="/docs-media/guides/add-column-filters-toolbar-status-filter-placeholder.png" alt="A dark data table with search and filter chips visible, plus an open status filter menu showing searchable options and an active At risk selection." className="my-7 w-full rounded-xs border-0" />

## Start with the columns users actually filter by [#start-with-the-columns-users-actually-filter-by]

Column filters work best for fields that answer a clear question:

* status
* owner
* priority
* plan
* renewal date
* seat count or revenue band

Do not add filters to every column by default. A table with too many low-value filters becomes harder to scan and harder to trust.

## Mark each filterable column with a `filterType` [#mark-each-filterable-column-with-a-filtertype]

A column needs a `filterType` before it can participate in the built-in filter UI.

```tsx
const columns: DatatableColumn<Customer>[] = [
  {
    id: "company",
    accessorKey: "company",
    header: "Company",
    filterType: "text",
  },
  {
    id: "status",
    accessorKey: "status",
    header: "Status",
    filterType: "text-list",
    filterOptions: {
      options: [
        { value: "active", label: "Active" },
        { value: "trial", label: "Trial" },
        { value: "paused", label: "Paused" },
      ],
    },
  },
  {
    id: "renewalDate",
    accessorKey: "renewalDate",
    header: "Renewal",
    filterType: "date",
  },
]
```

If a column should never be filterable, omit `filterType` or set `enableFiltering: false`.

## Turn on the toolbar filter entry point [#turn-on-the-toolbar-filter-entry-point]

Enable the filter button so users can open the built-in filter picker.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  toolbar={{
    filterButton: true,
    appliedState: {
      showFilters: true,
    },
  }}
/>
```

The current toolbar shows active filter chips when `appliedState.showFilters` is enabled.

<ImageZoom src="/docs-media/guides/add-column-filters/add-column-filters-toolbar-picker-and-chips.png" alt="The column filter picker opened from the toolbar with a realistic field selection flow and applied filter chips visible." className="my-7 w-full rounded-xs border-0" />

## Pick the right filter type for each field [#pick-the-right-filter-type-for-each-field]

Use the built-in filter types according to the kind of question users ask.

### Use `text` for open-ended string matching [#use-text-for-open-ended-string-matching]

Choose `text` when users search a field by partial or exact text.

```tsx
{
  id: "company",
  accessorKey: "company",
  header: "Company",
  filterType: "text",
}
```

The current docs and source support text-filter modes such as contains, equals, starts with, ends with, and excludes.

<ImageZoom src="/docs-media/guides/add-column-filters/add-column-filters-text-filter.png" alt="The text filter editor open on a Company field with operator choices like contains, equals, starts with, ends with, and excludes." className="my-7 w-full rounded-xs border-0" />

### Use `text-list` for finite labels [#use-text-list-for-finite-labels]

Choose `text-list` when the field has a bounded set of meaningful values.

```tsx
{
  id: "status",
  accessorKey: "status",
  header: "Status",
  filterType: "text-list",
  filterOptions: {
    options: [
      { value: "active", label: "Active" },
      { value: "trial", label: "Trial" },
      { value: "paused", label: "Paused" },
    ],
  },
}
```

This is usually the best choice for status, priority, plan, stage, or other user-facing facets.

<ImageZoom src="/docs-media/guides/add-column-filters/add-column-filters-text-list-filter.png" alt="A text-list filter editor on a Plan field with inclusion and exclusion options and multiple selected values applied." className="my-7 w-full rounded-xs border-0" />

You can also customize how option-list filters render without changing the filter payload. This is useful when an option needs a visual cue, such as an owner avatar, status dot, or boolean badge.

```tsx
{
  id: "owner",
  header: "Owner",
  accessorFn: (row) => row.owner.name,
  filterType: "text-list",
  filterOptions: {
    options: owners.map((owner) => ({ value: owner.name, label: owner.name })),
    renderOption: (option) => {
      const owner = owners.find((item) => item.name === option.value)

      return (
        <>
          {owner ? <OwnerAvatar owner={owner} /> : null}
          <span className="truncate">{option.label}</span>
        </>
      )
    },
  },
}
```

`renderOption` is presentation-only. The active filter still stores and applies the selected `value`.

### Use `number` for measurable values [#use-number-for-measurable-values]

Choose `number` for counts, prices, scores, durations, or quantities.

```tsx
{
  id: "seats",
  accessorKey: "seats",
  header: "Seats",
  filterType: "number",
}
```

<ImageZoom src="/docs-media/guides/add-column-filters/add-column-filters-number-filter.png" alt="A number filter editor on a Seats field with comparison operators like equals, greater than, greater than or equal, less than, and less than or equal." className="my-7 w-full rounded-xs border-0" />

### Use `date` for date-oriented questions [#use-date-for-date-oriented-questions]

Choose `date` when users think in before/after/range language.

```tsx
{
  id: "renewalDate",
  accessorKey: "renewalDate",
  header: "Renewal",
  filterType: "date",
}
```

Normalize date values before they reach the table so the UI and backend agree on what each filter means.

### Use `boolean` for yes/no fields [#use-boolean-for-yesno-fields]

Choose `boolean` when the column answers a binary question such as active vs inactive, paid vs unpaid, or internal vs external.

```tsx
{
  id: "isActive",
  accessorKey: "isActive",
  header: "Active",
  filterType: "boolean",
}
```

By default the built-in editor shows `True` and `False`. You can override those labels with `filterOptions.options`.

```tsx
{
  id: "isInternal",
  accessorKey: "isInternal",
  header: "Audience",
  filterType: "boolean",
  filterOptions: {
    options: [
      { value: true, label: "Internal" },
      { value: false, label: "External" },
    ],
    renderOption: (option) => (
      <>
        <span aria-hidden="true" className={option.value ? "bg-green-500 size-2 rounded-full" : "bg-gray-400 size-2 rounded-full"} />
        <span>{option.label}</span>
      </>
    ),
  },
}
```

### Use `id-list` for related entities [#use-id-list-for-related-entities]

Choose `id-list` when rows point at related records such as assignees, accounts, projects, or workspaces.

```tsx
const assigneeOptions = useMemo(
  () =>
    users.map((user) => ({
      value: user.id,
      label: user.name,
    })),
  [users]
)

{
  id: "assigneeIds",
  accessorKey: "assigneeIds",
  header: "Assignee",
  filterType: "id-list",
  filterOptions: {
    options: assigneeOptions,
    isLoading: usersQuery.isLoading,
    emptyText: "No assignees available",
    renderOption: (option) => {
      const user = users.find((item) => item.id === option.value)

      return (
        <>
          {user ? <UserAvatar user={user} /> : null}
          <span>{option.label}</span>
        </>
      )
    },
  },
}
```

Keep option loading in your app, not inside the table primitive. A common pattern is:

1. fetch related entities with your own query layer
2. map them to `{ value, label }[]`
3. pass the resolved options and loading state into `filterOptions`

That keeps fetching, caching, and invalidation under your control.

`renderOption` is supported by `text-list`, `id-list`, and `boolean` because all three use the shared option-list editor. It is not used by freeform `text`, numeric, or date filters.

<ImageZoom src="/docs-media/guides/add-column-filters/add-column-filters-id-list-filter.png" alt="An id-list filter editor on a Responsible field with multiple selected people and inclusion or exclusion operator choices." className="my-7 w-full rounded-xs border-0" />

## Know what the built-in filter UI can do [#know-what-the-built-in-filter-ui-can-do]

These filter types are available in the built-in picker and chip UI:

* `text`
* `text-list`
* `number`
* `date`
* `boolean`
* `id-list`

`custom` is still an extension point. It gives you a typed place to store filter payloads, but you supply your own editor, chip presentation, and query behavior.

The built-in picker behaves differently depending on filter type:

* `text` and `number` open through the editor modal flow
* `text-list` and `date` use inline submenu-style editors from the filter picker
* `boolean` and `id-list` use the same built-in option-list editing pattern, with chips that reopen the selector for quick edits
* only implemented, enabled filter types appear in the filter list

In practice there are two families of built-in filters:

* **freeform filters**: `text`, `number`, `date`
* **list-shaped filters**: `text-list`, `boolean`, `id-list`

That split is useful when you design columns. If the user is choosing from named options, a list-shaped filter usually produces the cleanest UI.

## Show active filters in the UI [#show-active-filters-in-the-ui]

If users can filter the table, they should be able to see and remove active filters easily.

```tsx
toolbar={{
  filterButton: true,
  appliedState: {
    showFilters: true,
    showSorting: true,
  },
}}
```

The applied-state bar renders filter chips below the toolbar and lets users remove individual filters without reopening the picker.

## Use `AND` and `OR` intentionally [#use-and-and-or-intentionally]

The table supports a cross-column filter mode.

* `AND` means a row must satisfy every active column filter
* `OR` means a row can satisfy any active column filter

The toolbar shows the toggle when users have multiple column filters, or when they combine global search with at least one column filter.

Use `AND` for narrow operational queries. Use `OR` for exploratory scanning across several related signals.

## In local mode, filters run against loaded rows [#in-local-mode-filters-run-against-loaded-rows]

In local mode, filters run against the rows already loaded in memory.

That works well when:

* the dataset is bounded
* browser-side filtering is acceptable
* backend-authoritative totals or facets are not required

`text-list` and `id-list` both support scalar cells and array-valued cells:

* if the cell holds one value, the filter compares that value directly
* if the cell holds an array, the filter matches when any selected value overlaps the row values

That makes them a good fit for tags, many-to-many relationships, and multi-assignee style columns.

## In online mode, your backend applies the filter payloads [#in-online-mode-your-backend-applies-the-filter-payloads]

In online mode, the table sends filter payloads to your query function and your backend becomes responsible for the filtered result.

```ts
async function fetchCustomers(input: OnlineQueryInput): Promise<OnlineQueryResponse<Customer>> {
  let query = db.select().from(customers)

  for (const filter of input.filters) {
    if (filter.id === "status" && filter.type === "text-list") {
      query = query.where(inArray(customers.status, filter.payload.values))
    }

    if (filter.id === "company" && filter.type === "text") {
      for (const condition of filter.payload.conditions) {
        if (condition.mode === "contains") {
          query = query.where(ilike(customers.company, `%${condition.value}%`))
        }
      }
    }

    if (filter.id === "arr" && filter.type === "number") {
      for (const condition of filter.payload.conditions) {
        if (condition.mode === "gte") {
          query = query.where(gte(customers.arr, condition.value))
        }

        if (condition.mode === "lte") {
          query = query.where(lte(customers.arr, condition.value))
        }
      }
    }

    if (filter.id === "isActive" && filter.type === "boolean") {
      query = query.where(eq(customers.isActive, filter.payload.value))
    }

    if (filter.id === "assigneeIds" && filter.type === "id-list") {
      query = query.where(inArray(customerAssignees.assigneeId, filter.payload.ids))
    }
  }

  return runQuery(query, input)
}
```

If you offer list-shaped filters in online mode, keep the option source authoritative too. That usually means your app fetches the option list from the same backend or domain source that defines the data.

## Disable low-value filters explicitly [#disable-low-value-filters-explicitly]

If a column has a `filterType` in a shared definition but should not be filterable in one table, disable it at the column level.

```tsx
{
  id: "rawPayload",
  accessorKey: "rawPayload",
  header: "Payload",
  filterType: "text",
  enableFiltering: false,
}
```

This keeps the filter picker focused on user-facing fields.

## Verify column filters before you move on [#verify-column-filters-before-you-move-on]

Before you continue, confirm that:

* each filterable column answers a real user question
* list-shaped filters use stable values and clear labels
* `id-list` option loading and caching stay in your app layer
* only built-in filter types are presented as turnkey UI
* applied filter chips are visible when users need them
* `AND` versus `OR` behavior matches the intended workflow
* online queries apply `input.filters` and return consistent facets when needed

<Callout title="Next">
  Add [global search](/docs/guides/add-global-search) for broad matching across fields. If filtering belongs on the server, check [Choose a data mode](/docs/guides/choose-a-data-mode) first.
</Callout>


# Add column ordering (https://react-datatable.com/docs/guides/add-column-ordering)

Use this guide when users need to reshape the table around their workflow without changing the underlying column definitions.

The goal is to expose drag behavior where it helps, keep sticky-column rules understandable, and make reordered layouts persist instead of snapping back on the next visit.

<ImageZoom src="/docs-media/guides/add-column-ordering-placeholder.png" alt="A dark data table with filters and toolbar controls visible, showing a dragged Responsible column header being repositioned across the grid." className="my-7 w-full rounded-xs border-0" />

## Start with stable column IDs and a sensible default order [#start-with-stable-column-ids-and-a-sensible-default-order]

Column ordering depends on durable column IDs.

Before you expose drag-and-drop, make sure:

* every user-visible column has a stable `id`
* the initial `columns` array already reflects a sensible default order
* identity columns stay near the left edge unless users have a strong reason to move them

Column ordering works best when users are refining a good default, not rescuing a bad one.

## Enable column reordering explicitly [#enable-column-reordering-explicitly]

Use the `columnReordering` prop to opt into drag behavior.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  columnReordering={{
    allowFrozenBoundaryCrossing: false,
    widthMorph: "interpolate",
  }}
/>
```

This enables header drag reordering for visible columns while keeping the rest of the table contract unchanged.

> \[!NOTE]
> Screenshot placeholder: column reorder via drag-and-drop plus column visibility and ordering controls in one realistic product table.

## Decide whether frozen columns form a fixed left-side zone [#decide-whether-frozen-columns-form-a-fixed-left-side-zone]

`allowFrozenBoundaryCrossing` controls whether dragged columns can cross the sticky/non-sticky boundary.

* `false`: frozen columns stay in the frozen zone and non-frozen columns stay in the scrollable zone
* `true`: users can drag visible columns across that seam

Use `false` when frozen columns represent a product-level identity area, such as:

* company or customer name
* issue title
* selection checkboxes
* row actions

Use `true` only when users genuinely expect full freedom over the left edge of the table.

The current drag controller actively clamps drop targets to the allowed side when boundary crossing is disabled, so this is a real interaction rule, not only a recommendation.

## Pick the width-morph behavior intentionally [#pick-the-width-morph-behavior-intentionally]

`widthMorph` controls how the dragged header overlay reacts when it moves over columns with different widths.

* `"none"`: keep the original width while dragging
* `"snap"`: jump to the target width
* `"interpolate"`: animate between source and target widths

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  columnReordering={{
    widthMorph: "snap",
  }}
/>
```

If you want the drag preview to feel more polished, set this explicitly. The copied source currently falls back to `"none"` in the grid controller unless you provide a value.

## Keep column ordering aligned with visibility controls [#keep-column-ordering-aligned-with-visibility-controls]

Column ordering only affects visible columns during drag.

That matters in two places:

* header drag reorders the visible grid columns
* badge-based column visibility management can also reorder visible versus hidden columns inside display options

Because hidden columns keep their relative positions in the stored order, users get more predictable results when you treat visibility and ordering as one layout story.

A good pattern is:

* use display options for visibility changes
* use header drag for fast spatial rearrangement
* persist both together as part of the current view

## Keep sticky columns conservative [#keep-sticky-columns-conservative]

Frozen columns are useful, but too many make drag behavior harder to understand and reduce horizontal space.

The current source caps sticky columns to preserve layout quality, so treat the left frozen zone as a small identity area rather than a second full table.

That usually means freezing only the columns users need for context while scanning wide datasets.

## Persist reordered layouts [#persist-reordered-layouts]

Column ordering becomes much more useful when it survives refreshes, navigation, and shared working modes.

Pair reordering with:

* current-view persistence for per-user defaults
* saved views when teams need named layouts
* URL sync only when layout state should travel in a shared link

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  persistState={{
    adapter: localStorageAdapter,
  }}
  columnReordering={{
    allowFrozenBoundaryCrossing: false,
    widthMorph: "interpolate",
  }}
/>
```

Without persistence, column drag often feels like a temporary toy instead of a serious workflow tool.

## Reset order through state, not ad hoc DOM tricks [#reset-order-through-state-not-ad-hoc-dom-tricks]

To restore the default layout, reset the stored table state or load a saved/default view with the desired `columnOrder`.

Avoid trying to patch the visual order outside the datatable state model. Ordering, visibility, sticky columns, and widths already interact inside the shared state surface.

## Verify column ordering before you move on [#verify-column-ordering-before-you-move-on]

Before you continue, confirm that:

* visible columns drag into the expected positions
* frozen-column boundaries behave the way your product intends
* the chosen `widthMorph` feels right for mixed column widths
* visibility changes and ordering changes stay coherent together
* reordered layouts survive through persistence or saved views when they should


# Add copy links (https://react-datatable.com/docs/guides/add-copy-links)

Use copy links when people occasionally need to share the current search, filters, sorting, or grouping state.

This feature creates deliberate, on-demand sharing links for the current table state.

<ImageZoom src="/docs-media/guides/add-copy-links-placeholder.png" alt="A dark data table toolbar showing a copy-link button next to display controls and a saved view, ready to share the current table state." className="my-7 w-full rounded-xs border-0" />

## Copy links vs saved views vs URL sync [#copy-links-vs-saved-views-vs-url-sync]

The simple version:

* **Copy links** load the table from URL params when someone opens the link you copied.
* **URL sync** keeps writing table state back into the URL while the user works.
* **Saved views** store a named preset instead of relying on a long URL.

Use copy links when users need to:

* paste the current table state into chat or a ticket
* hand someone a one-off filtered view
* share the current state without filling browser history with every change

Use saved views instead when the shared state should become a durable named preset.

Use continuous URL sync only when the URL itself is part of the product surface and should keep changing as the table changes.

## Turn on the toolbar control [#turn-on-the-toolbar-control]

Copy links are exposed through the toolbar.

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  toolbar={{
    quickSearch: true,
    filterButton: true,
    copyLink: true,
  }}
/>
```

The built-in `CopyLinkButton` always serializes the current shareable table state when the user clicks it.

> \[!NOTE]
> Screenshot placeholder: toolbar with the copy-link button visible next to search and filters, plus a realistic filtered table state that is worth sharing.

## What the copied link includes [#what-the-copied-link-includes]

Copy link uses the same URL-state serialization layer as URL sync.

That means the copied URL can include:

* global search (`q`)
* column filters (`f.columnId`)
* sorting (`s`)
* filter mode (`fm`)
* grouping (`g`)

It serializes shareable query state instead of personal layout preferences like column widths, sticky columns, visibility, or the active saved view ID.

## Use copy links without live URL sync [#use-copy-links-without-live-url-sync]

The copy-link button calls `serializeToFullUrl()` directly from the current store state.

That means users can copy a valid shareable link even when `urlSync.enabled` is false.

For many product tables, that is the right default:

* `persistState` remembers one person's working setup automatically
* `copyLink` shares the current query state on demand
* the address bar stays stable during normal interaction

## Accept URL params on load [#accept-url-params-on-load]

A copied link only helps if the destination table accepts URL params on load.

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  urlSync={{
    enabled: false,
    acceptUrlParams: true,
  }}
  toolbar={{ copyLink: true }}
/>
```

With `enabled: false` and `acceptUrlParams: true`, the table reads the shared state once and then clears those datatable params from the URL.

That is a good fit when links should open a shared state snapshot but the page should not keep rewriting the address bar afterward.

> \[!NOTE]
> Screenshot placeholder: a before-and-after share flow showing a copied filtered URL opening the same table state for a recipient while the address bar stays clean after initialization.

## Persistence and defaults [#persistence-and-defaults]

URL state still has the highest initialization priority.

That means a copied link can override:

* `initialState`
* workspace default views
* user default views
* remembered current-view persistence

That is what makes a copied link trustworthy: the recipient sees the shared query state first, even if they normally have their own defaults.

## Long links [#long-links]

Copied links store table state directly in the URL. Use saved views when the table state is too large for a practical link, especially when users stack many filters or complex filter payloads.

## Verify the share flow [#verify-the-share-flow]

Before you ship copy links, confirm that:

* the toolbar button is visible where users expect it
* the table accepts URL params on load when a copied link is opened
* copied state overrides remembered state during initialization
* the page behaves correctly after load when continuous URL sync is disabled
* long or complex states fall back to a saved-view workflow in product guidance

## Keep the product language clear [#keep-the-product-language-clear]

Readers should understand the difference between these three tools:

* **Current-view persistence** remembers my last state automatically
* **Saved views** create named reusable presets
* **Copy links** share the current query state right now

That distinction prevents teams from overloading one feature with another feature's job.

<Callout title="Next">
  Use [Add URL sync](/docs/guides/add-url-sync) when the address bar should stay in sync. Use [Add saved views](/docs/guides/add-saved-views) when shared state should become a named preset.
</Callout>


# Add current-view persistence (https://react-datatable.com/docs/guides/add-current-view-persistence)

Use this guide when a table should remember how one user last left it.

## When to persist the current view [#when-to-persist-the-current-view]

Current-view persistence is for per-user continuity.

Add it when users should be able to come back and find the table roughly where they left it, including things like:

* hidden or reordered columns
* sorting and grouping choices
* display settings
* current search and column filters
* the currently active saved view ID, when one was explicitly chosen

Do not use it for state that should stay temporary, collaborative, or route-specific.

## Add a persistence adapter and stable table key [#add-a-persistence-adapter-and-stable-table-key]

Current-view persistence is enabled with `persistState`.

```tsx
import { localStorageAdapter } from "./react-datatable/persistence"

<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  persistState={{
    adapter: localStorageAdapter,
    workspaceId: workspace.id,
    userId: currentUser.id,
  }}
/>
```

The adapter inherits the top-level `tableKey`, which is the main identity for the product surface.

Choose a stable key like `customers`, `workspace-members`, or `billing-invoices`.
Do not bake temporary route params into it.

> \[!NOTE]
> Screenshot placeholder: the same table before and after reload, showing remembered column layout, sorting, filters, and display settings restored for one user.

## Choose an adapter [#choose-an-adapter]

Use `localStorageAdapter` when one browser on one device is enough.

Use `sessionStorageAdapter` when the table should remember state only until the browser session ends.

Use a backend adapter when the same person should get the same table state across devices or browsers.

```tsx
persistState={{
  adapter,
  workspaceId: workspace.id,
  userId: currentUser.id,
  debounceMs: 1500,
}}
```

The built-in persistence hook auto-saves the extracted persisted state with a debounce, so backend adapters should be designed for repeated small writes.

## Add a backend adapter [#add-a-backend-adapter]

A backend adapter implements the `TableStateAdapter` contract: `get`, `set`, and `delete`.

```ts
import type {
  PersistedTableState,
  TableStateAdapter,
} from "../../../kit/src/react-datatable/persistence"

export const tableStateServerAdapter: TableStateAdapter = {
  async get({ tableKey, workspaceId, userId }) {
    const res = await fetch(`/api/datatable-state?tableKey=${tableKey}&workspaceId=${workspaceId}&userId=${userId}`)
    if (res.status === 404) return null
    if (!res.ok) throw new Error("Failed to load table state")
    return (await res.json()) as PersistedTableState
  },

  async set({ tableKey, workspaceId, userId }, state) {
    const res = await fetch("/api/datatable-state", {
      method: "PUT",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ tableKey, workspaceId, userId, state }),
    })
    if (!res.ok) throw new Error("Failed to save table state")
  },

  async delete({ tableKey, workspaceId, userId }) {
    const res = await fetch("/api/datatable-state", {
      method: "DELETE",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ tableKey, workspaceId, userId }),
    })
    if (!res.ok) throw new Error("Failed to reset table state")
  },
}
```

Use a server adapter when persistence should survive device changes or when support staff need to inspect and reset saved state centrally.

## What gets persisted [#what-gets-persisted]

The source of truth is `PersistedTableState`.

It includes durable working-state choices such as:

* column visibility, order, and widths
* sticky column count
* display settings like grid lines, column headers, and ordering badges
* sorting and grouping
* global search, column filters, and filter mode
* `activeViewId` when the user explicitly selected a saved view

```ts
type PersistedTableState = {
  showColumnHeaders: boolean
  stickyColumnsCount: number
  showHorizontalLines: boolean
  showVerticalLines: boolean
  showEmptyGroups: boolean
  showOrderingBadge: boolean
  columnOrder: string[]
  columnVisibility: Record<string, boolean>
  columnWidths: Record<string, number>
  sorting: DatatableState["sorting"]
  grouping: string[]
  groupingOrder: Record<string, Record<string, number>>
  groupExpanded: DatatableState["groupExpanded"]
  globalFilter: string
  columnFilters: DatatableState["columnFilters"]
  filterMode: DatatableState["filterMode"]
  activeViewId?: string | null
}
```

## Keep transient state out [#keep-transient-state-out]

Do not treat everything in the table as a preference.

The table intentionally does not persist:

* row selection
* active-row keyboard focus
* preview open or closed state
* temporary popovers
* in-progress action flows

A user expects their preferred table shape to come back. They usually do not expect yesterday's half-finished bulk selection or open preview panel to return with it.

## Defaults, views, and URLs [#defaults-views-and-urls]

Persistence loads after higher-priority startup inputs.

The coordinator merges state in this order:

1. built-in defaults
2. `initialState`
3. workspace default view
4. user default view
5. persisted current view
6. URL state

That means persisted state beats default views, but URL state still wins when someone opens a shareable link.

That lets a table feel personal by default without breaking intentional sharing.

## Scope persistence correctly [#scope-persistence-correctly]

Use the adapter config to prevent unrelated tables from overwriting each other.

```tsx
persistState={{
  adapter,
  workspaceId: workspace.id,
  userId: currentUser.id,
}}
```

A good rule is:

* the top-level `tableKey` separates product surfaces
* `workspaceId` separates organizations or accounts
* `userId` separates personal preferences inside the same workspace

If one of those boundaries matters in your product, include it.

## Save timing and failures [#save-timing-and-failures]

Persistence writes happen after a debounce.

```tsx
persistState={{
  adapter,
  debounceMs: 2000,
  onSave: () => analytics.track("customers_table_persisted"),
  onError: (error) => reportError(error),
}}
```

Increase `debounceMs` when writes go over the network or when users make many rapid layout adjustments.

Always decide where save failures should surface. Silent failure makes the table feel unreliable.

## Add a reset path [#add-a-reset-path]

If a remembered table state can become confusing, expose a reset action.

```tsx
await adapter.delete({
  tableKey: "customers",
  workspaceId,
  userId,
})
```

That is especially useful for support workflows, debugging, and major table migrations.

> \[!NOTE]
> Screenshot placeholder: a simple reset-table-state control in product UI, with the table returning from a customized remembered layout back to its default view.

## Verify current-view persistence before you move on [#verify-current-view-persistence-before-you-move-on]

Before you continue, confirm that:

* the table has a stable `tableKey`
* persistence scope matches the product boundaries that matter
* only durable preferences are saved
* transient interaction state stays transient
* debounce timing fits the adapter cost
* failures are observable somewhere useful
* URL-based sharing still overrides remembered state when that is intentional

<Callout title="Next">
  Use [Server persisted state endpoint](/docs/guides/server-persisted-state-endpoint) when state must sync across devices. Use [Add saved views](/docs/guides/add-saved-views) for named presets, or [Add URL sync](/docs/guides/add-url-sync) for continuously shareable state.
</Callout>


# Add global search (https://react-datatable.com/docs/guides/add-global-search)

Use this guide when users need one fast search box before they reach for column-specific filters.

The goal is to turn on quick search, keep the matching surface relevant, and make sure search runs in the right place for the data mode you already chose.

The search box can look similar in local and online mode. The important difference is where matching actually happens.

<ImageZoom src="/docs-media/guides/add-global-search-toolbar-quick-search.png" alt="A realistic table toolbar with the quick search input active next to the filter button." className="my-7 w-full rounded-xs border-0" />

## Turn on the search box [#turn-on-the-search-box]

Turn on the built-in search box from `toolbar.quickSearch`.

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  data={customers}
  getRowId={(row) => row.id}
  toolbar={{
    quickSearch: {
      placeholder: "Search customers...",
      debounceMs: 300,
    },
  }}
/>
```

The toolbar renders the search input on the left side of the table UI and keeps the current search term in datatable state.

## Choose the fields users actually think in [#choose-the-fields-users-actually-think-in]

Global search works best when it matches the fields users expect to search quickly:

* company, person, issue, or project names
* obvious IDs or short codes
* status-like labels when users commonly search by them

It works poorly when every technical or noisy field is searchable by default.

## Exclude noisy columns [#exclude-noisy-columns]

The current source honors column-level `enableGlobalFilter`, so disable global search on fields that should not match the quick search box.

```tsx
export const customerColumns: DatatableColumn<Customer>[] = [
  {
    id: "company",
    accessorKey: "company",
    header: "Company",
    filterType: "text",
  },
  {
    id: "internalNotes",
    accessorKey: "internalNotes",
    header: "Notes",
    enableGlobalFilter: false,
    enableSorting: false,
  },
]
```

This is the safest way to keep quick search focused without changing how column filters work.

## Use the placeholder to set expectations [#use-the-placeholder-to-set-expectations]

If users are unsure what the box searches, make the placeholder explicit.

```tsx
toolbar={{
  quickSearch: {
    placeholder: "Search company, owner, or status...",
  },
}}
```

A good placeholder reduces ambiguity without adding extra explanatory UI.

> \[!NOTE]
> Screenshot placeholder: search box with explicit placeholder text like “Search company, owner, or status...” visible over a realistic table so the expectation-setting language is easy to judge.

## Change debounce only if you need to [#change-debounce-only-if-you-need-to]

`debounceMs` controls how long the input waits before updating table state.

```tsx
toolbar={{
  quickSearch: {
    placeholder: "Search customers...",
    debounceMs: 200,
  },
}}
```

Keep the default unless you have a reason to change it:

* lower values feel more immediate on small local tables
* slightly higher values can reduce server churn in online mode

Do not treat debounce as the main performance strategy. Pick the right data mode first.

## Search scope is controlled by columns and backend logic [#search-scope-is-controlled-by-columns-and-backend-logic]

There is no separate toolbar setting for narrowing quick-search matching.

Today, the real control points are:

* disable global search on noisy columns with `enableGlobalFilter: false`
* choose the right backend search fields in online mode
* use placeholder text to set user expectations

That is simpler and more honest than suggesting there is a second search-scope config in the toolbar.

## Keyboard shortcuts work out of the box [#keyboard-shortcuts-work-out-of-the-box]

The quick search input already supports a few useful shortcuts:

* `Cmd+F` or `Ctrl+F` focuses the table search input
* `Escape` clears the current value and blurs the input when it is focused

That makes quick search feel like a first-class table control instead of just another form field.

> \[!NOTE]
> Screenshot placeholder: quick search focused via keyboard shortcut, with the active input state and nearby filter controls visible to show the toolbar as a cohesive command surface.

## In local mode, search only sees loaded rows [#in-local-mode-search-only-sees-loaded-rows]

In local mode, the table checks the current search term against globally searchable columns in the loaded row set.

That means:

* search only sees rows already in memory
* disabling `enableGlobalFilter` on a column removes it from quick-search matching
* matching happens alongside the rest of the browser-side query pipeline

If users expect backend-authoritative search semantics, local mode is the wrong fit even if the UI looks convenient.

## In online mode, your backend owns search [#in-online-mode-your-backend-owns-search]

In online mode, the table sends the current search term to your query function as `input.globalFilter`.

```ts
async function fetchCustomers(input: OnlineQueryInput): Promise<OnlineQueryResponse<Customer>> {
  let query = db.select().from(customers)

  if (input.globalFilter.trim() !== "") {
    const term = `%${input.globalFilter.trim()}%`
    query = query.where(
      or(
        ilike(customers.company, term),
        ilike(customers.owner, term),
        ilike(customers.status, term)
      )
    )
  }

  return runQuery(query, input)
}
```

In this mode, your backend must decide:

* which fields are searchable
* how matching works
* whether search is case-insensitive, prefix-based, full-text, or fuzzy
* how totals, facets, and grouped output stay consistent with the filtered result

## Check the no-results message [#check-the-no-results-message]

After search is enabled, verify that the no-results state tells users what to do next.

Good empty-state text usually tells them to:

* clear search
* remove or loosen filters
* confirm they are in the right saved view or scope

## Verify the search behavior [#verify-the-search-behavior]

Before you continue, confirm that:

* the search box appears where users expect it in the toolbar
* the placeholder describes the intended search surface
* noisy columns are excluded with `enableGlobalFilter: false` where needed
* local mode only promises search over loaded rows
* online queries apply `input.globalFilter` consistently to rows, totals, and facets
* the no-results state is understandable when search returns nothing

<Callout title="Next">
  Add [column filters](/docs/guides/add-column-filters) for field-specific querying. If search belongs on the server, check [Choose a data mode](/docs/guides/choose-a-data-mode) first.
</Callout>


# Add grouping (https://react-datatable.com/docs/guides/add-grouping)

Use this guide when users need to scan the table by category, owner, status, date bucket, or another field that makes sections easier to reason about than one long list.

The grouping UI can look similar in both modes. The important difference is who is responsible for producing the grouped result.

<ImageZoom src="/docs-media/guides/add-grouping-placeholder.png" alt="A dark grouped data table with active filters and a display menu open, showing grouping controls set to Region and Plan." className="my-7 w-full rounded-xs border-0" />

## Choose grouping columns [#choose-grouping-columns]

Group by fields with a small, recognizable set of values, such as status, owner, priority, plan, project, or month/year date buckets.

Avoid high-cardinality fields such as freeform names, titles, IDs, or overly fine timestamps.

Those usually create too many small groups, especially on large datasets.

## Mark groupable columns in the column definition [#mark-groupable-columns-in-the-column-definition]

Columns are only useful for grouping when you declare that intent clearly.

```tsx
const columns: DatatableColumn<Issue>[] = [
  {
    id: "status",
    accessorKey: "status",
    header: "Status",
    enableGrouping: true,
  },
  {
    id: "owner",
    accessorKey: "owner",
    header: "Owner",
    enableGrouping: true,
  },
]
```

This gives the display-options grouping controls a real set of columns to offer.

> \[!NOTE]
> Screenshot placeholder: grouped table with group and subgroup headers visible in a realistic issue or customer table.

## Use grouping specs when raw values are not the grouping shape users need [#use-grouping-specs-when-raw-values-are-not-the-grouping-shape-users-need]

Some fields should not group directly by their raw stored value.

Use `groupingSpec` when you need a better grouping surface, such as:

* month or year buckets for timestamps
* revenue bands
* seat-count ranges
* normalized labels for raw enum values

```tsx
{
  id: "createdAt",
  accessorKey: "createdAt",
  header: "Created",
  enableGrouping: true,
  groupingSpec: {
    variants: {
      month: { kind: "date_trunc", granularity: "month" },
      year: { kind: "date_trunc", granularity: "year" },
    },
    defaultVariant: "month",
  },
}
```

That keeps the grouping UI aligned with how people actually talk about the data.

## Start with one grouping level, then add a subgroup only when it truly helps [#start-with-one-grouping-level-then-add-a-subgroup-only-when-it-truly-helps]

The current grouping UI supports:

* one primary grouping column
* one optional secondary grouping column
* swapping the two levels when both are active

That means two levels are possible, but you should still earn the second one.

A good pattern is:

* first group by the strongest top-level category
* add a subgroup only when it answers a second common question

Examples:

* status, then owner
* project, then priority
* month, then plan

If users are already struggling to scan the first grouping level, a subgroup will usually make the table harder, not clearer.

> \[!NOTE]
> Screenshot placeholder: two-level grouping example such as status then owner, with subgroup headers and row counts visible so the hierarchy feels tangible.

## Expose grouping from display options [#expose-grouping-from-display-options]

Grouping is currently managed from the display-options popover.

That is a good default because grouping belongs with other layout-shaping controls such as ordering, visibility, and display settings.

Keep the responsibility split clear:

* grouping chooses row sections
* filtering narrows the dataset
* sorting controls row order inside those groups

When those jobs stay separate, users can predict what each control will do.

## In local mode, the browser groups the loaded rows [#in-local-mode-the-browser-groups-the-loaded-rows]

In local mode, the browser can group the currently loaded rows using your column definitions and grouping specs.

This works well when:

* the dataset is already loaded
* group counts only need to reflect loaded rows
* client-side grouping performance is acceptable

## In online mode, your backend owns grouped row shaping [#in-online-mode-your-backend-owns-grouped-row-shaping]

In online mode, your backend must return rows in final render order, including group-header rows when grouping is active.

For the exact response shape, see [`OnlineQueryResponse`](/docs/reference/online-api#response-type) in the [Online API](/docs/reference/online-api) reference.

For a fuller backend walkthrough, see [Server query endpoint](/docs/guides/server-query-endpoint), [Server query planning](/docs/guides/server-query-planning), and [Server query execution](/docs/guides/server-query-execution).

```ts
async function query(input: OnlineQueryInput): Promise<OnlineQueryResponse<Issue>> {
  // input.grouping?.columns drives backend grouping
  // rows should include group-header and data entries in final order
}
```

You should also list which columns the backend can safely group.

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  getRowId={(row) => row.id}
  online={{
    mode: "pagination",
    queryKey: ["issues"],
    query,
    supportedGroupingColumns: ["status", "owner", "priority"],
  }}
/>
```

That prevents saved views or shared URLs from requesting unsupported grouping state.

## Decide whether empty groups belong in the product [#decide-whether-empty-groups-belong-in-the-product]

Grouping can optionally keep empty groups visible when that matters to the workflow.

This is most useful when users care about the full domain, not only matching rows. For example:

* all status lanes in an ops workflow
* all plan tiers in an account view
* all queue buckets in triage

If empty groups would mostly create blank noise, hide them.

> \[!NOTE]
> Screenshot placeholder: grouping controls in display options with `show empty groups` visible, paired with a table state where empty groups are either shown deliberately or hidden for comparison.

## Pair grouping with the right neighboring features [#pair-grouping-with-the-right-neighboring-features]

Grouping gets stronger when the surrounding features support it well:

* sorting for stable order inside each group
* display options for showing or hiding empty groups
* persistence or saved views so users keep their preferred breakdown
* virtualization tuning if grouped tables become tall and dense

Grouping gets weaker when users have to rebuild the same grouped layout every visit.

## Verify grouping before you move on [#verify-grouping-before-you-move-on]

Before you continue, confirm that:

* only genuinely useful columns are groupable
* grouping labels match how users describe the data
* a subgroup is only exposed when it improves scanning
* online tables return grouped rows through a documented backend contract
* unsupported grouping columns are filtered out in online mode
* empty-group behavior matches the product workflow


# Add keyboard navigation (https://react-datatable.com/docs/guides/add-keyboard-navigation)

Use this guide when users need to move through dense tables quickly without relying on the mouse.

## Row states [#row-states]

Keyboard navigation in react-datatable is built around an active row.

The active row is where keyboard movement currently is; selection is which rows are included in bulk actions.

<MediaPlaceholder title="Keyboard navigation states in a realistic table">
  Show one table state with an active row, selected rows, and an open preview so the differences are visible at a glance.
</MediaPlaceholder>

Use keyboard navigation when users need to:

* move row by row with `ArrowUp` and `ArrowDown`
* open the active row with `Enter`
* toggle preview with `Space`
* expand or collapse grouped headers from the keyboard

If the table only needs checkbox selection and occasional mouse clicks, you may not need this yet.

## Enable keyboard navigation explicitly [#enable-keyboard-navigation-explicitly]

Turn it on with the `keyboardNavigation` prop.

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  keyboardNavigation={{
    enabled: true,
    autoFocus: true,
  }}
/>
```

`autoFocus` defaults to `true` when keyboard navigation is active, so only disable it when another control should keep initial focus.

> \[!NOTE]
> Screenshot placeholder: active row, open-row action, and preview toggle visible in a realistic table with grouped and ungrouped states.

## Supported keyboard navigation [#supported-keyboard-navigation]

react-datatable already supports these keyboard behaviors:

* `ArrowUp` and `ArrowDown` move the active row
* `Enter` opens the active data row through `rowActions.onOpenRow`
* `Space` toggles preview when preview is configured
* `Enter` and `Space` toggle grouped headers when the active item is a group header
* `Esc` closes preview before clearing other interaction state

Use `rowActions.onOpenRow` for the main keyboard open behavior.

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  keyboardNavigation={{ enabled: true }}
  rowActions={{
    onOpenRow: ({ row, rowId, trigger }) => {
      openCustomer(rowId, { trigger })
    },
  }}
/>
```

When `Enter` fires on an active data row, the table calls `onOpenRow` with `trigger: "keyboard"`.

That makes it easy to share one row-opening path across mouse and keyboard flows while still preserving analytics or UI branching when needed.

## Wire Space to row preview when preview is available [#wire-space-to-row-preview-when-preview-is-available]

Use preview when users need quick inspection without fully opening the row.

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  keyboardNavigation={{ enabled: true }}
  rowActions={{
    onTogglePreviewRow: ({ rowId, nextOpen }) => {
      trackPreviewToggle(rowId, nextOpen)
    },
  }}
  preview={{
    floating: {
      draggable: true,
      storageKey: "customers-preview",
    },
    renderPreview: ({ row, close }) => <CustomerPreview customer={row} onClose={close} />,
  }}
/>
```

When preview is configured:

* `Space` toggles preview for the active data row
* `Esc` closes the preview first
* the row action callback can observe whether the preview is opening or closing

The grid also enables keyboard navigation by default when preview rendering or `onOpenRow` is present, but it is still better to configure the behavior intentionally.

> \[!NOTE]
> Screenshot placeholder: active row with keyboard focus ring plus an open preview panel, showing the keyboard-driven inspection loop rather than only the resting table state.

## Grouped rows change Enter and Space behavior [#grouped-rows-change-enter-and-space-behavior]

Grouped headers are keyboard-active items too.

When the active item is a group header instead of a data row:

* `Enter` toggles group expansion
* `Space` also toggles group expansion

That means grouped tables need a clear mental model:

* data rows open or preview
* group headers expand or collapse

If you mix grouping and keyboard navigation, test both grouped and ungrouped states instead of assuming row behavior carries over unchanged.

## Be deliberate about focus ownership [#be-deliberate-about-focus-ownership]

The grid can claim focus on mount when keyboard navigation is enabled.

Keep `autoFocus` enabled when the table is the main work surface.

Disable it when:

* the page opens into a search field or form
* the table appears below a required input
* automatic grid focus would interrupt a setup flow

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  keyboardNavigation={{
    enabled: true,
    autoFocus: false,
  }}
/>
```

A table that steals focus at the wrong moment feels broken even when the keyboard logic itself is correct.

> \[!NOTE]
> Screenshot placeholder: a page layout where the table is below another input, illustrating when `autoFocus: false` protects the surrounding setup flow.

## Verify keyboard navigation before you move on [#verify-keyboard-navigation-before-you-move-on]

Before you continue, confirm that:

* `ArrowUp` and `ArrowDown` move the active row predictably
* `Enter` opens active data rows through `rowActions.onOpenRow`
* `Space` toggles preview when preview is configured
* group headers expand and collapse from the keyboard
* `Esc` closes preview before clearing other interaction state
* active-row styling is visually distinct from checkbox selection
* grid autofocus helps more than it hurts in the surrounding screen


# Add row preview (https://react-datatable.com/docs/guides/add-row-preview)

Use this guide when users need to inspect row details without leaving the table.

## What row preview is [#what-row-preview-is]

Row preview opens a lightweight detail panel while the user stays in the table.

It works well for quick inspection, comparison, and scanning supporting context before deciding whether to open the full record.

Use `rowActions.onOpenRow` instead when the next step should leave the table, enter an edit flow, or route to a dedicated detail page.

<MediaPlaceholder title="Floating row preview beside a realistic table">
  Show a table with one row active and its preview panel open beside the grid so the in-context inspection model is obvious.
</MediaPlaceholder>

## Add a preview renderer [#add-a-preview-renderer]

Preview is available when you provide `preview.renderPreview`.

`renderPreview` can return any React component you want.

```tsx
function CustomerPreview({ customer, onClose }: { customer: Customer; onClose: () => void }) {
  return (
    <div>
      <h3>{customer.name}</h3>
      <p>{customer.email}</p>
      <button onClick={onClose}>Close</button>
    </div>
  )
}

<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  preview={{
    renderPreview: ({ row, close }) => (
      <CustomerPreview customer={row} onClose={close} />
    ),
  }}
/>
```

The renderer receives `row`, `rowId`, and `close()`.

Keep the preview focused on inspection. If it starts to need routing, multi-step workflows, or heavy mutation, it is probably becoming a full detail page.

> \[!NOTE]
> Screenshot placeholder: floating row preview panel open, repositioned, and tied to the active row in a realistic table.

## Configure the floating panel [#configure-the-floating-panel]

The built-in preview surface is a floating panel rendered above the table.

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  preview={{
    floating: {
      draggable: true,
      storageKey: "customers-preview",
    },
    renderPreview: ({ row, close }) => <CustomerPreview customer={row} onClose={close} />,
  }}
/>
```

The current preview options are:

* `floating.draggable` — lets users move the panel out of the way; defaults to `true`
* `floating.storageKey` — stores the panel position in `sessionStorage`
* `floating.width` — preferred panel width, clamped to the viewport
* `floating.height` — preferred panel height, clamped to the viewport
* `followRowHoverWhenOpen` — when `true`, hovering a different row moves the open preview to that row

If you omit `floating.storageKey`, the preview reuses the top-level `tableKey` for position storage.

> \[!NOTE]
> Screenshot placeholder: draggable preview panel moved away from the grid, making the floating behavior and preserved position feel intentional instead of accidental.

## Preview behavior [#preview-behavior]

When preview is configured:

* clicking a data row opens preview for that row
* `Space` toggles preview for the active data row
* `Esc` closes preview before clearing other interaction state
* keyboard movement can carry preview along with the active row
* `onTogglePreviewRow` can observe open/close events for analytics or side effects

If you also provide `rowActions.onOpenRow`, preview remains the in-table inspection path and open-row remains the deeper navigation path.

> \[!NOTE]
> Screenshot placeholder: row preview open beside a visible “open full record” affordance so the distinction between lightweight preview and deeper navigation is obvious.

## Verify row preview before you move on [#verify-row-preview-before-you-move-on]

Before you continue, confirm that:

* the preview content answers a real inspection need
* click and keyboard preview behavior match the intended workflow
* `Space` toggles preview on the active row
* `Esc` closes preview cleanly
* the floating panel can be moved when it would otherwise cover important data
* the panel position is only persisted when a stable `storageKey` is appropriate
* width and height overrides still behave well at smaller viewport sizes
* full row navigation still has a clear, separate path


# Add row selection (https://react-datatable.com/docs/guides/add-row-selection)

Use this guide when users need to act on more than one row at a time.

## When to add selection [#when-to-add-selection]

Row selection is for work, not decoration.

Add it when users need to:

* archive, assign, export, or update several rows at once
* keep a working set selected while previewing or opening individual rows
* apply a bulk workflow to either visible rows or the whole filtered result

If the table does not yet have a concrete selection-driven action, skip selection for now.

## Enable selection [#enable-selection]

Selection is configured with the `selection` prop.

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  selection={{
    enabled: true,
    showCheckboxOnHover: false,
  }}
/>
```

The current implementation is multi-select, so you do not need to set a separate mode.

When selection is enabled, the table adds a synthetic checkbox column at the start of the grid. That column is part of the interaction model, but not part of your saved user column order.

> \[!NOTE]
> Screenshot placeholder: selection column and selected rows visible in a realistic grid, with one active row that is not the same thing as the selected set.

## Control which rows can be selected [#control-which-rows-can-be-selected]

Use `getRowCanSelect` when the next action only applies to some rows.

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  selection={{
    enabled: true,
    getRowCanSelect: (row) => row.permissions.canArchive,
  }}
/>
```

Tie the predicate to the action the user is about to run.

Examples:

* only rows the current user can archive
* only invoices that are still unpaid
* only records that are safe to retry

The table uses that predicate both when rendering row checkboxes and when calculating how many rows are actually selectable in the current filtered result.

## Checkbox visibility [#checkbox-visibility]

`showCheckboxOnHover` controls whether unselected rows keep their checkbox hidden until the row is hovered.

```tsx
selection={{
  enabled: true,
  showCheckboxOnHover: true,
}}
```

Use hover-only checkboxes when selection is secondary to the main table workflow.

Show checkboxes all the time when:

* bulk work is a primary use case
* the table needs to feel obviously actionable
* users might otherwise miss that multi-select exists

> \[!NOTE]
> Screenshot placeholder: side-by-side or annotated comparison of hover-only checkboxes versus always-visible checkboxes, showing when each selection style feels right.

## Select-all scope [#select-all-scope]

The selection model supports two different scopes:

* explicit selection of concrete row IDs
* all-matching selection for the current online query

If you only need visible or loaded-row selection, stop here. If users need actions like "export every filtered customer," enable `allowSelectAllMatching`.

```tsx
<Datatable
  tableKey="customers"
  online={{
    mode: "pagination",
    queryKey: ["customers", "listOnline"],
    query: listCustomers,
  }}
  columns={columns}
  getRowId={(row) => row.id}
  selection={{
    enabled: true,
    allowSelectAllMatching: true,
  }}
/>
```

With that option enabled, the header checkbox can switch from explicit IDs to an `allMatching` descriptor built from the current table query.

## The two selection payloads [#the-two-selection-payloads]

The action layer receives a `DataTableSelectionDescriptor`.

```ts
type DataTableSelectionDescriptor =
  | {
      kind: "explicit"
      ids: string[]
    }
  | {
      kind: "allMatching"
      query: OnlineQueryStateInput
      includedIds: string[]
      excludedIds: string[]
      totalMatchingRows: number
    }
```

Use `explicit` when the action should target only the rows the browser has identified directly.

Use `allMatching` when the user means "everything matching the current filters, sorting, search, and grouping," even if many of those rows are not currently mounted.

That distinction keeps large online bulk workflows honest.

## All-matching action copy [#all-matching-action-copy]

When `allowSelectAllMatching` is enabled, the action text must say what will actually happen.

Good examples:

* `Export all 2,400 matching customers`
* `Archive 138 filtered issues`
* `Assign selected rows`

Bad examples:

* `Run`
* `Apply`
* `Export selected` when the action really targets all matching rows

The point is to prevent users from thinking they selected only what they can currently see.

> \[!NOTE]
> Screenshot placeholder: all-matching selection banner or copy state such as “Export all 2,400 matching customers,” making the scope larger than the visible viewport unmistakable.

## Resolve online selections on the server [#resolve-online-selections-on-the-server]

For all-matching selections, do not expect the browser to send every target row ID.

Use the saved query plus the exclusion list.

```ts
if (selection.kind === "explicit") {
  rows = await db.select().from(customers).where(inArray(customers.id, selection.ids))
} else {
  rows = await applyOnlineQuery(db.select().from(customers), selection.query)
  rows = rows.filter((row) => !selection.excludedIds.includes(row.id))
}
```

That lets the server resolve the real target set without forcing the client to load every row first.

## Selection resets when the query meaningfully changes [#selection-resets-when-the-query-meaningfully-changes]

Selection is tied to the current working result set.

When filters, search, sorting, or grouping change enough to alter that result set, the table clears selection instead of pretending the old selection still means the same thing.

A selected set from one query should not silently carry into a different query and trigger the wrong bulk action.

## Verify row selection before you move on [#verify-row-selection-before-you-move-on]

Before you continue, confirm that:

* selection exists because a real multi-row workflow needs it
* active row, preview, and selection are visually distinct
* `getRowCanSelect` blocks rows that should stay out of the workflow
* header select-all behaves the right way for your product surface
* all-matching copy states scope clearly when rows outside the viewport are included
* server actions can interpret `explicit` versus `allMatching` correctly
* changing the query clears stale selection instead of carrying it into a different result set


# Add saved views (https://react-datatable.com/docs/guides/add-saved-views)

Use saved views when users need intentional presets they can come back to, share, or promote to defaults.

Current-view persistence remembers the last state automatically. Saved views are named states people manage on purpose.

<ImageZoom src="/docs-media/guides/add-saved-views-toolbar-menu-placeholder.png" alt="Saved views menu open over a dark data table, showing a search field, create new view action, active private view, unsaved changes row, and additional named presets in the toolbar." className="my-7 w-full rounded-xs border-0" />

## Saved views vs persistence [#saved-views-vs-persistence]

Add saved views when users need to:

* switch between recurring table setups
* name those setups for later reuse
* give teammates a shared starting point
* set personal or workspace defaults

If the table only needs to remember what one person last did, start with current-view persistence instead.

## Configure a view adapter [#configure-a-view-adapter]

Saved views are enabled with `views`.

```tsx
import { localStorageDatatableViewAdapter } from "./react-datatable/persistence"

<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  views={{
    adapter: localStorageDatatableViewAdapter,
    workspaceId: workspace.id,
    userId: currentUser.id,
  }}
/>
```

The adapter inherits the top-level `tableKey`. Keep `workspaceId` and `userId` aligned with the rest of the table state system.

That keeps persistence, defaults, and saved views pointed at the same product surface.

## Expose the views control [#expose-the-views-control]

Most tables should expose saved views through the toolbar.

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  views={{
    adapter: localStorageDatatableViewAdapter,
    workspaceId: workspace.id,
    userId: currentUser.id,
  }}
  toolbar={{
    quickSearch: true,
    filterButton: true,
    displayOptions: true,
    views: true,
  }}
/>
```

If the table does not expose a views control, users have no obvious way to create, switch, or manage named presets.

> \[!NOTE]
> Screenshot placeholder: saved-views dropdown open in the toolbar with a few realistic named presets, a current active view, and obvious create/manage actions.

## What a saved view stores [#what-a-saved-view-stores]

Saved views store the same durable table state shape used by current-view persistence.

That means a view can capture:

* column visibility, order, and widths
* sticky column count and display settings
* sorting and grouping
* global search and column filters
* filter mode and group expansion

A saved view does not exist to preserve temporary action state like selection or open dialogs.

## Choose an adapter [#choose-an-adapter]

`localStorageDatatableViewAdapter` is good for browser-local experimentation and private presets.

It supports:

* creating, updating, and deleting private views
* setting a user default view

It does not support:

* sharing a view to the workspace
* setting workspace defaults

Use a backend adapter when views need to follow users across devices or support team-wide shared presets.

## Add a backend adapter [#add-a-backend-adapter]

A backend adapter implements the `DatatableViewAdapter` contract.

```ts
import type {
  DatatableView,
  DatatableViewAdapter,
} from "../../../kit/src/react-datatable/persistence"

export const datatableViewServerAdapter: DatatableViewAdapter = {
  async list(config) {
    const res = await fetch(`/api/datatable-views?tableKey=${config.tableKey}&workspaceId=${config.workspaceId}&userId=${config.userId}`)
    if (!res.ok) throw new Error("Failed to list views")
    return (await res.json()) as DatatableView[]
  },

  async get(config, viewId) {
    const res = await fetch(`/api/datatable-views/${viewId}?tableKey=${config.tableKey}&workspaceId=${config.workspaceId}&userId=${config.userId}`)
    if (res.status === 404) return null
    if (!res.ok) throw new Error("Failed to load view")
    return (await res.json()) as DatatableView
  },

  async create(config, view) {
    const res = await fetch("/api/datatable-views", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ config, view }),
    })
    if (!res.ok) throw new Error("Failed to create view")
    return (await res.json()) as DatatableView
  },

  async update(config, viewId, updates) {
    const res = await fetch(`/api/datatable-views/${viewId}`, {
      method: "PATCH",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ config, updates }),
    })
    if (!res.ok) throw new Error("Failed to update view")
    return (await res.json()) as DatatableView
  },

  async delete(config, viewId) {
    const res = await fetch(`/api/datatable-views/${viewId}`, {
      method: "DELETE",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ config }),
    })
    if (!res.ok) throw new Error("Failed to delete view")
  },

  async share(config, viewId) {
    const res = await fetch(`/api/datatable-views/${viewId}/share`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ config }),
    })
    if (!res.ok) throw new Error("Failed to share view")
    return (await res.json()) as DatatableView
  },

  async setUserDefault(config, viewId) {
    const res = await fetch("/api/datatable-views/defaults/user", {
      method: "PUT",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ config, viewId }),
    })
    if (!res.ok) throw new Error("Failed to set user default")
  },

  async setWorkspaceDefault(config, viewId) {
    const res = await fetch("/api/datatable-views/defaults/workspace", {
      method: "PUT",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ config, viewId }),
    })
    if (!res.ok) throw new Error("Failed to set workspace default")
  },
}
```

This is the kind of adapter you need when views are shared across a team, follow users across devices, or need admin-managed workspace defaults.

## Default precedence [#default-precedence]

Saved views can act as defaults, but only when there is no persisted current-view state to restore.

Initialization priority is:

1. built-in defaults
2. `initialState`
3. workspace default view
4. user default view
5. persisted current view
6. URL state

That means:

* a user default beats a workspace default
* remembered current-view state beats both defaults
* a shareable URL still wins over everything else

This keeps defaults useful without surprising users who already have a remembered working state.

## Create views from the current state, then make one active [#create-views-from-the-current-state-then-make-one-active]

The saved-views hook creates a new view from the current persisted table state and then marks that new view as active.

```ts
const createdView = await createViewFromCurrentState("My open renewals")
```

Applying a view writes its saved state into the store and sets `activeViewId`, which means normal persistence and URL sync can react to that change afterward.

## Use dirty state as a UX signal [#use-dirty-state-as-a-ux-signal]

The views hook compares the current persisted state to the active view state, excluding `activeViewId` itself.

That is how the table can tell whether the user is still on the saved preset or has drifted away from it.

Use that signal for UI like:

* “Save changes to view” actions
* unsaved-state badges
* prompts before overwriting a shared default

> \[!NOTE]
> Screenshot placeholder: a dirty saved-view state where the active preset has been modified, with a visible unsaved badge or “save changes” action.

## Match UI to adapter capabilities [#match-ui-to-adapter-capabilities]

Not every adapter supports the same actions.

The table checks adapter capabilities through optional methods:

* `setUserDefault` enables personal default management
* `share` and `setWorkspaceDefault` enable workspace sharing and workspace defaults

If your adapter does not support sharing, keep the UI private-only instead of showing actions that cannot succeed.

## Keep views stable across schema changes [#keep-views-stable-across-schema-changes]

Saved views depend on stable column IDs and compatible persisted-state shape.

Before shipping a table change that renames or removes columns, check whether old views will still deserialize into something sensible.

At minimum:

* keep column IDs stable when you can
* plan migrations if IDs must change
* retest user and workspace defaults after schema changes

## Use copy links for temporary sharing [#use-copy-links-for-temporary-sharing]

Saved views and URL sharing solve different problems.

Use saved views for durable named presets. Use URL sync or copy-link behavior for temporary, ad hoc sharing.

That keeps team-owned defaults distinct from one-off links pasted into chat.

## Verify saved views before you move on [#verify-saved-views-before-you-move-on]

Before you continue, confirm that:

* the table exposes a clear views entry point
* adapter scope matches the table's workspace and user boundaries
* the adapter capabilities match the UI affordances you show
* defaults behave correctly when persisted current-view state exists
* saved views survive reloads in the environments that matter
* column-ID changes will not silently break existing views

<Callout title="Next">
  Use [Server saved views endpoint](/docs/guides/server-saved-views-endpoint) when views should sync across devices or support sharing. Use [Add URL sync](/docs/guides/add-url-sync) when people only need temporary state sharing.
</Callout>


# Add sorting (https://react-datatable.com/docs/guides/add-sorting)

Use this guide when users need to change row order to answer real questions faster.

The goal is to make the right columns sortable, show the current ordering clearly, and then implement sorting correctly for the mode your table already uses.

The sorting UI can look similar in local and online mode. The important difference is where the order is actually computed.

<ImageZoom src="/docs-media/guides/add-sorting-display-ordering-placeholder.png" alt="Display options menu open over a dark data table, showing ordering controls with a searchable sort-column picker and a selected Region sort." className="my-7 w-full rounded-xs border-0" />

## Start with the columns where order changes decisions [#start-with-the-columns-where-order-changes-decisions]

Sorting is most useful on fields where users naturally ask for highest, newest, oldest, or alphabetic order:

* created date or updated date
* amount, revenue, score, or seat count
* priority, severity, or status rank
* company, owner, or project name

Do not make every column sortable by default just because the UI allows it. Decorative or ambiguous columns usually create more noise than value.

## Enable sorting where it helps [#enable-sorting-where-it-helps]

Columns are sortable unless you disable them, so turn sorting off on fields that should not control row order.

```tsx
const columns: DatatableColumn<Customer>[] = [
  {
    id: "company",
    accessorKey: "company",
    header: "Company",
  },
  {
    id: "revenue",
    accessorKey: "revenue",
    header: "Revenue",
  },
  {
    id: "notes",
    accessorKey: "notes",
    header: "Notes",
    enableSorting: false,
  },
]
```

This keeps sorting focused on fields with stable meaning.

## Active sorting is shown in several places in the UI [#active-sorting-is-shown-in-several-places-in-the-ui]

The shipped UI already exposes sorting in a few places:

* the column headers show sort state for sorted columns
* the display-options ordering section lets users choose one visible primary sort
* the applied sorting chip shows the active sort stack when it is visible

Use the default surfaces unless you have a clear product reason to hide one.

The most important thing to explain is where users can see the current ordering and where they can adjust it when they need more than one sort.

> \[!NOTE]
> Screenshot placeholder: sorting chip plus display-options ordering controls in a realistic table with one primary sort and one added secondary sort.

## Set a default order with `initialState.sorting` [#set-a-default-order-with-initialstatesorting]

Use table state, not column metadata, to define the first order users see.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  initialState={{
    sorting: [{ id: "company", desc: false }],
  }}
/>
```

This is the reliable way to start with a known ordering.

## Show active sorting in the UI [#show-active-sorting-in-the-ui]

If row order changes the meaning of the table, show that order clearly.

```tsx
<Datatable
  tableKey="customers"
  toolbar={{
    appliedState: {
      showSorting: true,
      showFilters: true,
    },
  }}
/>
```

The applied-state bar renders a sorting chip that:

* shows the primary sorted column
* shows when multiple columns are active
* lets users clear sorting quickly
* opens a popover for deeper multi-sort management

If you want sorting to stay active but feel less noisy, you can hide the chip intentionally. That is usually best for fixed implementation-level defaults rather than user-controlled ranking.

## In local mode, the browser sorts the loaded rows [#in-local-mode-the-browser-sorts-the-loaded-rows]

In local mode, the table sorts the rows already in memory.

Built-in sorting already works out of the box for common column types:

* `text` → text sort
* `number` → basic numeric sort
* `date` → datetime sort
* everything else → TanStack `auto`

You do not need to define a `sortingFn` for those common cases.

That works well when:

* the loaded dataset is bounded
* browser-side ordering is acceptable
* users do not need backend-authoritative ranking across unseen rows

Add `sortingFn` on the column definition only when local sorting needs custom business logic.

```tsx
{
  id: "priority",
  accessorKey: "priority",
  header: "Priority",
  sortingFn: (left, right) => {
    const rank = { critical: 0, high: 1, medium: 2, low: 3 }
    return rank[left.getValue() as keyof typeof rank] - rank[right.getValue() as keyof typeof rank]
  },
}
```

For example, a priority column may need a business-specific rank instead of normal text ordering.

Use stable raw values whenever possible:

* numeric amounts instead of formatted currency strings
* ISO timestamps or `Date` values instead of rendered labels
* normalized status ranks instead of arbitrary display text

## In online mode, your backend owns final order [#in-online-mode-your-backend-owns-final-order]

In online mode, the table sends sorting state to your query function and the backend becomes responsible for final order.

You do not need to implement client-side sorting functions in this case.

```ts
async function fetchCustomers(input: OnlineQueryInput): Promise<OnlineQueryResponse<Customer>> {
  let query = db.select().from(customers)

  const sortableFields = {
    company: customers.company,
    revenue: customers.revenue,
    createdAt: customers.createdAt,
  } as const

  for (const sort of input.sorting) {
    const field = sortableFields[sort.id as keyof typeof sortableFields]
    if (!field) continue

    query = query.orderBy(sort.desc ? desc(field) : asc(field))
  }

  query = query.orderBy(asc(customers.id))

  return runQuery(query, input)
}
```

In this mode, your backend must decide:

* which column IDs map to safe sortable fields
* how multi-sort priority is applied
* how grouped queries preserve consistent ordering
* how pagination avoids duplicate or skipped rows

Always end with a stable tie-breaker such as `id`. Without that, equal primary values can move between pages or viewport windows and create confusing duplicates or gaps.

## Verify sorting before you move on [#verify-sorting-before-you-move-on]

Before you continue, confirm that:

* only meaningful columns are sortable
* default order is set through `initialState.sorting`
* active sorting is visible when users need it
* local custom `sortingFn` logic matches the displayed meaning of the data
* online queries apply `input.sorting` through a safe field map and finish with a stable tie-breaker


# Add URL sync (https://react-datatable.com/docs/guides/add-url-sync)

Add URL sync when the URL is part of the product surface, not just a convenient way to share a one-off state.

<Callout title="Use URL sync for compact shareable state">
  URLs are great for search, filters, sorting, and other small query state. If the table state can grow large, current-view persistence or saved views will usually feel more reliable.
</Callout>

This is the right tool for pages where people expect refresh, back/forward navigation, or a pasted URL to preserve the active query state.

## When to use URL sync [#when-to-use-url-sync]

Use continuous URL sync when people need to:

* reload the page and keep the same search, filters, sorting, or grouping
* use back and forward navigation as part of the table workflow
* bookmark a live working state
* treat table state as part of the page's contract

Do not reach for it by default.

For many product tables, `persistState` plus `copyLink` is a better fit because it keeps the address bar stable during normal interaction.

## Turn on URL sync [#turn-on-url-sync]

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  urlSync={{
    enabled: true,
    acceptUrlParams: true,
    historyMode: "replace",
  }}
/>
```

The table reads URL state during initialization, merges it through the table-state coordinator, and then enables continuous store-to-URL sync after it is ready.

## History behavior [#history-behavior]

`historyMode` controls how state changes affect browser navigation.

* Use `"replace"` when the page should reflect the latest state without creating a long back-stack trail.
* Use `"push"` when stepping backward through prior table states is a real product behavior.

If you are unsure, start with `"replace"`.

## What URL sync includes [#what-url-sync-includes]

URL sync serializes the shareable query state of the table:

* global search (`q`)
* column filters (`f.columnId`)
* sorting (`s`)
* filter mode (`fm`)
* grouping (`g`)

It does not serialize personal layout preferences such as column visibility, widths, order, sticky columns, or the active saved-view ID.

Those belong in persistence and saved-view systems instead.

## Initialization priority [#initialization-priority]

URL state has the highest priority during initialization.

A URL-synced state can override:

* default store state
* persisted per-user state
* `initialState`
* saved default views
* current-view persistence

That precedence makes pasted links and bookmarks reliable.

## One-load URL params [#one-load-url-params]

If the page should accept shared URLs but should not keep mutating the address bar after load, use this pattern instead:

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
  urlSync={{
    enabled: false,
    acceptUrlParams: true,
  }}
  toolbar={{ copyLink: true }}
/>
```

In that mode, the table reads the incoming URL state once, applies it, and clears the datatable params afterward.

That is usually better for product tables where the address bar should stay clean but shared links should still work.

## Long filter states [#long-filter-states]

The URL writer uses the table's canonical filter encoding:

* text and number filters use their condition mode names
* date filters use `preset`, `range`, `before`, `after`, and `custom`
* list filters use `include` and `exclude`

Continuous URL sync works best when filters are reasonably compact and the page is not trying to encode large custom payloads into the URL.

If users routinely build large states, guide them toward saved views instead.

## Multi-table pages [#multi-table-pages]

Only one table on a page should run with `urlSync.enabled: true`.

The current implementation uses shared parameter names like `q`, `s`, and `f.columnId`, so multiple live URL-synced tables on the same page will collide.

If a page needs multiple tables, keep continuous URL sync on just one of them or avoid the feature entirely until namespacing exists.

## Verify production behavior [#verify-production-behavior]

Before shipping URL sync, verify that:

* opening a bookmarked or pasted URL restores the expected query state
* browser back and forward navigation match the chosen `historyMode`
* URL state overrides persisted state on first load
* the page still behaves correctly when the URL contains no datatable params
* overly large states fail safely and have a saved-view fallback in product guidance

## Keep the mental model simple for users [#keep-the-mental-model-simple-for-users]

The easiest product framing is:

* **Persistence** remembers my setup
* **Saved views** give names to reusable setups
* **Copy links** share a snapshot on demand
* **URL sync** makes the address bar part of the live table experience

If the page does not need that last promise, do not force it.

<Callout title="Next">
  Use [Add copy links](/docs/guides/add-copy-links) for one-off sharing. Use [Add saved views](/docs/guides/add-saved-views) when the state should become a named preset.
</Callout>


# Choose a data mode (https://react-datatable.com/docs/guides/choose-a-data-mode)

Use this guide after your table contract and columns are stable.

This is the canonical decision page for where table work happens. The downstream feature guides should inherit this choice instead of reopening it.

This page is really about three separate decisions:

1. should the browser own the working row set, or should the server stay authoritative?
2. if the server owns the rows, should users move through pages or through a continuous scroll?
3. should the table mount the full loaded list, or virtualize it and mount only the visible window?

Keep those decisions separate in your head:

* local vs online decides where query semantics live
* pagination vs infinite decides how online users move through results
* virtualization decides how many loaded rows are mounted in the DOM

## Start by choosing where query semantics live [#start-by-choosing-where-query-semantics-live]

Pick the place where filtering, sorting, grouping, and totals should really happen.

| Choose      | When it fits                                                                           | Main prop |
| ----------- | -------------------------------------------------------------------------------------- | --------- |
| Local mode  | The browser can hold the full result set and client-side table behavior is acceptable. | `data`    |
| Online mode | The backend should stay authoritative for query semantics, totals, or row windows.     | `online`  |

This is the highest-leverage choice. It matters more than whether the table later uses virtualization, preview, or saved views.

## Path 1: choose local mode when the browser can own the rows [#path-1-choose-local-mode-when-the-browser-can-own-the-rows]

Use local mode when:

* the full dataset is bounded and cheap to preload
* filtering and sorting can happen in memory
* you want the shortest path to a responsive table
* the backend does not need to recompute totals, facets, or grouped output on every interaction

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  data={customers}
  getRowId={(row) => row.id}
/>
```

Local mode keeps the integration simple: your app fetches rows once, then the table handles search, filters, sorting, grouping, and selection in the browser.

### Then decide whether to turn on virtualization [#then-decide-whether-to-turn-on-virtualization]

Local mode decides who owns query semantics. Virtualization only decides how many loaded rows are mounted in the DOM.

Keep virtualization off when:

* the table stays responsive with the full DOM mounted
* row height is simple and fairly stable
* users usually work with smaller result sets

Turn virtualization on when:

* the data is still reasonable to preload, but mounting every row feels sluggish
* rows contain heavier React cells, menus, badges, previews, charts, or nested layouts

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  data={customers}
  getRowId={(row) => row.id}
  virtualization={{ mode: "viewport", rowOverscanCount: 8 }}
/>
```

Rule of thumb: if the browser can own the rows but the page feels heavy, try virtualization before moving query semantics to the server. If the problem is backend truth, totals, permissions, or data size, choose online mode instead.

## Path 2: choose online mode when the server should stay authoritative [#path-2-choose-online-mode-when-the-server-should-stay-authoritative]

Use online mode when:

* the dataset is too large to preload safely
* permissions, tenant boundaries, or business rules must stay enforced on the server
* filtering, sorting, grouping, totals, or facets need backend truth
* users need server pagination or infinite loading

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  getRowId={(row) => row.id}
  online={{
    mode: "pagination",
    queryKey: ["customers", workspaceId],
    query: fetchCustomersPage,
  }}
/>
```

In online mode, the table still owns interaction state, but your backend owns query semantics. The table sends search, filters, sorting, grouping, and navigation input; the server returns render-ready rows plus totals.

That path usually also requires server work: query parsing, filtering, sorting, pagination or windowing, and stable row identity all need to be implemented on the backend.

### Next, choose the online navigation model [#next-choose-the-online-navigation-model]

If you choose `online`, pick the navigation pattern that matches the product experience.

### Use pagination when page boundaries matter [#use-pagination-when-page-boundaries-matter]

Choose `mode: "pagination"` when users expect explicit pages, exact totals, and deliberate page movement.

```tsx
online={{
  mode: "pagination",
  queryKey: ["customers", workspaceId],
  pageSize: 50,
  initialPageIndex: 0,
  query: fetchCustomersPage,
}}
```

This is usually the better default for back-office tables, audit surfaces, and workflows where users care about counts and repeatable pages.

Virtualization is often unnecessary here, especially when page sizes are moderate and rows are simple. Add it only when a single page still mounts enough heavy UI to feel slow.

### Use infinite mode when users browse through a long list [#use-infinite-mode-when-users-browse-through-a-long-list]

Choose `mode: "infinite"` when users move through a continuous result set and page numbers add little value.

```tsx
online={{
  mode: "infinite",
  queryKey: ["customers", workspaceId],
  pageSize: 80,
  prefetchRows: 160,
  query: fetchCustomersWindow,
}}
```

This works best when your backend can load stable row windows by offset and the product experience is centered on scrolling rather than paging.

Here, `prefetchRows` is an **online data-loading** option, not a virtualization option. It tells the table to fetch extra server rows around the current visible window so scrolling feels smoother.

In practice, infinite mode should usually be paired with virtualization. Once users can scroll through a long continuously loaded list, mounting everything defeats the point.

### Keep online navigation and virtualization separate [#keep-online-navigation-and-virtualization-separate]

Online mode decides how data is fetched. Virtualization decides how many loaded rows are mounted in the DOM.

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  getRowId={(row) => row.id}
  online={{
    mode: "infinite",
    queryKey: ["customers", workspaceId],
    pageSize: 80,
    prefetchRows: 160,
    query: fetchCustomersWindow,
  }}
  virtualization={{ mode: "viewport", rowOverscanCount: 8 }}
/>
```

A few important boundaries:

* `online.mode: "infinite"` is a server-loading strategy
* `virtualization.mode: "viewport"` is a DOM-rendering strategy
* `prefetchRows` warms server data around the visible range
* `rowOverscanCount` mounts extra DOM rows around the viewport

Choose online mode for backend-owned query semantics, and choose virtualization for render-cost control.

## Build a stable `queryKey` [#build-a-stable-querykey]

Your `queryKey` is the table's dataset identity for online requests. It is not a React Query cache key. It should identify which dataset this table is querying, not which temporary view state the user is in.

```tsx
queryKey: ["customers", workspaceId, segmentId]
```

Only include `segmentId` when it is a fixed app scope outside the table controls.

For example, `"enterprise"` belongs in `queryKey` if the whole route is an Enterprise Customers page and the table can never show non-enterprise rows. If the user chooses Enterprise from a Plan or Segment filter, then it is table state instead and should not be in `queryKey`.

Good things to include:

* workspace or tenant IDs
* route or product scope
* a fixed dataset segment that the whole table is scoped to

Do **not** include things like page number, scroll offset, search text, filters, sorting, or grouping there. The table already sends those through the online query input.

## Load online data with `fetch` [#load-online-data-with-fetch]

The simplest version is a plain async function that accepts the table's query input and returns the table's online response shape.

```tsx
async function fetchCustomersPage(input: OnlineQueryInput): Promise<OnlineQueryResponse<Customer>> {
  const response = await fetch("/api/customers/table", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(input),
  })

  if (!response.ok) {
    throw new Error("Failed to load customers")
  }

  return response.json()
}

<Datatable
  tableKey="customers"
  columns={columns}
  getRowId={(row) => row.id}
  online={{
    mode: "pagination",
    queryKey: ["customers", workspaceId],
    query: fetchCustomersPage,
  }}
/>
```

This is enough for a server-owned table. The table builds the request from current search, filters, sorting, grouping, pagination, and saved state.

This example uses `POST` so the table query can stay as JSON. That is practical for structured filter, sorting, grouping, and pagination input, and it avoids long encoded query strings. `POST` is not required; if your API prefers GET, encode the same input into the URL and return the same online response shape.

## Add React Query when you want cached online requests [#add-react-query-when-you-want-cached-online-requests]

After the plain `fetch` version, you can cache the table request with libraries like React Query. This can make sense for datatables because users often move between tabs, routes, and detail pages, then expect already-loaded rows to be available without another network request.

Keep the table's `online.queryKey` as the dataset identity, and use React Query's `queryKey` for the cached response.

```tsx
import { useQueryClient } from "@tanstack/react-query"

function CustomersTable({ workspaceId }: { workspaceId: string }) {
  const queryClient = useQueryClient()

  return (
    <Datatable
      tableKey="customers"
      columns={columns}
      getRowId={(row) => row.id}
      online={{
        mode: "pagination",
        queryKey: ["customers", workspaceId],
        query: (input) =>
          queryClient.fetchQuery({
            queryKey: ["customers-table-response", workspaceId, input],
            queryFn: () => fetchCustomersPage(input),
            staleTime: 30_000,
          }),
      }}
    />
  )
}
```

Use this shape when cache reuse, request deduping, retries, or background refresh are part of the app shell. The table still owns the online query input; React Query owns the transport cache around that input.

The table interface is agnostic to the fetching library. You can use the same `online.query` contract with `fetch`, tRPC, gRPC, Apollo Client, or another data client as long as the function returns the table's online response shape.

## Reuse prefetched first-page data safely [#reuse-prefetched-first-page-data-safely]

If a route already loaded the first online result, pass it through `initialData` and guard it with `initialDataQueryState`.

```tsx
online={{
  mode: "pagination",
  queryKey: ["customers", workspaceId],
  initialData,
  initialDataQueryState,
  query: fetchCustomersPage,
}}
```

That guard matters when persisted state or URL state changes the final query before the table settles. Without it, users can briefly see stale rows from the wrong filter or view.

## Use this quick decision path [#use-this-quick-decision-path]

Choose local mode if all of these are true:

* the full row set is reasonably bounded
* browser-side filtering and sorting are acceptable
* backend-owned totals or grouped summaries are not required

Choose online mode if any of these are true:

* server rules must stay authoritative
* the result set is large or continuously changing
* pagination or infinite row windows are part of the product design
* online grouping, totals, or facets should match backend truth

Then choose rendering with these defaults:

* local mode: depends on row count and rendering cost
* online + pagination: usually do **not** start with virtualization
* online + infinite: usually **do** virtualize

## Verify the choice before adding features [#verify-the-choice-before-adding-features]

Before you move on, confirm that:

* row identity still comes from a stable domain ID
* the chosen mode matches where query semantics should live
* your `queryKey` matches the dataset identity
* online query functions can return rows, totals, and grouped output accurately if needed
* virtualization settings are being treated as rendering controls, not data-loading controls
* local mode has an explicit virtualization decision instead of inheriting the default accidentally
* downstream feature guides in your app can now assume this decision is settled

<Callout title="Next">
  Add [global search](/docs/guides/add-global-search) and [column filters](/docs/guides/add-column-filters) when query behavior is next. Use [Tune virtualization](/docs/guides/tune-virtualization) for render performance, or [Online API](/docs/reference/online-api) for exact request and response shapes.
</Callout>


# Configure display options (https://react-datatable.com/docs/guides/configure-display-options)

Use this guide when users need control over table presentation without exposing every internal table setting.

The goal is to decide which layout controls belong in your product, make those controls easy to find, and keep column visibility, frozen columns, and ordering feedback consistent.

<ImageZoom src="/docs-media/guides/configure-display-options-panel.png" alt="Display menu open over a data table, showing options for grouping, ordering by multiple columns, freezing one column, toggling display settings, and managing column visibility." className="my-7 w-full rounded-xs border-0" />

## Start by deciding how much presentation control users really need [#start-by-deciding-how-much-presentation-control-users-really-need]

Display options are best for choices that help users work faster without changing the underlying data query:

* which columns are visible
* how many columns stay frozen on the left
* whether ordering feedback should stay visible
* whether headers or grid lines should be shown
* whether empty groups should appear when grouping is active

If a control would confuse most users or break a product convention, hide it instead of exposing it just because the component supports it.

## Turn on the toolbar entry point [#turn-on-the-toolbar-entry-point]

The display-options button lives in the toolbar.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  toolbar={{
    displayOptions: true,
  }}
/>
```

If your toolbar is enabled, this button is part of the right-side control cluster alongside views and copy-link actions.

## Shape the popover around the controls users actually need [#shape-the-popover-around-the-controls-users-actually-need]

Use the top-level `displayOptions` config to decide which sections appear inside the popover.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  toolbar={{
    displayOptions: true,
  }}
  displayOptions={{
    sections: {
      // whether to show a specific section
      grouping: false,
      ordering: true,
      freezeColumns: true,
      displaySettings: true,
      columnVisibility: true,
    },
    controls: {
      // whether to show specific controls within sections
      showEmptyGroups: false,
      showOrderingBadge: true,
    },
  }}
/>
```

That split is important:

* `toolbar.displayOptions` decides whether the button exists
* top-level `displayOptions` decides what the popover contains

## Keep the display-options scope focused on presentation [#keep-the-display-options-scope-focused-on-presentation]

The current popover groups controls into a few jobs:

* grouping and ordering controls near the top
* frozen-column control
* display settings toggles
* column visibility management
* a reset action at the bottom

## Decide whether users should manage ordering here [#decide-whether-users-should-manage-ordering-here]

The popover includes an ordering section, but it is best for simple primary-sort selection.

Use it when users need to:

* pick the main sorted column
* flip ascending versus descending
* clear sorting quickly

If users need deeper multi-sort management, the applied sorting chip remains the clearer surface today because it exposes the full sort stack and drag-to-reorder behavior.

## Use display settings to control how much state stays visible [#use-display-settings-to-control-how-much-state-stays-visible]

The display settings section currently exposes toggles for:

* show order indicator
* show column headers
* show horizontal grid lines
* show vertical grid lines
* show empty groups

`showOrderingBadge` is especially useful when you want sorting to remain active but not always visible in the applied-state bar.

That gives you a clean split:

* sorting logic can stay active
* the chip row can stay quieter when the order is just a product default

## Choose the right column visibility UI mode [#choose-the-right-column-visibility-ui-mode]

`columnVisibilityUI` controls how users manage visible versus hidden columns.

* `"badges"`: best for smaller sets where drag-and-drop chips stay readable
* `"dropdown"`: best for larger sets where search matters more than spatial scanning
* `"auto"`: let the source switch based on hideable column count

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  columnVisibilityUI="dropdown"
  toolbar={{
    displayOptions: true,
  }}
/>
```

In badge mode, users can both toggle visibility and reorder visible versus hidden columns directly in the popover.

> \[!NOTE]
> Screenshot placeholder: badge-style column visibility UI with visible and hidden columns separated clearly, including drag-and-drop reordering chips.

## Add the quick column picker when visibility changes are frequent [#add-the-quick-column-picker-when-visibility-changes-are-frequent]

The toolbar popover is not the only visibility entry point.

`viewColumnsButton` adds the `+` button pinned at the right edge of the grid for fast column toggles close to the table itself.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  viewColumnsButton={{
    show: true,
  }}
/>
```

Use this when people often adjust visible columns while scanning the table, not only from the toolbar.

> \[!NOTE]
> Screenshot placeholder: auxiliary `+` view-columns button pinned at the right edge of the grid, showing a faster in-table visibility control than the main toolbar popover.

## Let users keep layout changes across sessions [#let-users-keep-layout-changes-across-sessions]

If users change these table settings, you can keep those choices across sessions with [current-view persistence](/docs/guides/add-current-view-persistence) or [saved views](/docs/guides/add-saved-views).

That is especially useful for column visibility and ordering indicators, which are often part of how users recognize their working view.

## Verify display options before you move on [#verify-display-options-before-you-move-on]

Before you continue, confirm that:

* the display-options button appears where users expect it in the toolbar
* the popover includes only the sections your product wants to expose
* `showOrderingBadge` matches whether sorting should stay visibly user-controlled
* the chosen `columnVisibilityUI` fits your column count
* frequently changed layouts are backed by persistence or saved views


# Define columns (https://react-datatable.com/docs/guides/define-columns)

Use this guide right after Quickstart, before you lock the top-level table contract.

The goal is to define columns that stay stable over time and make the right behavior obvious to the table.

## Start from the row shape [#start-from-the-row-shape]

Write or confirm the row type before you define columns:

```tsx
export type Customer = {
  id: string
  company: string
  owner: string
  status: "active" | "trial" | "paused"
  seats: number
  renewalDate: string
}
```

This keeps columns grounded in real product data instead of ad-hoc UI formatting.

## Give every column a stable ID [#give-every-column-a-stable-id]

Use explicit IDs for every column:

```tsx
import type { DatatableColumn } from "./react-datatable"

export const customerColumns: DatatableColumn<Customer>[] = [
  {
    id: "company",
    accessorKey: "company",
    header: "Company",
    filterType: "text",
  },
  {
    id: "status",
    accessorKey: "status",
    header: "Status",
    filterType: "text-list",
    filterOptions: {
      options: ["active", "trial", "paused"],
    },
  },
]
```

Do not derive IDs from translated labels or visible text.

Column IDs feed filtering, sorting, grouping, URL state, saved views, persisted state, and online query inputs. If an ID changes, stored user state may stop mapping correctly.

> \[!NOTE]
> Screenshot placeholder: realistic table with columns whose visible labels differ from stable internal IDs, emphasizing why stable column contracts matter.

## Prefer `accessorKey` for real fields [#prefer-accessorkey-for-real-fields]

Use `accessorKey` when the displayed value maps directly to a row property:

```tsx
{
  id: "company",
  accessorKey: "company",
  header: "Company",
  filterType: "text",
}
```

This is the easiest shape to keep consistent across local mode, online mode, and API mapping.

## Use `accessorFn` when the field is nested or intentionally derived [#use-accessorfn-when-the-field-is-nested-or-intentionally-derived]

Use `accessorFn` when the displayed value comes from nested data or from a computed value.

For example, if the row contains a richer owner object, keep the row shape honest and pick the exact value the table should use:

```tsx
export type Customer = {
  id: string
  company: string
  owner: {
    id: string
    name: string
    company: {
      id: string
      name: string
    }
  }
  status: "active" | "trial" | "paused"
}

{
  id: "ownerName",
  header: "Owner",
  accessorFn: (row) => row.owner.name,
  filterType: "text",
}
```

That is usually better than flattening product data just to satisfy the table.

Use `accessorFn` when the column value is computed too:

```tsx
{
  id: "accountHealth",
  header: "Health",
  accessorFn: (row) => row.status + ":" + row.seats,
  enableSorting: false,
}
```

When you do this, keep the ID explicit and confirm whether your online backend also needs a matching derived field or sort/filter concept. If the backend sorts or filters on `owner.name`, make sure the server-side contract uses the same semantic field even if the raw object is richer.

> \[!NOTE]
> Screenshot placeholder: nested owner/company data rendered as a clean Owner column, with the richer underlying object shape called out in accompanying art direction.

## Choose the filter type based on the data, not the styling [#choose-the-filter-type-based-on-the-data-not-the-styling]

A good column definition decides how users should query the field.

```tsx
{
  id: "seats",
  accessorKey: "seats",
  header: "Seats",
  filterType: "number",
  enableSorting: true,
}
```

A few common mappings:

* names and labels → `text`
* finite statuses or plans → `text-list`
* numeric measures → `number`
* machine-readable dates → `date`

If a field is a finite set, use list-style filtering even if the cell is rendered as a badge or pill.

## Decide sorting and grouping intentionally [#decide-sorting-and-grouping-intentionally]

Columns define more than rendering. For each one, decide:

* should users sort this field?
* should users group by it?
* does grouped output need a grouping spec?

```tsx
{
  id: "renewalDate",
  accessorKey: "renewalDate",
  header: "Renewal",
  filterType: "date",
  enableGrouping: true,
  groupingSpec: {
    defaultVariant: "month",
    variants: {
      month: { kind: "date_trunc", granularity: "month" },
    },
  },
}
```

If a column is mostly a control surface, like an actions column, sorting and filtering should usually be disabled.

## Pick a column pattern that matches the field [#pick-a-column-pattern-that-matches-the-field]

Once the behavior is clear, choose the presentation pattern that matches it:

* plain text for names and identifiers
* number formatting for metrics while keeping the raw value numeric
* date formatting for machine-readable dates
* badges or pills for finite status-like fields
* links for primary entities that open a detail page
* compact action buttons for per-row controls

The key idea is that the column pattern includes both behavior and UI, not just the cell renderer.

## Use metadata when on-screen labels should differ from the contract [#use-metadata-when-on-screen-labels-should-differ-from-the-contract]

If the table needs a different label in the interface than it uses in the column contract, use column metadata rather than changing the column ID.

`meta.displayName`, `meta.filterName`, and related metadata let the interface stay readable while the underlying column contract stays stable.

## Check your columns before moving on [#check-your-columns-before-moving-on]

Before you add more features, verify that:

* each column has a stable ID
* accessor choice matches the real data shape
* filter type matches the field semantics
* sorting and grouping are enabled only where they make sense
* custom cells do not hide the underlying data behavior

<Callout title="Next">
  Continue with [Define your table](/docs/guides/define-your-table) and [Choose a data mode](/docs/guides/choose-a-data-mode). Then move into the feature guides you actually need.
</Callout>


# Define your table (https://react-datatable.com/docs/guides/define-your-table)

Use this guide after [Define columns](/docs/guides/define-columns), when you are ready to lock the top-level table contract before adding more features.

At this point, assume you already know which columns the table needs and how they access row data.

The goal is to make three decisions up front:

1. what each row's stable ID is
2. whether the browser or the server owns the working row set
3. which top-level datatable props belong in your first integration

## Start with the smallest working contract [#start-with-the-smallest-working-contract]

A table still needs four things to mount correctly:

* `columns`
* `getRowId`
* either `data` or `online`
* a normal React render location in your app

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  data={customers}
  getRowId={(row) => row.id}
/>
```

If this contract is not stable yet, do not spend time on grouping, preview, or persistence. Get this boundary right first.

If the columns themselves still feel unsettled, go back and finish [Define columns](/docs/guides/define-columns) before you freeze the table boundary.

> \[!NOTE]
> Screenshot placeholder: the smallest working datatable integration rendered in an app page with only core columns, row identity, and local data wired up.

## Pick a real row identity [#pick-a-real-row-identity]

Give every row a durable domain ID:

```tsx
getRowId={(row) => row.id}
```

Use a real business identifier, not an array index.

Stable row IDs keep table behavior predictable when users sort, filter, select, save views, or reload server data.

## Choose the top-level data contract [#choose-the-top-level-data-contract]

This page is where you decide whether the table is powered by a local row set or an online query contract.

### Use `data` when the browser can own the rows [#use-data-when-the-browser-can-own-the-rows]

Choose local mode when:

* the full result set comfortably fits in the browser
* filtering and sorting can happen on the client
* you want the fastest path to a working table

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  data={customers}
  getRowId={(row) => row.id}
/>
```

### Use `online` when the server should stay authoritative [#use-online-when-the-server-should-stay-authoritative]

Choose online mode when:

* filtering, sorting, grouping, or totals must follow server rules
* the dataset is too large to keep fully in memory
* you need pagination, infinite scroll, or server-owned row windows

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  getRowId={(row) => row.id}
  online={{
    mode: "pagination",
    queryKey: ["customers", workspaceId],
    query: fetchCustomers,
  }}
/>
```

The visible UI can feel similar in both modes. The real difference is where table work happens.

> \[!NOTE]
> Screenshot placeholder: one local table example and one online table example using the same surface, with visual annotations showing browser-owned versus server-owned query behavior.

## Keep the app boundary clean [#keep-the-app-boundary-clean]

Your app should continue to own:

* domain types and business rules
* route params, workspace scope, and permissions
* server queries, mutations, and side effects
* surrounding page layout

The datatable should own:

* row modeling
* sorting, filtering, grouping, visibility, and selection state
* rendering the grid and related built-in controls

This split makes later customization safer because you are not mixing business logic into table internals.

## Add only the top-level options you already need [#add-only-the-top-level-options-you-already-need]

A good first integration usually adds a small amount of configuration around the core contract:

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  data={customers}
  getRowId={(row) => row.id}
  toolbar={{
    quickSearch: { placeholder: "Search customers..." },
    filterButton: true,
    displayOptions: true,
  }}
  selection={{ enabled: true }}
/>
```

Start with the options your users will see immediately. Add deeper capabilities one at a time from the guides.

## Use `choose-a-data-mode` to make the next decision more explicit [#use-choose-a-data-mode-to-make-the-next-decision-more-explicit]

Once the table contract is mounted, move to [Choose a data mode](/docs/guides/choose-a-data-mode) for the deeper decision tree:

* local versus online ownership
* pagination versus infinite loading for online mode
* virtualization as a separate rendering choice

That page is the canonical place to reason about those boundaries. The downstream feature guides should inherit that choice, not reopen it.

## Verify the contract before layering on features [#verify-the-contract-before-layering-on-features]

Before moving on, check that:

* rows render with the columns you expect
* row IDs stay stable across reloads and reordering
* the chosen data mode matches where your filtering and sorting logic should live
* the table mounts without extra one-off wiring in feature components
* the app boundary still feels clean before you add feature-specific options

Next, [choose a data mode](/docs/guides/choose-a-data-mode) before you add feature-specific behavior.


# Server persisted state endpoint (https://react-datatable.com/docs/guides/server-persisted-state-endpoint)

Use this guide when the table should remember one user's last working state across reloads, browsers, or devices.

This page is about automatic state persistence. If users need named presets they can manage and share, use [Server saved views endpoint](/docs/guides/server-saved-views-endpoint).

## Decide what this endpoint stores [#decide-what-this-endpoint-stores]

Current-view persistence is quiet, personal memory.

It usually stores:

* column visibility, order, and widths
* sticky columns and display toggles
* sorting
* grouping and grouped expansion
* global search and column filters
* filter mode
* `activeViewId` when the user explicitly chose a saved view

It should not store temporary action state like row selection or open dialogs.

## Start with the persisted snapshot type [#start-with-the-persisted-snapshot-type]

The adapter reads and writes `PersistedTableStateSnapshot` values.

```ts
import {
  buildPersistedTableStateSnapshot,
  replayPersistedTableState,
} from "react-datatable-server"
```

The useful part is the full stored shape:

```ts
interface PersistedTableStateSnapshot {
  version: 1
  query: {
    filters: ColumnFilter[]
    sorting: SortingState
    globalFilter: string
    grouping: {
      columns: string[]
      showEmptyGroups: boolean
      expansion: {
        defaultExpanded: boolean
        overrides: Record<string, boolean>
      }
    } | null
    filterMode: "AND" | "OR"
  }
  presentation: {
    showColumnHeaders: boolean
    stickyColumnsCount: number
    showHorizontalLines: boolean
    showVerticalLines: boolean
    showOrderingBadge: boolean
    columnOrder: string[]
    columnVisibility: Record<string, boolean>
    columnWidths: Record<string, number>
    activeViewId: string | null
  }
}
```

That means persisted state stores both backend-facing query state and the presentation state needed to restore the table.

Use `buildPersistedTableStateSnapshot()` before saving, and `replayPersistedTableState()` after loading.

For the surrounding contracts, see [TypeScript types](/docs/reference/typescript-types).

## Create the Postgres table with Drizzle [#create-the-postgres-table-with-drizzle]

For a multi-tenant SaaS app, a practical schema is one row per table, workspace, and user.

That gives each user-facing table surface one remembered state.

```ts
import { jsonb, pgTable, text, timestamp, uniqueIndex } from "drizzle-orm/pg-core"
import type { PersistedTableStateSnapshot } from "react-datatable/persistence"

export const datatableState = pgTable(
  "datatable_state",
  {
    id: text("id").primaryKey(),
    tableKey: text("table_key").notNull(),
    workspaceId: text("workspace_id").notNull(),
    userId: text("user_id").notNull(),
    snapshot: jsonb("snapshot").$type<PersistedTableStateSnapshot>().notNull(),
    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => ({
    scopeIdx: uniqueIndex("datatable_state_scope_idx").on(
      table.tableKey,
      table.workspaceId,
      table.userId
    ),
  })
)
```

That unique scope is the important part. It prevents one table surface from overwriting another.

## Add a small storage service [#add-a-small-storage-service]

Keep the persistence logic in one backend module.

```ts
import { and, eq } from "drizzle-orm"
import { datatableState } from "@/db/schema"
import type { PersistedTableStateSnapshot } from "react-datatable/persistence"

export async function getDatatableState(args: {
  db: Database
  tableKey: string
  workspaceId: string
  userId: string
}) {
  return args.db.query.datatableState.findFirst({
    where: and(
      eq(datatableState.tableKey, args.tableKey),
      eq(datatableState.workspaceId, args.workspaceId),
      eq(datatableState.userId, args.userId)
    ),
  })
}

export async function upsertDatatableState(args: {
  db: Database
  id: string
  tableKey: string
  workspaceId: string
  userId: string
  snapshot: PersistedTableStateSnapshot
}) {
  await args.db
    .insert(datatableState)
    .values({
      id: args.id,
      tableKey: args.tableKey,
      workspaceId: args.workspaceId,
      userId: args.userId,
      snapshot: args.snapshot,
    })
    .onConflictDoUpdate({
      target: [datatableState.tableKey, datatableState.workspaceId, datatableState.userId],
      set: {
        snapshot: args.snapshot,
        updatedAt: new Date(),
      },
    })
}

export async function deleteDatatableState(args: {
  db: Database
  tableKey: string
  workspaceId: string
  userId: string
}) {
  await args.db
    .delete(datatableState)
    .where(
      and(
        eq(datatableState.tableKey, args.tableKey),
        eq(datatableState.workspaceId, args.workspaceId),
        eq(datatableState.userId, args.userId)
      )
    )
}
```

## Add the GET endpoint [#add-the-get-endpoint]

The load endpoint should either return a saved snapshot or `404`.

```ts
import { NextRequest, NextResponse } from "next/server"
import { getDatatableState } from "@/server/datatable/state-store"
import { requireWorkspaceAccess } from "@/server/auth"

export async function GET(request: NextRequest) {
  const session = await requireWorkspaceAccess(request)
  const tableKey = request.nextUrl.searchParams.get("tableKey")

  if (!tableKey) {
    return NextResponse.json({ error: "tableKey is required" }, { status: 400 })
  }

  const record = await getDatatableState({
    db: session.db,
    tableKey,
    workspaceId: session.workspaceId,
    userId: session.userId,
  })

  if (!record) {
    return NextResponse.json({ error: "Not found" }, { status: 404 })
  }

  return NextResponse.json(record.snapshot)
}
```

## Add the PUT and DELETE endpoints [#add-the-put-and-delete-endpoints]

Write state snapshots on save, and remove the row on reset.

The request body still uses `PersistedTableState`. The server converts it to `PersistedTableStateSnapshot` before writing.

```ts
import { NextRequest, NextResponse } from "next/server"
import { createId } from "@paralleldrive/cuid2"
import { buildPersistedTableStateSnapshot } from "react-datatable-server"
import type { PersistedTableState } from "react-datatable/persistence"
import { deleteDatatableState, upsertDatatableState } from "@/server/datatable/state-store"
import { requireWorkspaceAccess } from "@/server/auth"

export async function PUT(request: NextRequest) {
  const session = await requireWorkspaceAccess(request)
  const body = (await request.json()) as {
    tableKey: string
    state: PersistedTableState
  }

  const snapshot = buildPersistedTableStateSnapshot(body.state)

  await upsertDatatableState({
    db: session.db,
    id: createId(),
    tableKey: body.tableKey,
    workspaceId: session.workspaceId,
    userId: session.userId,
    snapshot,
  })

  return NextResponse.json({ ok: true })
}

export async function DELETE(request: NextRequest) {
  const session = await requireWorkspaceAccess(request)
  const body = (await request.json()) as { tableKey: string }

  await deleteDatatableState({
    db: session.db,
    tableKey: body.tableKey,
    workspaceId: session.workspaceId,
    userId: session.userId,
  })

  return NextResponse.json({ ok: true })
}
```

## Wire the frontend table-state adapter [#wire-the-frontend-table-state-adapter]

Now connect `persistState.adapter` to those endpoints.

The contract is:

* `get()` returns `PersistedTableStateSnapshot | null`
* `set()` writes the same snapshot type
* `delete()` clears the saved row for that table scope

```ts
import type {
  PersistedTableStateSnapshot,
  TableStateAdapter,
} from "react-datatable/persistence"
import { replayPersistedTableState } from "react-datatable-server"

export const tableStateServerAdapter: TableStateAdapter = {
  async get(config) {
    const url = new URL("/api/datatable-state", window.location.origin)
    url.searchParams.set("tableKey", config.tableKey)

    const res = await fetch(url)
    if (res.status === 404) return null
    if (!res.ok) throw new Error("Failed to load datatable state")

    const snapshot = (await res.json()) as PersistedTableStateSnapshot
    return replayPersistedTableState(snapshot)
  },

  async set(config, state) {
    const res = await fetch("/api/datatable-state", {
      method: "PUT",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        tableKey: config.tableKey,
        state,
      }),
    })

    if (!res.ok) throw new Error("Failed to save datatable state")
  },

  async delete(config) {
    const res = await fetch("/api/datatable-state", {
      method: "DELETE",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        tableKey: config.tableKey,
      }),
    })

    if (!res.ok) throw new Error("Failed to delete datatable state")
  },
}
```

The important part is consistency:

* API reads return the persisted-state snapshot
* API writes persist the same snapshot shape
* UI code calls `replayPersistedTableState()` before handing the value back to the table

## Connect it to `Datatable` [#connect-it-to-datatable]

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  data={rows}
  getRowId={(row) => row.id}
  persistState={{
    adapter: tableStateServerAdapter,
    debounceMs: 1500,
  }}
/>
```

Use a stable `tableKey`. It is the top-level product boundary for remembered state.

## Keep precedence predictable [#keep-precedence-predictable]

Persistence restores one person's last saved state, but it does not win over a specific URL state on the first load. That keeps shared or bookmarked table URLs reliable while still letting the table remember the user's last working state afterward.

For the full state-loading details, see [State Lifecycle](/docs/concepts/state-lifecycle).

That is why current-view persistence and saved views can coexist cleanly when both use the same underlying query and presentation model.

## Verify the persistent state endpoint before you move on [#verify-the-persistent-state-endpoint-before-you-move-on]

Run one full user-path check before you ship it:

1. change sorting, filters, grouping, and a few presentation settings
2. reload the page and confirm they come back
3. clear the remembered state through your reset path
4. reload again and confirm the table falls back to defaults or saved-view precedence

Before you ship it, confirm that:

* the row is scoped by `tableKey`, `workspaceId`, and `userId`
* new writes use the persisted-state snapshot
* grouped expansion survives save and reload
* save failures surface somewhere useful
* deleting the record really resets the remembered state

<Callout title="Next">
  Use [Server saved views endpoint](/docs/guides/server-saved-views-endpoint) when users need named presets. If the online query layer is still missing, go back to [Server query endpoint](/docs/guides/server-query-endpoint).
</Callout>

For the persistence types behind this guide, see [TypeScript types](/docs/reference/typescript-types).


# Server query endpoint (https://react-datatable.com/docs/guides/server-query-endpoint)

<Callout title="Three-guide server flow">
  The full server-side query implementation is covered across three guides: [Endpoint](/docs/guides/server-query-endpoint), [Query Plan](/docs/guides/server-query-planning), and [Query Execution](/docs/guides/server-query-execution).
</Callout>

Use this guide when `online.query` should call your server instead of reading rows from the browser.

This page is about the endpoint boundary. It should authenticate, normalize input, choose the right execution path, and return `OnlineQueryResponse<TData>`. It should not hide planner or SQL complexity inside the route handler.

## Start with the request and response contract [#start-with-the-request-and-response-contract]

```ts
import type {
  OnlineQueryInput,
  OnlineQueryResponse,
  OnlineTableRow,
} from "react-datatable-server"
```

The endpoint receives table interaction state, not auth state:

* `mode`, `limit`, and `offset`
* `filters`, `sorting`, and `globalFilter`
* optional `grouping`

It returns backend-owned row output:

* `rows`
* `totalDataRows`
* `totalRenderedRows`
* `hasMore`
* optional `grouping`
* optional `facets`

`OnlineQueryInput` leaves `filterMode`, tenant scope, and permissions to the server so you can choose them in your own backend policy layer.

## Keep the route thin [#keep-the-route-thin]

A good route does five jobs in order:

1. authenticate and resolve workspace scope
2. parse `OnlineQueryInput`
3. normalize and plan the query
4. delegate execution by plan kind
5. serialize `OnlineQueryResponse<TData>`

```ts
import { NextRequest, NextResponse } from "next/server"
import type { OnlineQueryInput } from "react-datatable-server"
import { buildBackendQueryPlan, buildBackendQueryState } from "react-datatable-server"
import { orderServerColumns } from "@/server/datatable/order-columns"
import { executeOrderQuery } from "@/server/datatable/order-query-service"
import { requireWorkspaceAccess } from "@/server/auth"

export async function POST(request: NextRequest) {
  const session = await requireWorkspaceAccess(request)
  const input = (await request.json()) as OnlineQueryInput

  const query = buildBackendQueryState({
    filters: input.filters,
    sorting: input.sorting,
    globalFilter: input.globalFilter,
    filterMode: "AND",
    grouping: input.grouping,
  })

  const plan = buildBackendQueryPlan({
    navigationMode: input.mode,
    limit: input.limit,
    offset: input.offset,
    query,
    columns: orderServerColumns,
    tieBreakers: [
      { columnId: "createdAt", expression: { kind: "column", columnId: "created_at" } },
      { columnId: "id", expression: { kind: "column", columnId: "id" } },
    ],
  })

  const response = await executeOrderQuery({
    db: session.db,
    workspaceId: session.workspaceId,
    plan,
  })

  return NextResponse.json(response)
}
```

## Normalize first, then plan, then execute [#normalize-first-then-plan-then-execute]

Do not compile SQL directly from the raw request body.

`buildBackendQueryState()` gives you one stable backend query shape. `buildBackendQueryPlan()` validates that shape against your supported server columns. Only then should your execution layer touch Drizzle or SQL.

That separation matters because the same backend state model also powers:

* live online requests
* saved-view replay
* persisted-state replay
* grouped expansion restoration

## Split execution by plan kind [#split-execution-by-plan-kind]

Grouped requests need their own counting, ordering, row shaping, and continuity rules.

```ts
import type { BackendQueryPlan, OnlineQueryResponse } from "react-datatable-server"

export async function executeOrderQuery(args: {
  db: Database
  workspaceId: string
  plan: BackendQueryPlan
}): Promise<OnlineQueryResponse<OrderRow>> {
  if (args.plan.kind === "grouped_window") {
    return executeGroupedOrderQuery(args)
  }

  return executeFlatOrderQuery(args)
}
```

The next two guides cover those inner layers separately on purpose:

* [Server query planning](/docs/guides/server-query-planning)
* [Server query execution](/docs/guides/server-query-execution)

## Return the exact row shape the table expects [#return-the-exact-row-shape-the-table-expects]

Flat mode returns only data rows:

```ts
return {
  rows: pageRows.map((row) => ({
    type: "data",
    rowId: row.id,
    item: row,
    groupPath: [],
  })),
  totalDataRows,
  totalRenderedRows: totalDataRows,
  hasMore,
}
```

Grouped mode returns structural headers too:

```ts
return {
  rows: [
    {
      type: "group-header",
      groupId: "status:active",
      columnId: "status",
      value: "active",
      depth: 0,
      count: 42,
      groupPath: [],
    },
    {
      type: "data",
      rowId: order.id,
      item: order,
      groupPath: ["status:active"],
    },
  ],
  totalDataRows: 420,
  totalRenderedRows: 431,
  hasMore: true,
  grouping: {
    groups: {
      "status:active": {
        total: 42,
        renderedRowCount: 43,
      },
    },
  },
}
```

In grouped mode, `totalRenderedRows` includes headers and `grouping` describes the full grouped result across the dataset.

## Keep tenant scope outside the datatable request [#keep-tenant-scope-outside-the-datatable-request]

The client should control table interactions. The server should control data access.

Apply tenant, workspace, and permission scope before search, filters, and sorting run:

```ts
const baseWhere = eq(orders.workspaceId, workspaceId)
```

## Connect the endpoint to `online.query` [#connect-the-endpoint-to-onlinequery]

```ts
import type { OnlineQueryInput, OnlineQueryResponse } from "react-datatable-server"

async function queryOrders(input: OnlineQueryInput): Promise<OnlineQueryResponse<OrderRow>> {
  const res = await fetch("/api/orders/datatable-query", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(input),
  })

  if (!res.ok) {
    throw new Error("Failed to query orders")
  }

  return res.json()
}
```

This example uses `POST` so the table can send structured query input as JSON. React Query can still cache this response by `queryKey`, as the landing page demo does. Use `GET` instead if you need normal browser or CDN cache semantics.

## Verify the endpoint boundary before you move on [#verify-the-endpoint-boundary-before-you-move-on]

Before you call the endpoint done, confirm that:

* auth and workspace scope are server-owned
* raw input is normalized before planning
* flat and grouped plans go through different executors
* grouped responses include `grouping` and correct `totalRenderedRows`
* `facets` are returned when your filter UI depends on them
* the route handler stays thin enough that planner and SQL logic are testable outside HTTP

<Callout title="Next">
  Continue in order: [Server query planning](/docs/guides/server-query-planning), then [Server query execution](/docs/guides/server-query-execution). After that, move to [Server persisted state endpoint](/docs/guides/server-persisted-state-endpoint) if the next job is autosave.
</Callout>


# Server query execution (https://react-datatable.com/docs/guides/server-query-execution)

<Callout title="Three-guide server flow">
  The full server-side query implementation is covered across three guides: [Endpoint](/docs/guides/server-query-endpoint), [Query Plan](/docs/guides/server-query-planning), and [Query Execution](/docs/guides/server-query-execution).
</Callout>

Use this guide when `buildBackendQueryPlan()` is already returning the right plan and the remaining job is to execute it.

The right mental model is:

1. one shared execution setup
2. one split into two execution strategies
   * `flat_window`
   * `grouped_window`
3. one final `OnlineQueryResponse<TData>` contract

`OnlineQueryResponse<TData>` is the server payload the table reads after each request. It tells the table which rows to render, how many matching data rows exist, whether more rows can load, and, in grouped mode, what grouped structure those rows belong to.

## Plan the query [#plan-the-query]

Your backend should have one entrypoint that does three things before execution branches:

1. normalize request aliases
2. build the backend query plan
3. choose the execution strategy from `plan.kind`

```ts
function buildTableQueryPlan(input: OnlineQueryInput) {
  const query = buildBackendQueryState({
    filters: input.filters,
    sorting: input.sorting,
    globalFilter: input.globalFilter,
    filterMode: "AND",
    grouping: input.grouping,
  })

  return buildBackendQueryPlan({
    navigationMode: input.mode,
    limit: input.limit,
    offset: input.offset,
    query,
    columns: orderServerColumns,
    tieBreakers: [
      { columnId: "createdAt", expression: { kind: "column", columnId: "created_at" } },
      { columnId: "id", expression: { kind: "column", columnId: "id" } },
    ],
  })
}

export async function executeTableQuery(input: OnlineQueryInput) {
  const plan = buildTableQueryPlan(input)

  if (plan.kind === "grouped_window") {
    return executeGroupedQuery(plan)
  }

  return executeFlatQuery(plan)
}
```

In the showcase app, this same handoff lives in `site/src/db/showcase-online-query.ts` with showcase-specific helper names. The important part is the shape of the pipeline, not the demo app naming.

## Implement the flat query [#implement-the-flat-query]

Use the flat path when the planner returns `kind: "flat_window"`.

### 1. Compile planner output into real SQL conditions [#1-compile-planner-output-into-real-sql-conditions]

The flat executor needs two compiled pieces:

* `where`
* `orderBy`

That compilation step maps planner expressions onto your actual schema.

### 2. Fetch the requested window [#2-fetch-the-requested-window]

```ts
const compiled = compileFlatQueryPlan(plan)

return db
  .select()
  .from(orders)
  .where(compiled.where)
  .orderBy(...compiled.orderBy)
  .limit(plan.limit + 1)
  .offset(plan.offset)
```

The `limit + 1` read is there only to determine `hasMore` safely.

### 3. Count the full filtered result [#3-count-the-full-filtered-result]

The same executor runs a separate count query against the same filtered scope:

```ts
const [result] = await db
  .select({ value: count() })
  .from(orders)
  .where(compiled.where)
```

That produces `totalDataRows`.

### 4. Shape the final response [#4-shape-the-final-response]

The flat executor trims the overflow row, maps database rows into domain rows, and returns only data rows:

```ts
return {
  rows: visibleRows.map((item) => ({
    type: "data",
    rowId: item.id,
    item,
    groupPath: [],
  })),
  totalDataRows,
  totalRenderedRows: totalDataRows,
  hasMore,
}
```

That is the complete flat path:

* compile filters, search, and sorting
* fetch one ordered window
* count the filtered dataset
* return one flat `OnlineQueryResponse<TData>`

## Implement the grouped query [#implement-the-grouped-query]

Use the grouped path when the planner returns `kind: "grouped_window"`.

Grouped execution is still one server path, but it has extra responsibilities. The response must describe both the matching data rows and the grouped structure around them.

### 1. Reuse the filtered scope [#1-reuse-the-filtered-scope]

The grouped path starts from the same filtered dataset as the flat path.

```ts
function buildFilteredBaseCte(plan: GroupedWindowQueryPlan): SQL {
  const where = compileFilteredBaseWhere(plan)

  return sql`with filtered_base as (
    select *
    from ${orders}
    ${where ? sql`where ${where}` : sql``}
  )`
}
```

That keeps grouped counts and grouped rows tied to the same filtered dataset.

### 2. Build grouped summary queries [#2-build-grouped-summary-queries]

The grouped executor needs summary queries before it can shape the response.

```ts
const countQuery = ...
const topGroupsQuery = ...
const subgroupsQuery = ...
```

Those queries produce:

* `totalDataRows`
* group counts
* subgroup counts
* the data needed for `OnlineGroupingSummary`
* the data needed for `totalRenderedRows`

### 3. Handle `showEmptyGroups` [#3-handle-showemptygroups]

`showEmptyGroups` belongs in the grouped summary layer.

If it is `false`, return only groups that actually appear in the filtered dataset.

If it is `true`, the executor also needs a full domain for that grouped column so it can emit zero-count groups.

For example, a status column might use a known domain like this:

```ts
const statusDomain = ["active", "paused", "inactive"]
```

If your product needs empty groups for arbitrary SQL-backed dimensions, you need your own domain source for those values.

### 4. Fetch the grouped data window [#4-fetch-the-grouped-data-window]

The grouped path still needs a real row query.

```ts
return db
  .select()
  .from(orders)
  .where(compiled.where)
  .orderBy(...buildGroupedQueryOrderBy(plan))
  .limit(plan.limit)
  .offset(plan.offset)
```

That ordering is what keeps grouped infinite windows stable when a request starts in the middle of a group.

### 5. Shape group headers and data rows together [#5-shape-group-headers-and-data-rows-together]

Once the executor has both the page rows and the grouped summary, it builds the final render rows.

That output may include:

* top-level `group-header` rows
* subgroup `group-header` rows
* `data` rows with the right `groupPath`

So grouped execution is not just “fetch rows and let the client add headers later.” The server already has to return grouped render structure.

### 6. Return the grouped response [#6-return-the-grouped-response]

```ts
return {
  rows: buildGroupedRows(plan, items, summary),
  totalDataRows: summary.totalDataRows,
  totalRenderedRows: summary.totalRenderedRows,
  hasMore: plan.offset + plan.limit < summary.totalDataRows,
  grouping: summary.grouping,
}
```

That is the complete grouped path:

* reuse the filtered scope
* compute group summaries
* apply `showEmptyGroups` in the summary layer
* fetch the ordered data window
* build group headers plus data rows
* return grouped totals and grouping metadata

### 7. Add facet counts to the response [#7-add-facet-counts-to-the-response]

`facets` are not a separate execution mode. They are extra response data.

If your table shows backend-aware filter counts, compute them from the same filtered scope and attach them to the final response.

For example, if your filter UI needs status counts, run a grouped aggregate against the same filtered base query:

```ts
async function buildFacets(plan: FlatWindowQueryPlan | GroupedWindowQueryPlan) {
  const where = compileFilteredBaseWhere(plan)

  const statusFacetRows = await db
    .select({
      value: orders.status,
      count: count(),
    })
    .from(orders)
    .where(where)
    .groupBy(orders.status)
    .orderBy(orders.status)

  return {
    status: statusFacetRows.map((row) => ({
      value: row.value,
      count: row.count,
    })),
  }
}
```

Then attach those facet counts to the same response that returns rows:

```ts
const facets = await buildFacets(plan)

return {
  rows,
  totalDataRows,
  totalRenderedRows,
  hasMore,
  grouping,
  facets,
}
```

The important rule is simple: facets must be computed from the same tenant scope and filtered dataset as the rows you returned.

## Why grouped queries need a separate executor [#why-grouped-queries-need-a-separate-executor]

The codebase has one canonical pipeline, but two executor implementations because the contracts differ:

* flat mode returns only ordered data rows plus a count
* grouped mode returns ordered data rows, structural headers, grouped totals, and rendered-row counts

So the split is not architectural drift. It exists because `flat_window` and `grouped_window` need different query and response-shaping logic.

In the showcase app, those responsibilities currently live in files such as:

* `site/src/db/showcase-flat-executor.ts`
* `site/src/db/showcase-grouped-summary.ts`
* `site/src/db/showcase-grouped-executor.ts`
* `site/src/db/showcase-online-query.ts`

## Verify the production path [#verify-the-production-path]

Before you call execution done, confirm that your backend can:

* compile planner expressions into real schema expressions
* keep ordering deterministic with tie-breakers
* count the same filtered scope it renders
* return `totalRenderedRows` correctly in grouped mode
* implement `showEmptyGroups` from a real domain source when needed
* compute `facets` from the same scoped dataset when the UI needs them

<Callout title="Next">
  If the next job is restoring state, continue to [Server persisted state endpoint](/docs/guides/server-persisted-state-endpoint). If the request or planner layer is still incomplete, go back to [Server query endpoint](/docs/guides/server-query-endpoint) and [Server query planning](/docs/guides/server-query-planning).
</Callout>


# Server query planning (https://react-datatable.com/docs/guides/server-query-planning)

<Callout title="Three-guide server flow">
  The full server-side query implementation is covered across three guides: [Endpoint](/docs/guides/server-query-endpoint), [Query Plan](/docs/guides/server-query-planning), and [Query Execution](/docs/guides/server-query-execution).
</Callout>

Use this guide when your endpoint is wired up and the next job is turning raw `OnlineQueryInput` state into a safe backend plan.

This page stops at the planner output. It explains `buildBackendQueryState()` and `buildBackendQueryPlan()`. It does *not* cover the Drizzle execution layer; that lives in [Server query execution](/docs/guides/server-query-execution).

## Plan the query [#plan-the-query]

The planner helpers split the request into two stages:

1. `buildBackendQueryState()` normalizes raw table state into one backend-friendly shape.
2. `buildBackendQueryPlan()` validates that shape against your server column map and returns either a flat plan or a grouped plan.

That split is the seam between UI state and backend execution.

## Step 1: Normalize the request with `buildBackendQueryState()` [#step-1-normalize-the-request-with-buildbackendquerystate]

```ts
import { buildBackendQueryState } from "react-datatable-server"

const query = buildBackendQueryState({
  filters: input.filters,
  sorting: input.sorting,
  globalFilter: input.globalFilter,
  filterMode: "AND",
  grouping: input.grouping,
})
```

The returned `BackendQueryState` does four important cleanup jobs:

* keeps filters as one typed list
* preserves sorting in request order
* trims and deduplicates grouping columns
* normalizes grouped expansion state into a stable shape

That matters because saved views, persisted state, and live requests should all converge on the same backend query model.

### Grouping columns are trimmed and deduplicated [#grouping-columns-are-trimmed-and-deduplicated]

```ts
export function normalizeGroupingColumns(columns: string[]): string[] {
  const seen = new Set<string>()
  const normalized: string[] = []

  for (const column of columns) {
    const trimmed = column.trim()
    if (!trimmed || seen.has(trimmed)) {
      continue
    }

    seen.add(trimmed)
    normalized.push(trimmed)
  }

  return normalized
}
```

So noisy input like this:

```ts
["status", " plan ", "status", ""]
```

becomes this:

```ts
["status", "plan"]
```

### Group expansion becomes one stable override model [#group-expansion-becomes-one-stable-override-model]

```ts
{
  defaultExpanded: true,
  overrides: {
    "status:inactive": false,
  },
}
```

That shape is what later grouped execution uses when it decides which groups emit only headers and which emit nested data rows.

## Step 2: Define which server columns support which operations [#step-2-define-which-server-columns-support-which-operations]

`buildBackendQueryPlan()` can only validate the request if you declare what the backend actually supports.

That is the job of `defineServerColumns()`.

```ts
import { defineServerColumns } from "react-datatable-server"

export const orderServerColumns = defineServerColumns({
  company: {
    id: "company",
    filter: {
      type: "text",
      expression: { kind: "column", columnId: "company" },
    },
    search: {
      expression: { kind: "column", columnId: "company" },
    },
    sort: {
      expression: { kind: "column", columnId: "company" },
    },
    group: {
      keyExpression: { kind: "column", columnId: "company" },
      orderExpressions: [{ kind: "column", columnId: "company" }],
    },
  },
  renewal: {
    id: "renewal",
    filter: {
      type: "date",
      expression: { kind: "derived", key: "renewalDate" },
    },
    sort: {
      expression: { kind: "derived", key: "renewalDate" },
    },
  },
})
```

Each column definition declares which planner operations are valid:

* `filter`
* `search`
* `sort`
* `group`

If a column omits one of those sections, that operation is unsupported for that column.

## Step 3: Build the validated plan with `buildBackendQueryPlan()` [#step-3-build-the-validated-plan-with-buildbackendqueryplan]

```ts
import { buildBackendQueryPlan } from "react-datatable-server"

const plan = buildBackendQueryPlan({
  navigationMode: input.mode,
  limit: input.limit,
  offset: input.offset,
  query,
  columns: orderServerColumns,
  tieBreakers: [
    { columnId: "createdAt", expression: { kind: "column", columnId: "created_at" } },
    { columnId: "id", expression: { kind: "column", columnId: "id" } },
  ],
})
```

The planner compiles four major concerns before execution starts:

* `compileFilters()`
* `compileGlobalSearch()`
* `compileSorting()`
* `compileGrouping()` when grouping is active

This is the point where table-owned state becomes a backend-owned execution contract.

## What the planner validates [#what-the-planner-validates]

### Window validation [#window-validation]

The planner rejects invalid windows before the query layer runs:

```ts
if (!Number.isInteger(limit) || limit <= 0) {
  throw new QueryPlannerValidationError("Query limit must be a positive integer.")
}

if (!Number.isInteger(offset) || offset < 0) {
  throw new QueryPlannerValidationError("Query offset must be a non-negative integer.")
}
```

### Filter validation [#filter-validation]

Each compiled filter becomes a `QueryPlanFilter` entry with:

* `columnId`
* the validated filter payload
* the backend `expression` that execution should compile

If the frontend sends a filter type that the backend did not declare, the planner fails early instead of producing half-valid SQL.

### Search validation [#search-validation]

`compileGlobalSearch()` trims the term and gathers only columns that actually expose a `search` expression.

If the request asks for search but your backend exposes no searchable columns, the planner throws instead of pretending search worked.

### Sorting validation and tie-breakers [#sorting-validation-and-tie-breakers]

`compileSorting()` validates each requested sort and then appends deterministic backend tie-breakers without duplicating an already-used expression.

That is what keeps infinite windows stable when multiple rows share the same user-visible sort key.

### Grouping validation [#grouping-validation]

`compileGrouping()` checks that:

* grouping columns are unique
* each requested grouping column is actually groupable
* each grouped column exposes both a key expression and group ordering expressions

A grouped plan should either be valid or fail clearly. It should not degrade into a half-grouped response.

## What the planner returns [#what-the-planner-returns]

The planner returns one of two executable contracts.

### Flat plan [#flat-plan]

```ts
{
  kind: "flat_window",
  navigationMode: "pagination" | "infinite",
  limit,
  offset,
  filters,
  filterMode,
  sorting,
  globalSearch,
}
```

### Grouped plan [#grouped-plan]

```ts
{
  kind: "grouped_window",
  navigationMode: "pagination" | "infinite",
  limit,
  offset,
  filters,
  filterMode,
  sorting,
  globalSearch,
  grouping: {
    columns: [
      {
        columnId: "status",
        keyExpression: { kind: "column", columnId: "status" },
        orderExpressions: [{ kind: "column", columnId: "status" }],
      },
    ],
    showEmptyGroups: false,
    expansion: {
      defaultExpanded: true,
      overrides: {},
    },
  },
}
```

The grouped plan carries the exact grouping metadata that the executor must honor later.

## What this page does *not* do [#what-this-page-does-not-do]

The planner does not:

* fetch a flat page from the database
* count grouped summaries
* decide how `showEmptyGroups` becomes rendered group headers
* insert loading rows for virtual scrolling
* emit `OnlineQueryResponse<TData>`

Those are execution concerns.

In the example app, they live in separate execution modules. In the showcase app, those files are:

* `site/src/db/showcase-flat-executor.ts`
* `site/src/db/showcase-grouped-summary.ts`
* `site/src/db/showcase-grouped-executor.ts`
* `site/src/db/showcase-online-query.ts`

## Verify planning before moving on [#verify-planning-before-moving-on]

Before you call the planning layer done, confirm that:

* invalid `limit` and `offset` values fail clearly
* unsupported filter columns fail clearly
* filter type mismatches fail clearly
* search only uses declared search expressions
* sorting appends deterministic tie-breakers
* unsupported grouping columns fail clearly
* grouped requests preserve expansion state in the returned plan

Then continue to [Server query execution](/docs/guides/server-query-execution), where the real Drizzle and grouped-row complexity starts.

<Callout title="Next">
  Continue to [Server query execution](/docs/guides/server-query-execution) once your planner returns the right `flat_window` and `grouped_window` shapes. If the route contract is still unclear, go back to [Server query endpoint](/docs/guides/server-query-endpoint).
</Callout>


# Server saved views endpoint (https://react-datatable.com/docs/guides/server-saved-views-endpoint)

Use this guide when users need named table presets they can create on purpose, reopen later, and optionally share with a workspace.

This page is about saved views. If you only need automatic last-state restore for one user, use [Server persisted state endpoint](/docs/guides/server-persisted-state-endpoint).

## Start with the saved view model [#start-with-the-saved-view-model]

A saved view is more than a state blob.

It combines:

* a durable table-state payload
* a name
* scope metadata
* sharing metadata
* default flags

The saved view payload itself is `DatatableView["state"]`.

```ts
import {
  buildDatatableViewState,
  replaySavedViewState,
} from "react-datatable-server"
```

The stored state shape is:

```ts
interface DatatableViewState {
  version: 1
  query: {
    filters: ColumnFilter[]
    sorting: SortingState
    globalFilter: string
    grouping: {
      columns: string[]
      showEmptyGroups: boolean
      expansion: {
        defaultExpanded: boolean
        overrides: Record<string, boolean>
      }
    } | null
    filterMode: "AND" | "OR"
  }
  presentation: {
    showColumnHeaders: boolean
    stickyColumnsCount: number
    showHorizontalLines: boolean
    showVerticalLines: boolean
    showOrderingBadge: boolean
    columnOrder: string[]
    columnVisibility: Record<string, boolean>
    columnWidths: Record<string, number>
    activeViewId: string | null
  }
}
```

That keeps saved views aligned with the same query and presentation model used by live requests and current-view persistence.

For the surrounding saved-view contracts, see [TypeScript types](/docs/reference/typescript-types).

## Create the Postgres table with Drizzle [#create-the-postgres-table-with-drizzle]

A straightforward schema keeps the view metadata and the saved state together.

A saved-view row needs two kinds of fields:

* identity and sharing metadata such as `id`, `name`, `isShared`, and default flags
* the saved-view state payload in `snapshot`

```ts
import { boolean, jsonb, pgTable, text, timestamp, uniqueIndex } from "drizzle-orm/pg-core"
import type { DatatableView } from "react-datatable/persistence"

export const datatableViews = pgTable(
  "datatable_views",
  {
    id: text("id").primaryKey(),
    tableKey: text("table_key").notNull(),
    workspaceId: text("workspace_id").notNull(),
    ownerUserId: text("owner_user_id").notNull(),
    name: text("name").notNull(),
    isShared: boolean("is_shared").notNull().default(false),
    isUserDefault: boolean("is_user_default").notNull().default(false),
    isWorkspaceDefault: boolean("is_workspace_default").notNull().default(false),
    snapshot: jsonb("snapshot").$type<DatatableView["state"]>().notNull(),
    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
  },
  (table) => ({
    scopeIdx: uniqueIndex("datatable_views_scope_idx").on(
      table.tableKey,
      table.workspaceId,
      table.ownerUserId,
      table.name
    ),
  })
)
```

This schema works well when:

* private views belong to one user
* shared views stay inside one workspace
* defaults are stored on the view row itself

If your product needs richer ACLs, split sharing into a separate table.

## Define the API surface first [#define-the-api-surface-first]

A backend saved-views adapter usually needs these actions:

* `list`
* `get`
* `create`
* `update`
* `delete`
* `share`
* `setUserDefault`
* `setWorkspaceDefault`

That is the product surface the UI expects.

A minimum `DatatableView` payload returned from your backend should look like this:

```ts
{
  id: "view_123",
  name: "Open enterprise deals",
  state: {
    version: 1,
    query: { ... },
    presentation: { ... },
  },
  isShared: true,
  isUserDefault: false,
  isWorkspaceDefault: true,
  createdBy: "user_123",
  createdAt: new Date(),
  updatedAt: new Date(),
  workspaceId: "ws_123",
}
```

If your response omits those fields, the built-in views UI will not have enough information to render ownership, sharing, or default state correctly.

## Add a small store module [#add-a-small-store-module]

Keep the SQL behind one service layer.

```ts
import { and, asc, eq, or } from "drizzle-orm"
import { datatableViews } from "@/db/schema"

export async function listDatatableViews(args: {
  db: Database
  tableKey: string
  workspaceId: string
  userId: string
}) {
  return args.db.query.datatableViews.findMany({
    where: and(
      eq(datatableViews.tableKey, args.tableKey),
      eq(datatableViews.workspaceId, args.workspaceId),
      or(
        eq(datatableViews.ownerUserId, args.userId),
        eq(datatableViews.isShared, true)
      )
    ),
    orderBy: [asc(datatableViews.name)],
  })
}
```

For `create()` and `update()`, build the saved-view state payload with `buildDatatableViewState()` before it hits the database.

## Add the list and get endpoints [#add-the-list-and-get-endpoints]

These two endpoints load the available views and one specific view.

```ts
import { NextRequest, NextResponse } from "next/server"
import { getDatatableView, listDatatableViews } from "@/server/datatable/view-store"
import { requireWorkspaceAccess } from "@/server/auth"

export async function GET(request: NextRequest) {
  const session = await requireWorkspaceAccess(request)
  const tableKey = request.nextUrl.searchParams.get("tableKey")
  const viewId = request.nextUrl.searchParams.get("viewId")

  if (!tableKey) {
    return NextResponse.json({ error: "tableKey is required" }, { status: 400 })
  }

  if (viewId) {
    const view = await getDatatableView({
      db: session.db,
      viewId,
      tableKey,
      workspaceId: session.workspaceId,
      userId: session.userId,
    })

    if (!view) {
      return NextResponse.json({ error: "Not found" }, { status: 404 })
    }

    return NextResponse.json(view)
  }

  const views = await listDatatableViews({
    db: session.db,
    tableKey,
    workspaceId: session.workspaceId,
    userId: session.userId,
  })

  return NextResponse.json(views)
}
```

## Add the create and update endpoints [#add-the-create-and-update-endpoints]

Create and update should be explicit about the saved state they persist.

```ts
import { NextRequest, NextResponse } from "next/server"
import { createId } from "@paralleldrive/cuid2"
import { buildDatatableViewState } from "react-datatable-server"
import type { DatatableView } from "react-datatable/persistence"
import { createDatatableView, updateDatatableView } from "@/server/datatable/view-store"
import { requireWorkspaceAccess } from "@/server/auth"

export async function POST(request: NextRequest) {
  const session = await requireWorkspaceAccess(request)
  const body = (await request.json()) as {
    tableKey: string
    view: DatatableView
  }

  const created = await createDatatableView({
    db: session.db,
    id: createId(),
    tableKey: body.tableKey,
    workspaceId: session.workspaceId,
    ownerUserId: session.userId,
    name: body.view.name,
    isShared: false,
    snapshot: buildDatatableViewState(body.view.state),
  })

  return NextResponse.json(created)
}

export async function PATCH(request: NextRequest) {
  const session = await requireWorkspaceAccess(request)
  const body = (await request.json()) as {
    tableKey: string
    viewId: string
    updates: Partial<DatatableView>
  }

  const updated = await updateDatatableView({
    db: session.db,
    tableKey: body.tableKey,
    workspaceId: session.workspaceId,
    userId: session.userId,
    viewId: body.viewId,
    updates: {
      ...body.updates,
      state: body.updates.state
        ? buildDatatableViewState(body.updates.state)
        : undefined,
    },
  })

  return NextResponse.json(updated)
}
```

## Add delete, share, and default endpoints [#add-delete-share-and-default-endpoints]

Saved views need a few lifecycle actions beyond CRUD.

### Delete [#delete]

Allow the owner to delete a private view or an unshared view they control.

```ts
export async function DELETE(request: NextRequest, { params }: { params: { viewId: string } }) {
  const session = await requireWorkspaceAccess(request)
  const body = (await request.json()) as { tableKey: string }

  await deleteDatatableView({
    db: session.db,
    tableKey: body.tableKey,
    workspaceId: session.workspaceId,
    userId: session.userId,
    viewId: params.viewId,
  })

  return NextResponse.json({ ok: true })
}
```

### Share [#share]

Turn `isShared` on through a dedicated endpoint instead of treating it like a silent field toggle. Sharing changes who can see the view.

```ts
export async function POST(request: NextRequest, { params }: { params: { viewId: string } }) {
  const session = await requireWorkspaceAccess(request)
  const body = (await request.json()) as { tableKey: string }

  const shared = await shareDatatableView({
    db: session.db,
    tableKey: body.tableKey,
    workspaceId: session.workspaceId,
    userId: session.userId,
    viewId: params.viewId,
  })

  return NextResponse.json(shared)
}
```

### Set defaults [#set-defaults]

A practical pattern is:

* `PUT /api/datatable-views/defaults/user`
* `PUT /api/datatable-views/defaults/workspace`

When one view becomes the new default, clear the old default inside the same scope.

```ts
export async function PUT(request: NextRequest) {
  const session = await requireWorkspaceAccess(request)
  const body = (await request.json()) as {
    tableKey: string
    viewId: string
  }

  await setUserDefaultDatatableView({
    db: session.db,
    tableKey: body.tableKey,
    workspaceId: session.workspaceId,
    userId: session.userId,
    viewId: body.viewId,
  })

  return NextResponse.json({ ok: true })
}
```

## Wire the frontend saved-views adapter [#wire-the-frontend-saved-views-adapter]

Once the endpoints exist, connect them through `DatatableViewAdapter`.

The adapter contract is more than plain CRUD:

* `list()` returns every view the current user can access
* `get()` returns one hydrated `DatatableView`
* `create()` and `update()` send the saved-view state payload
* `share()` and the default setters expose the extra UI actions

```ts
import type { DatatableView, DatatableViewAdapter } from "react-datatable/persistence"
import { buildDatatableViewState, replaySavedViewState } from "react-datatable-server"

export const datatableViewServerAdapter: DatatableViewAdapter = {
  async list(config) {
    const url = new URL("/api/datatable-views", window.location.origin)
    url.searchParams.set("tableKey", config.tableKey)

    const res = await fetch(url)
    if (!res.ok) throw new Error("Failed to list views")

    const views = (await res.json()) as DatatableView[]
    return views.map((view) => ({
      ...view,
      state: replaySavedViewState(view.state),
    }))
  },

  async get(config, viewId) {
    const url = new URL("/api/datatable-views", window.location.origin)
    url.searchParams.set("tableKey", config.tableKey)
    url.searchParams.set("viewId", viewId)

    const res = await fetch(url)
    if (res.status === 404) return null
    if (!res.ok) throw new Error("Failed to load view")

    const view = (await res.json()) as DatatableView
    return {
      ...view,
      state: replaySavedViewState(view.state),
    }
  },

  async create(config, view) {
    const res = await fetch("/api/datatable-views", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        tableKey: config.tableKey,
        view: {
          ...view,
          state: buildDatatableViewState(view.state),
        },
      }),
    })

    if (!res.ok) throw new Error("Failed to create view")
    return res.json()
  },

  async update(config, viewId, updates) {
    const res = await fetch("/api/datatable-views", {
      method: "PATCH",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        tableKey: config.tableKey,
        viewId,
        updates,
      }),
    })

    if (!res.ok) throw new Error("Failed to update view")
    return res.json()
  },

  async delete(config, viewId) {
    const res = await fetch(`/api/datatable-views/${viewId}`, {
      method: "DELETE",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ tableKey: config.tableKey }),
    })

    if (!res.ok) throw new Error("Failed to delete view")
  },

  async share(config, viewId) {
    const res = await fetch(`/api/datatable-views/${viewId}/share`, {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ tableKey: config.tableKey }),
    })

    if (!res.ok) throw new Error("Failed to share view")
    return res.json()
  },

  async setUserDefault(config, viewId) {
    const res = await fetch("/api/datatable-views/defaults/user", {
      method: "PUT",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ tableKey: config.tableKey, viewId }),
    })

    if (!res.ok) throw new Error("Failed to set user default")
  },

  async setWorkspaceDefault(config, viewId) {
    const res = await fetch("/api/datatable-views/defaults/workspace", {
      method: "PUT",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({ tableKey: config.tableKey, viewId }),
    })

    if (!res.ok) throw new Error("Failed to set workspace default")
  },
}
```

## Connect it to `Datatable` [#connect-it-to-datatable]

```tsx
<Datatable
  tableKey="customers"
  columns={columns}
  data={rows}
  getRowId={(row) => row.id}
  views={{
    adapter: datatableViewServerAdapter,
  }}
  toolbar={{
    views: true,
    filterButton: true,
    quickSearch: true,
    displayOptions: true,
  }}
/>
```

## Keep saved views aligned with backend capabilities [#keep-saved-views-aligned-with-backend-capabilities]

Saved views should not keep requesting states the backend can no longer run.

When columns are removed or renamed:

* migrate existing saved-view payloads if possible
* reject stale filters or grouping clearly if not
* keep `supportedGroupingColumns` aligned with the backend query builder

That matters even more when views store grouped expansion state.

## Verify the saved views endpoint before you move on [#verify-the-saved-views-endpoint-before-you-move-on]

Run one end-to-end view flow before you ship it:

1. save a new named view
2. reload and confirm it appears in the views UI
3. load it and confirm filters, grouping, and presentation state replay correctly
4. set it as a user or workspace default
5. reload again and confirm default precedence works

Before you ship it, confirm that:

* new writes use the direct saved-view state payload
* private and shared views respect workspace scope
* user-default and workspace-default actions clear older defaults in the same scope
* the adapter replays saved state correctly after load
* the UI only exposes sharing or default actions your adapter actually supports
* stale view payloads fail clearly instead of producing partial behavior

<Callout title="Next">
  Go to [Server persisted state endpoint](/docs/guides/server-persisted-state-endpoint) if you still need autosave. If the online backend path is still incomplete, start with [Server query endpoint](/docs/guides/server-query-endpoint).
</Callout>

For the persistence and saved-view contracts behind this guide, see [TypeScript types](/docs/reference/typescript-types).


# Tune virtualization (https://react-datatable.com/docs/guides/tune-virtualization)

Use this guide when the table already behaves correctly but starts to feel heavy once more rows or columns are on screen.

Virtualization is about render cost, not query semantics. It changes how much of the already-loaded table React mounts at once.

<ImageZoom src="/docs-media/guides/tune-virtualization-placeholder.png" alt="A dark data table with virtualization enabled, one active status filter, and a compact table showing company health rows." className="my-7 w-full rounded-xs border-0" />

## Full vs viewport rendering [#full-vs-viewport-rendering]

Use `virtualization.mode: "full"` when the loaded dataset is bounded and mounting every loaded row is still cheap enough.

Use `virtualization.mode: "viewport"` when users scroll through enough loaded rows or visible columns that full mounting starts to hurt interaction quality.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  virtualization={{ mode: "viewport" }}
/>
```

Typical signals that `viewport` is the better fit:

* large local datasets
* wide tables with many visible columns
* dense product surfaces where people scroll constantly
* infinite online tables with big loaded windows

## Rendering mode vs data mode [#rendering-mode-vs-data-mode]

`virtualization` controls render cost, while local versus online mode controls data ownership.

* local versus online mode decides who owns filtering, sorting, pagination, and grouping
* virtualization decides how much of the loaded table is mounted in the DOM

That means `online.mode: "infinite"` and `virtualization.mode: "viewport"` often appear together, but they solve different problems.

If you are still deciding how rows should be fetched, go back to [Choose a data mode](/docs/guides/choose-a-data-mode).

## Infinite-mode constraint [#infinite-mode-constraint]

The current grid forces infinite online tables to render in viewport mode, even if you request `full`.

That is intentional. Infinite scrolling only stays practical when the loaded window is still rendered through the viewport engine.

So treat `full` as an option for:

* bounded local tables
* bounded pagination results
* debugging parity against viewport mode

Not for large free-scrolling infinite tables.

## Row and header heights [#row-and-header-heights]

The viewport engine relies on predictable heights.

The copied source defaults both `rowHeight` and `headerHeight` to `48`, with grouped headers using their own `44` pixel height unless you change the display model.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  rowHeight={44}
  headerHeight={44}
  virtualization={{ mode: "viewport" }}
/>
```

When you tighten density:

* update both row and header heights together unless you intentionally want a mixed density
* test grouped tables separately
* watch custom cells for wrapped text that breaks the assumed height

If rows need lots of variable-height detail, move that detail into preview panels or routes instead of fighting the viewport model.

## Overscan [#overscan]

Overscan mounts extra rows and columns just outside the viewport so fast scrolling does not reveal blank gaps.

```tsx
<Datatable
  tableKey="customers"
  data={customers}
  columns={columns}
  getRowId={(row) => row.id}
  virtualization={{
    mode: "viewport",
    rowOverscanCount: 12,
    columnOverscanCount: 2,
  }}
/>
```

Start with the built-in defaults first.

The current grid already scales overscan from the visible viewport and floors it at a practical minimum, so manual tuning is usually only necessary when:

* you can reproduce visible blanking during fast scroll
* wide sticky-column layouts need a little more horizontal cushion
* a very dense table is doing too much offscreen work

Raise overscan when scrolling reveals gaps. Lower it only when you have evidence that offscreen rendering is contributing meaningfully to sluggishness.

## Extra verification cases [#extra-verification-cases]

Virtualization interacts with presentation choices.

Before you call the table done, test:

* sticky columns on and off
* grouped and ungrouped row models
* custom cells with long text or badges
* preview, selection, and keyboard navigation in the same table

Those combinations are where misaligned heights or overly optimistic density choices usually show up.

## Use full mode to debug [#use-full-mode-to-debug]

If scrolling feels wrong, switching temporarily to `full` can help you isolate the problem.

If the issue disappears in `full` mode, the likely causes are:

* incorrect row or header heights
* wrapped content producing dynamic heights
* overscan that is too low for the scroll speed
* custom styling that fights sticky columns or row layout

If the issue remains in `full` mode too, the problem is probably not virtualization.

## Verify production behavior [#verify-production-behavior]

Before you move on, confirm that:

* scroll performance is acceptable with realistic data volume
* sticky columns stay aligned while scrolling
* grouped rows still look correct at the chosen density
* custom cells do not create accidental dynamic row heights
* infinite tables still feel smooth while data loads ahead of the viewport


# Astro (https://react-datatable.com/docs/installation/astro)

Use this path for Astro apps that render React islands.

<Steps>
  <Step>
    ### Create or open an Astro app [#create-or-open-an-astro-app]

    If you need a new app, create one with Tailwind CSS and React:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm create astro@latest my-app -- --template with-tailwindcss --install --add react --git
cd my-app`,
  npm: `npm create astro@latest my-app -- --template with-tailwindcss --install --add react --git
cd my-app`,
  yarn: `yarn create astro my-app --template with-tailwindcss --install --add react --git
cd my-app`,
  bun: `bun create astro@latest my-app -- --template with-tailwindcss --install --add react --git
cd my-app`,
}"
    />

    If the generated Tailwind setup pulls Vite 8 and `npm run build` fails inside `@tailwindcss/vite`, pin Vite to the current 7.x range:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm add -D vite@^7.3.3`,
  npm: `npm install -D vite@^7.3.3`,
  yarn: `yarn add -D vite@^7.3.3`,
  bun: `bun add --dev vite@^7.3.3`,
}"
    />
  </Step>

  <Step>
    ### Confirm aliases [#confirm-aliases]

    Make sure `tsconfig.json` resolves `@/*` to `src/*`:

    ```json
    {
      "compilerOptions": {
        "baseUrl": ".",
        "paths": {
          "@/*": ["./src/*"]
        }
      }
    }
    ```
  </Step>

  <Step>
    ### Install react-datatable [#install-react-datatable]

    Run the installer from the app root:

    ```bash
npx @react-datatable/cli install --token <license-token> --framework astro
```

    The default target is `src/react-datatable`.
  </Step>

  <Step>
    ### Render it as a React island [#render-it-as-a-react-island]

    Create a React component:

    ```tsx
    import { Datatable, type DatatableColumn } from "@/react-datatable"

    type Customer = { id: string; company: string }

    const columns: DatatableColumn<Customer>[] = [
      { id: "company", accessorKey: "company", header: "Company", filterType: "text" },
    ]

    export function CustomersTable() {
      return <Datatable tableKey="customers" columns={columns} data={[]} getRowId={(row) => row.id} />
    }
    ```

    Use it from an Astro page:

    ```astro
    ---
    import { CustomersTable } from "@/components/CustomersTable"
    ---

    <CustomersTable client:load />
    ```
  </Step>

  <Step>
    ### Verify the app [#verify-the-app]

    Run:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm run build`,
  npm: `npm run build`,
  yarn: `yarn build`,
  bun: `bun run build`,
}"
    />
  </Step>
</Steps>


# Installation (https://react-datatable.com/docs/installation)

Choose the setup that matches your app. Every path installs the same owned source into your repository and keeps data fetching provider-free by default.

Use the installer when you have a license token:

```bash
npx @react-datatable/cli install --token <license-token>
```

The installer validates the token, copies the table source, installs the core runtime dependencies, and adds a Tailwind `@source` directive when it can safely detect a Tailwind CSS entry file.

| Framework | Installation guide |
| --- | --- |
| Next.js | [Next.js](/docs/installation/next) |
| Vite | [Vite](/docs/installation/vite) |
| TanStack Start | [TanStack Start](/docs/installation/tanstack-start) |
| React Router | [React Router](/docs/installation/react-router) |
| Astro | [Astro](/docs/installation/astro) |
| Laravel | [Laravel](/docs/installation/laravel) |
| Manual | [Manual](/docs/installation/manual) |

For custom stacks, use [Manual](/docs/installation/manual). For a first table after installation, continue to [Getting started](/docs/quickstart/getting-started).


# Laravel (https://react-datatable.com/docs/installation/laravel)

Use this path for Laravel apps with Vite, React, TypeScript, and Tailwind CSS.

<Steps>
  <Step>
    ### Create or open a Laravel app [#create-or-open-a-laravel-app]

    If you need a new Laravel app, create it first:

    ```bash
    laravel new my-app
    cd my-app
    ```

    Then add the frontend stack you use for React. The important pieces for react-datatable are Vite, React, TypeScript, Tailwind CSS, and a browser entry under `resources/js`.
  </Step>

  <Step>
    ### Confirm the CSS entry [#confirm-the-css-entry]

    Laravel Vite apps usually load Tailwind from `resources/css/app.css`:

    ```css
    @import "tailwindcss";
    ```
  </Step>

  <Step>
    ### Install react-datatable [#install-react-datatable]

    Install the source under `resources/js`:

    ```bash
npx @react-datatable/cli install --token <license-token> --framework laravel --target resources/js/react-datatable
```
  </Step>

  <Step>
    ### Import from Laravel React code [#import-from-laravel-react-code]

    ```tsx
    import { Datatable, type DatatableColumn } from "./react-datatable"

    type Customer = { id: string; company: string }

    const columns: DatatableColumn<Customer>[] = [
      { id: "company", accessorKey: "company", header: "Company", filterType: "text" },
    ]

    export function CustomersTable({ rows }: { rows: Customer[] }) {
      return <Datatable tableKey="customers" columns={columns} data={rows} getRowId={(row) => row.id} />
    }
    ```
  </Step>

  <Step>
    ### Verify the frontend build [#verify-the-frontend-build]

    Run the Vite build command from the Laravel app root:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm run build`,
  npm: `npm run build`,
  yarn: `yarn build`,
  bun: `bun run build`,
}"
    />
  </Step>
</Steps>


# Manual (https://react-datatable.com/docs/installation/manual)

Use this path when your app is not one of the named framework setups.

<Steps>
  <Step>
    ### Confirm the requirements [#confirm-the-requirements]

    Your app needs React, TypeScript, Tailwind CSS 4, and a CSS file that imports Tailwind:

    ```css
    @import "tailwindcss";
    ```
  </Step>

  <Step>
    ### Choose a source target [#choose-a-source-target]

    Pick the directory where copied source should live. Common choices are:

    ```txt
    src/react-datatable
    app/react-datatable
    resources/js/react-datatable
    ```
  </Step>

  <Step>
    ### Run the installer [#run-the-installer]

    Pass the target explicitly:

    ```bash
npx @react-datatable/cli install --token <license-token> --framework manual --target src/react-datatable
```

    Use `--no-install` when you want to copy source first and install dependencies yourself.
  </Step>

  <Step>
    ### Add Tailwind source scanning [#add-tailwind-source-scanning]

    If the installer cannot detect your Tailwind entry file, add this to your global CSS manually:

    ```css
    @source "./react-datatable";
    ```

    Adjust the path relative to the CSS file.
  </Step>

  <Step>
    ### Install core dependencies manually [#install-core-dependencies-manually]

    If you used `--no-install`, install the runtime dependencies:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm add @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities @phosphor-icons/react @radix-ui/react-alert-dialog @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-popover @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tooltip @tanstack/react-table class-variance-authority clsx cmdk date-fns react-day-picker tailwind-merge zod zustand`,
  npm: `npm install @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities @phosphor-icons/react @radix-ui/react-alert-dialog @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-popover @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tooltip @tanstack/react-table class-variance-authority clsx cmdk date-fns react-day-picker tailwind-merge zod zustand`,
  yarn: `yarn add @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities @phosphor-icons/react @radix-ui/react-alert-dialog @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-popover @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tooltip @tanstack/react-table class-variance-authority clsx cmdk date-fns react-day-picker tailwind-merge zod zustand`,
  bun: `bun add @dnd-kit/core @dnd-kit/modifiers @dnd-kit/sortable @dnd-kit/utilities @phosphor-icons/react @radix-ui/react-alert-dialog @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-popover @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tooltip @tanstack/react-table class-variance-authority clsx cmdk date-fns react-day-picker tailwind-merge zod zustand`,
}"
    />
  </Step>

  <Step>
    ### Verify the app [#verify-the-app]

    Run your normal typecheck and build commands.
  </Step>
</Steps>


# Next.js (https://react-datatable.com/docs/installation/next)

Use this path for Next.js projects. The installer detects App Router versus Pages Router from the project structure.

<Steps>
  <Step>
    ### Create or open a Next.js app [#create-or-open-a-nextjs-app]

    If you need a new app, create one with TypeScript, Tailwind CSS, and the App Router:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm dlx create-next-app@latest my-app --ts --tailwind --app --src-dir
cd my-app`,
  npm: `npx create-next-app@latest my-app --ts --tailwind --app --src-dir
cd my-app`,
  yarn: `yarn dlx create-next-app@latest my-app --ts --tailwind --app --src-dir
cd my-app`,
  bun: `bunx create-next-app@latest my-app --ts --tailwind --app --src-dir
cd my-app`,
}"
    />
  </Step>

  <Step>
    ### Confirm the CSS entry [#confirm-the-css-entry]

    Next.js should have `src/app/globals.css` or `app/globals.css` with Tailwind imported:

    ```css
    @import "tailwindcss";
    ```

    The installer adds the table source to Tailwind's scan path when it finds that file.
  </Step>

  <Step>
    ### Install react-datatable [#install-react-datatable]

    Run the installer from the app root:

    ```bash
npx @react-datatable/cli install --token <license-token> --framework next-app
```

    For a Pages Router app, use:

    ```bash
npx @react-datatable/cli install --token <license-token> --framework next-pages
```

    The default target is `src/react-datatable`. Use `--target react-datatable` when your app does not use `src/`.
  </Step>

  <Step>
    ### Import from the copied source [#import-from-the-copied-source]

    In App Router, render the table from a client component:

    ```tsx
    "use client"

    import { Datatable, type DatatableColumn } from "@/react-datatable"

    type Customer = { id: string; company: string }

    const columns: DatatableColumn<Customer>[] = [
      { id: "company", accessorKey: "company", header: "Company", filterType: "text" },
    ]

    export function CustomersTable({ rows }: { rows: Customer[] }) {
      return <Datatable tableKey="customers" columns={columns} data={rows} getRowId={(row) => row.id} />
    }
    ```
  </Step>

  <Step>
    ### Verify the app [#verify-the-app]

    Run:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm run build`,
  npm: `npm run build`,
  yarn: `yarn build`,
  bun: `bun run build`,
}"
    />
  </Step>
</Steps>


# React Router (https://react-datatable.com/docs/installation/react-router)

Use this path for React Router framework apps.

<Steps>
  <Step>
    ### Create or open a React Router app [#create-or-open-a-react-router-app]

    If you need a new app, create one first:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm create react-router@latest my-app
cd my-app`,
  npm: `npm create react-router@latest my-app
cd my-app`,
  yarn: `yarn create react-router my-app
cd my-app`,
  bun: `bun create react-router@latest my-app
cd my-app`,
}"
    />

    The standard template includes Tailwind CSS and the `~/*` import alias.
  </Step>

  <Step>
    ### Install react-datatable [#install-react-datatable]

    React Router apps usually keep app code under `app/`, so target that directory:

    ```bash
npx @react-datatable/cli install --token <license-token> --framework react-router --target app/react-datatable
```
  </Step>

  <Step>
    ### Use it in a route [#use-it-in-a-route]

    ```tsx
    import { Datatable, type DatatableColumn } from "~/react-datatable"

    type Customer = { id: string; company: string }

    const columns: DatatableColumn<Customer>[] = [
      { id: "company", accessorKey: "company", header: "Company", filterType: "text" },
    ]

    export default function Home() {
      return <Datatable tableKey="customers" columns={columns} data={[]} getRowId={(row) => row.id} />
    }
    ```
  </Step>

  <Step>
    ### Verify the app [#verify-the-app]

    Run:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm run build`,
  npm: `npm run build`,
  yarn: `yarn build`,
  bun: `bun run build`,
}"
    />
  </Step>
</Steps>


# TanStack Start (https://react-datatable.com/docs/installation/tanstack-start)

Use this path for TanStack Start projects created with the TanStack CLI.

<Steps>
  <Step>
    ### Create or open a TanStack Start app [#create-or-open-a-tanstack-start-app]

    If you need a new app, create one first:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm dlx @tanstack/cli@latest create`,
  npm: `npx @tanstack/cli@latest create`,
  yarn: `yarn dlx @tanstack/cli@latest create`,
  bun: `bunx @tanstack/cli@latest create`,
}"
    />

    Choose TanStack Start, React, and the recommended defaults so Tailwind CSS and the `@/*` import alias are configured.
  </Step>

  <Step>
    ### Confirm Tailwind and aliases [#confirm-tailwind-and-aliases]

    The recommended TanStack Start template already includes Tailwind and a `@/*` alias. If your app is custom, make sure the global CSS imports Tailwind and TypeScript resolves `@/*` to `src/*`.
  </Step>

  <Step>
    ### Install react-datatable [#install-react-datatable]

    Run the installer from the app root:

    ```bash
npx @react-datatable/cli install --token <license-token> --framework tanstack-start
```

    The default target is `src/react-datatable`.
  </Step>

  <Step>
    ### Use it in a route [#use-it-in-a-route]

    ```tsx
    import { createFileRoute } from "@tanstack/react-router"
    import { Datatable, type DatatableColumn } from "@/react-datatable"

    type Customer = { id: string; company: string }

    const columns: DatatableColumn<Customer>[] = [
      { id: "company", accessorKey: "company", header: "Company", filterType: "text" },
    ]

    export const Route = createFileRoute("/")({
      component: Page,
    })

    function Page() {
      return <Datatable tableKey="customers" columns={columns} data={[]} getRowId={(row) => row.id} />
    }
    ```
  </Step>

  <Step>
    ### Verify the app [#verify-the-app]

    Run your app's build command:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm run build`,
  npm: `npm run build`,
  yarn: `yarn build`,
  bun: `bun run build`,
}"
    />
  </Step>
</Steps>


# Vite (https://react-datatable.com/docs/installation/vite)

Use this path for a Vite app with React, TypeScript, and Tailwind CSS.

<Steps>
  <Step>
    ### Create or open a Vite React app [#create-or-open-a-vite-react-app]

    If you need a new app, create one with the React + TypeScript template:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm create vite my-app --template react-ts
cd my-app
pnpm install`,
  npm: `npm create vite@latest my-app -- --template react-ts
cd my-app
npm install`,
  yarn: `yarn create vite my-app --template react-ts
cd my-app
yarn install`,
  bun: `bun create vite my-app --template react-ts
cd my-app
bun install`,
}"
    />
  </Step>

  <Step>
    ### Configure Tailwind CSS [#configure-tailwind-css]

    Install Tailwind for Vite when your app does not have it yet:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm add -D tailwindcss @tailwindcss/vite`,
  npm: `npm install -D tailwindcss @tailwindcss/vite`,
  yarn: `yarn add -D tailwindcss @tailwindcss/vite`,
  bun: `bun add --dev tailwindcss @tailwindcss/vite`,
}"
    />

    Add the Vite plugin:

    ```ts
    import tailwindcss from "@tailwindcss/vite"
    import react from "@vitejs/plugin-react"
    import { defineConfig } from "vite"

    export default defineConfig({
      plugins: [react(), tailwindcss()],
    })
    ```

    Make sure `src/index.css` imports Tailwind:

    ```css
    @import "tailwindcss";
    ```
  </Step>

  <Step>
    ### Install react-datatable [#install-react-datatable]

    Run the installer from the app root:

    ```bash
npx @react-datatable/cli install --token <license-token> --framework vite
```

    The default target is `src/react-datatable`.
  </Step>

  <Step>
    ### Render a first table [#render-a-first-table]

    Import from the copied source:

    ```tsx
    import { Datatable, type DatatableColumn } from "./react-datatable"

    type Customer = { id: string; company: string; status: string }

    const columns: DatatableColumn<Customer>[] = [
      { id: "company", accessorKey: "company", header: "Company", filterType: "text" },
      { id: "status", accessorKey: "status", header: "Status", filterType: "text-list" },
    ]

    export function CustomersTable({ rows }: { rows: Customer[] }) {
      return <Datatable tableKey="customers" columns={columns} data={rows} getRowId={(row) => row.id} />
    }
    ```
  </Step>

  <Step>
    ### Verify the app [#verify-the-app]

    Run a production build:

    <PackageManagerCommandTabs
      commands="{
  pnpm: `pnpm run build`,
  npm: `npm run build`,
  yarn: `yarn build`,
  bun: `bun run build`,
}"
    />
  </Step>
</Steps>


# Introduction (https://react-datatable.com/docs/introduction)

`react-datatable` is a source-owned React datatable for teams that need real product behavior without spending weeks assembling it from primitives.

<ImageZoom src="/docs-media/overview/overview-introduction-product-hero.png" alt="Dark-mode react-datatable product view with search, filters, revenue sorting, responsible owner avatars, tags, and views controls" className="my-7 w-full rounded-xs border-0" />

<Callout title="Source-first by design">
  You copy the table source into your app and own it from day one. That means agents and developers can change the shipped UI directly instead of fighting a closed grid abstraction.
</Callout>

## What react-datatable gives you [#what-react-datatable-gives-you]

The table ships as one coordinated system, not a pile of separate recipes. In the current source, `DataTableBody` composes the toolbar, applied state bar, virtualized grid, column visibility affordances, bulk action island, floating preview, and pagination or loading controls.

Out of the box, that system can include:

* quick search and column filters
* sorting, grouping, and column ordering
* display options and column visibility controls
* row selection and bulk actions
* floating row preview
* saved views, current-view persistence, copy links, and URL-backed state
* local data mode, paginated online mode, and infinite online mode
* virtualization for large result sets

## Why teams use it [#why-teams-use-it]

Use `react-datatable` for tables that carry core product workflows, state, and interaction rules.

It is a good fit when you need to move quickly but still want a table that already understands how real product features interact: filters affect selection, views capture state, share links reproduce state, and local and server-backed modes follow the same mental model.

That matters even more in agentic workflows. Instead of asking an agent to invent a complete datatable architecture from scratch, you start from working source that already has the hard edges wired together. If you work with coding agents, you can point them to [llms.txt](/docs/llms.txt) for a compact docs index.

## When it fits best [#when-it-fits-best]

Choose `react-datatable` when:

* you want a production-shaped React table fast
* you need source-level ownership and UI customization
* you expect the table to grow from local rows to server-backed data
* you want one system for search, filtering, persistence, sharing, preview, and bulk workflows

It is probably the wrong tool when:

* you only need a simple static table
* you are not building in React
* you need spreadsheet-style editing behavior
* you cannot copy and maintain source inside your app

## How to read these docs [#how-to-read-these-docs]

The docs are organized by reader job:

* **Quickstart** gets you to a working first table.
* **Concepts** explain the table surface, data loading, state lifecycle, and persistence behavior.
* **Guides** show how to add one capability at a time.
* **Customization** covers changing the shipped UI and source safely.
* **Examples** show complete patterns in context.
* **Reference** keeps the exact API surface in one place.

If you want a first success quickly, go to [Installation](/docs/installation), then [Getting started](/docs/quickstart/getting-started).


# License (https://react-datatable.com/docs/license)

<div className="space-y-5 text-[15px] leading-7 text-foreground">
  <p className="m-0">
    SOFTWARE LICENSE AGREEMENT
  </p>

  <p className="m-0">
    Copyright © react-datatable
  </p>

  <p className="m-0">
    This Software License Agreement ("Agreement") governs the use of the react-datatable source package (the "Software").
  </p>

  <p className="m-0">
    The delivered license document names the licensed company or individual and controls the scope of use for that license.
  </p>

  <p className="m-0">
    By purchasing, downloading, or using the Software, you ("Licensee") agree to be bound by the terms of this Agreement.
  </p>

  <p className="m-0">
    Subject to full payment and compliance with this Agreement, Licensor grants Licensee a non-exclusive, non-transferable,
    revocable license to:
  </p>

  <ul className="m-0 list-disc space-y-2 pl-6">
    <li>
      Use the Software in unlimited internal or commercial applications;
    </li>

    <li>
      Modify the Software for internal use within those applications;
    </li>

    <li>
      Keep the modified Software in private repositories controlled by the licensed company; and
    </li>

    <li>
      Bundle and distribute the Software only as part of compiled production builds.
    </li>
  </ul>

  <p className="m-0">
    Agencies, consultancies, and freelancers must purchase a separate license for each client company.
  </p>

  <p className="m-0">
    Contractors may work with the Software only on behalf of the licensed company and only for that company's applications.
  </p>

  <p className="m-0">
    RESTRICTIONS
  </p>

  <p className="m-0">
    Licensee may not:
  </p>

  <ul className="m-0 list-disc space-y-2 pl-6">
    <li>
      Redistribute, publish, or share the Software source code, in whole or in part;
    </li>

    <li>
      Include the Software in any open-source project, public code repository, or package registry;
    </li>

    <li>
      Transfer the license or provide the Software to another company, client, or third party except as allowed in compiled production builds;
    </li>

    <li>
      Sublicense, resell, rent, lease, or otherwise provide the Software source to third parties; or
    </li>

    <li>
      Use the Software to create a competing datatable product, component library, starter, or template for redistribution.
    </li>
  </ul>

  <p className="m-0">
    OWNERSHIP
  </p>

  <p className="m-0">
    The Software is licensed, not sold. All rights, title, and interest in the Software remain with Licensor. No rights are granted
    other than those expressly stated in this Agreement.
  </p>

  <p className="m-0">
    TERMINATION
  </p>

  <p className="m-0">
    If Licensee breaches any term of this Agreement, the license terminates automatically and immediately. Upon termination,
    Licensee must stop using the Software and delete all source copies of the Software in its possession or control.
  </p>

  <p className="m-0">
    NO WARRANTY
  </p>

  <p className="m-0">
    The Software is provided "as is", without warranties of any kind, express or implied, including but not limited to
    merchantability, fitness for a particular purpose, and non-infringement. Licensor shall not be liable for any damages arising
    from the use of, or inability to use, the Software.
  </p>

  <p className="m-0">
    SUPPORT
  </p>

  <p className="m-0">
    Unless explicitly stated at the time of purchase, this license does not include guaranteed support, maintenance, bug fixes, or
    future updates. Any support, upgrade, or custom terms follow the specific order, invoice, or written agreement tied to the
    purchase.
  </p>

  <p className="m-0">
    FUTURE CHANGES
  </p>

  <p className="m-0">
    Licensor reserves the right to modify, discontinue, relicense, or cease support for the Software at any time. Any future version
    of the Software may be offered under different terms.
  </p>

  <p className="m-0">
    For licensing questions, custom terms, multi-company coverage, agency/client rollout, or client-delivery rights, contact:{" "}
    <a className="underline underline-offset-4" href="mailto:support@react-datatable.com">[support@react-datatable.com](mailto:support@react-datatable.com)</a>
  </p>
</div>


# Pricing (https://react-datatable.com/docs/pricing)

Get a commercial source license for `react-datatable` for your company.

## Business License [#business-license]

We offer a commercial source license for **$999** as a one-time payment.

This license covers **one company** with **unlimited internal or commercial applications**. It is **non-transferable**, and there are **no subscription fees**, **no per-seat fees**, and **no renewal fees** for that licensed scope.

<div className="my-8 grid gap-4 md:grid-cols-2">
  <div className="rounded-2xl border border-border bg-card p-6 md:p-7">
    <p className="m-0 text-sm font-medium text-muted-foreground">
      react-datatable — full source
    </p>

    <p className="mt-3 text-3xl font-semibold tracking-tight">
      $999 paid once
    </p>

    <p className="mt-3 text-sm leading-6 text-muted-foreground">
      Full source code for one company, licensed for unlimited internal or commercial applications under that same company.
    </p>

    <a className="mt-6 inline-flex h-10 items-center justify-center rounded-full bg-foreground px-4 text-sm font-medium text-background no-underline transition-opacity hover:opacity-90" href="/#buy-cta">
      Buy the source code
    </a>
  </div>

  <div className="rounded-2xl border border-border bg-card p-6 md:p-7">
    <p className="m-0 text-sm font-medium text-muted-foreground">
      Risk-free purchase
    </p>

    <p className="mt-3 text-3xl font-semibold tracking-tight">
      30-day money-back guarantee
    </p>

    <p className="mt-3 text-sm leading-6 text-muted-foreground">
      If it is not the right fit, contact us within 30 days of purchase and we will refund the order.
    </p>
  </div>
</div>

* After purchasing, we will send you a link with the source code.
* The standard license covers one company with unlimited internal or commercial applications.
* The license is non-transferable.
* Agencies, consultancies, and freelancers need a separate license for each client company.
* If you need transfer, resale, or separate client-company rights, contact us before purchase.
* You can read the full license terms on the [License](/docs/license) page.

## Frequently Asked Questions [#frequently-asked-questions]

<Accordions type="single">
  <Accordion title="What does the standard license include?">
    The standard license includes the full react-datatable source code for one company, with use in unlimited internal or commercial applications, subject to the non-transferable license terms.
  </Accordion>

  <Accordion title="How will I receive the source code?">
    After purchase, we will send you a link with the source code.
  </Accordion>

  <Accordion title="Can I use it for client work or agency delivery?">
    Not under a single shared license. Agencies, consultancies, and freelancers need a separate license for each client company.
  </Accordion>

  <Accordion title="Can I use one license for multiple products?">
    Yes. The standard purchase covers one company and unlimited internal or commercial applications under that same company. It does not transfer to separate companies or clients.
  </Accordion>

  <Accordion title="Can I buy once and use it for multiple clients?">
    No. Agencies, consultancies, and freelancers need a separate license for each client company.
  </Accordion>

  <Accordion title="Can I get a refund?">
    Yes. We offer a 30-day money-back guarantee. If you need a refund, contact us within 30 days of purchase.
  </Accordion>

  <Accordion title="Where can I ask licensing questions before buying?">
    Reach out to [support@react-datatable.com](mailto:support@react-datatable.com) for licensing, scope, or purchase questions.
  </Accordion>
</Accordions>


# Getting started (https://react-datatable.com/docs/quickstart/getting-started)

Use this page after you have installed the source into your app.

By the end, you should have a local-mode table rendering static rows with working search, filters, selection, and display controls.

<ImageZoom src="/docs-media/quickstart/getting-started-table-overview.png" alt="A seeded local react-datatable showing company, plan, region, contact, seats, and renewal columns in a dark table view." className="my-7 w-full rounded-xs border-0" />

## Before you start [#before-you-start]

Complete [Installation](/docs/installation) first. Your app should already have:

* the copied `src/react-datatable` source
* the runtime dependencies installed
* Tailwind configured to scan the copied source
* the theme tokens the table expects

## 1. Define the row type [#1-define-the-row-type]

Start with the shape your product already uses.

```tsx
type Customer = {
  id: string
  company: string
  status: "active" | "trial" | "paused"
  seats: number
}
```

Stable row identity matters because selection, preview, persistence, and online replacement all depend on it later.

## 2. Define the columns [#2-define-the-columns]

Columns are the table contract. Give every column a stable `id`.

```tsx
import type { DatatableColumn } from "./react-datatable"

const columns: DatatableColumn<Customer>[] = [
  {
    id: "company",
    accessorKey: "company",
    header: "Company",
    filterType: "text",
  },
  {
    id: "status",
    accessorKey: "status",
    header: "Status",
    filterType: "text-list",
  },
  {
    id: "seats",
    accessorKey: "seats",
    header: "Seats",
    filterType: "number",
  },
]
```

## 3. Create the table component [#3-create-the-table-component]

Local mode uses the `data` prop. It does not need an app-level provider.

```tsx
import { Datatable, type DatatableColumn } from "./react-datatable"

type Customer = {
  id: string
  company: string
  status: "active" | "trial" | "paused"
  seats: number
}

const columns: DatatableColumn<Customer>[] = [
  { id: "company", accessorKey: "company", header: "Company", filterType: "text" },
  { id: "status", accessorKey: "status", header: "Status", filterType: "text-list" },
  { id: "seats", accessorKey: "seats", header: "Seats", filterType: "number" },
]

export function CustomersTable({ rows }: { rows: Customer[] }) {
  return (
    <Datatable
      tableKey="customers"
      columns={columns}
      data={rows}
      getRowId={(row) => row.id}
    />
  )
}
```

`tableKey` gives the table a stable identity for persisted state, runtime restoration, and feature configuration that needs a table namespace.

## 4. Add first controls [#4-add-first-controls]

Turn on the built-in controls you want users to see first.

```tsx
export function CustomersTable({ rows }: { rows: Customer[] }) {
  return (
    <Datatable
      tableKey="customers"
      columns={columns}
      data={rows}
      getRowId={(row) => row.id}
      toolbar={{
        quickSearch: { placeholder: "Search customers..." },
        filterButton: true,
        displayOptions: true,
      }}
      selection={{ enabled: true }}
    />
  )
}
```

This keeps the first table small while still proving the main surface: search, filters, display options, and row selection.

## 5. Add viewport virtualization [#5-add-viewport-virtualization]

Use virtualization when the table can render enough rows to make DOM size matter.

```tsx
export function CustomersTable({ rows }: { rows: Customer[] }) {
  return (
    <Datatable
      tableKey="customers"
      columns={columns}
      data={rows}
      getRowId={(row) => row.id}
      toolbar={{
        quickSearch: { placeholder: "Search customers..." },
        filterButton: true,
        displayOptions: true,
      }}
      selection={{ enabled: true }}
      virtualization={{ mode: "viewport", rowOverscanCount: 8 }}
    />
  )
}
```

Virtualization is a rendering setting. It does not change whether the browser or server owns the row set.

## 6. Initialize it with static rows [#6-initialize-it-with-static-rows]

For the first pass, keep the data local and explicit.

```tsx
import { CustomersTable } from "./CustomersTable"

const customerRows = [
  { id: "cus_001", company: "Acme Inc.", status: "active", seats: 42 },
  { id: "cus_002", company: "Northstar Labs", status: "trial", seats: 12 },
  { id: "cus_003", company: "Orbit Systems", status: "paused", seats: 7 },
] satisfies Array<{
  id: string
  company: string
  status: "active" | "trial" | "paused"
  seats: number
}>

export function App() {
  return <CustomersTable rows={customerRows} />
}
```

Once the static table is working, you can replace `customerRows` with route data, loader data, or an `online.query` function.

<Callout title="What success looks like">
  You should now have a table that renders rows, accepts stable columns and row IDs, and shows the first toolbar controls without needing a custom architecture pass first.
</Callout>

## Verify the setup [#verify-the-setup]

Use the smallest checks that match your app:

<PackageManagerCommandTabs
  commands="{
  pnpm: `pnpm run typecheck
pnpm run build`,
  npm: `npm run typecheck
npm run build`,
  yarn: `yarn typecheck
yarn build`,
  bun: `bun run typecheck
bun run build`,
}"
/>

If you are working inside the `react-datatable` repository, the local examples provide a known-good baseline:

<PackageManagerCommandTabs
  commands="{
  pnpm: `pnpm run dev:local-basic
pnpm run dev:online-basic`,
  npm: `npm run dev:local-basic
npm run dev:online-basic`,
  yarn: `yarn dev:local-basic
yarn dev:online-basic`,
  bun: `bun run dev:local-basic
bun run dev:online-basic`,
}"
/>

## Where to go next [#where-to-go-next]

If the table is rendering and you want to shape the integration boundary, continue to [Define columns](/docs/guides/define-columns), then [Define your table](/docs/guides/define-your-table).

For server-backed data, read [Data loading](/docs/concepts/data-loading), then [Choose a data mode](/docs/guides/choose-a-data-mode).


# Column API (https://react-datatable.com/docs/reference/column-api)

Use this page when you need the exact meaning of a column field. For the higher-level setup flow, start with [Define columns](/docs/guides/define-columns).

## Main type [#main-type]

```ts
interface DatatableColumn<TData, TValue = unknown> {
  id: string
  header: string
  order?: number
  defaultVisible?: boolean
  width?: number
  minWidth?: number
  maxWidth?: number
  resizable?: boolean
  accessorKey?: keyof TData
  accessorFn?: (row: TData) => TValue
  cell?: ColumnDef<TData, TValue>["cell"]
  enableSorting?: boolean
  sortingFn?: ColumnDef<TData, TValue>["sortingFn"]
  showSortInHeader?: boolean
  enableFiltering?: boolean
  enableGlobalFilter?: boolean
  filterType?: FilterType
  filterOptions?: FilterOptions
  enableGrouping?: boolean
  groupingSpec?: ColumnGroupingSpec
  meta?: {
    displayName?: string
    filterName?: string
    filterIcon?: React.ComponentType<{ className?: string }>
    [key: string]: unknown
  }
}
```

## Identity and labels [#identity-and-labels]

### `id` [#id]

Stable machine-readable column ID.

This is the contract key used by:

* filters
* sorting
* grouping
* saved views
* persisted current-view state
* URL state
* online query inputs

Do not derive it from visible text.

### `header` [#header]

Primary visible column label in the shipped grid header.

### `meta.displayName` [#metadisplayname]

Optional friendlier display label for product surfaces that should not reuse the raw header text.

### `meta.filterName` [#metafiltername]

Optional label override for filter UI.

### `meta.filterIcon` [#metafiltericon]

Optional custom icon for filter affordances.

## Visibility and order [#visibility-and-order]

### `order` [#order]

Initial relative column order.

Use it when the source order of your array should not be the rendered default.

### `defaultVisible` [#defaultvisible]

Whether the column starts visible.

Hidden-by-default columns can still be surfaced later through display options, views, or persisted state if your table exposes those controls.

## Width and resizing [#width-and-resizing]

### `width` [#width]

Initial resolved width in pixels.

### `minWidth` [#minwidth]

Minimum allowed width.

### `maxWidth` [#maxwidth]

Maximum allowed width.

### `resizable` [#resizable]

Per-column override for whether the user can resize this column.

Use fixed sizing for structural columns that should not be dragged into unusable widths.

## Data access [#data-access]

### `accessorKey` [#accessorkey]

Direct field access for simple columns.

```tsx
{
  id: "company",
  accessorKey: "company",
  header: "Company",
}
```

Prefer this when the rendered value maps directly to a row property.

### `accessorFn` [#accessorfn]

Derived value accessor.

```tsx
{
  id: "accountHealth",
  header: "Health",
  accessorFn: (row) => `${row.status}:${row.seats}`,
}
```

Use this only when the column value is intentionally computed. In online mode, make sure your backend query semantics still match the column ID and intended sort/filter behavior.

### `cell` [#cell]

Custom cell renderer.

The table provides TanStack-style cell context in both local and online modes, so normal `cell` patterns still work when online rows are server-shaped.

For broader guidance, see:

* [Custom React cells](/docs/customization/custom-react-cells)
* [Custom cells gallery](/docs/examples/custom-cells-gallery)

## Sorting fields [#sorting-fields]

### `enableSorting` [#enablesorting]

Whether the column participates in sorting.

### `sortingFn` [#sortingfn]

TanStack-compatible local sorting function override.

Use this only when the default sort semantics for the accessed value are wrong for local mode.

### `showSortInHeader` [#showsortinheader]

Whether sort state should render in the header for this column.

This is useful when sorting is still active but should stay out of the primary header presentation.

## Filtering fields [#filtering-fields]

### `enableFiltering` [#enablefiltering]

Whether the column participates in column-filter workflows.

### `enableGlobalFilter` [#enableglobalfilter]

Whether the column is included in the shipped quick-search/global-search behavior.

See [Add global search](/docs/guides/add-global-search).

### `filterType` [#filtertype]

```ts
"text" | "number" | "date" | "boolean" | "text-list" | "id-list" | "custom"
```

This controls the filter payload shape and the intended user query semantics.

Common uses:

* `text`: names, titles, identifiers
* `number`: counts, amounts, scores
* `date`: machine-readable date fields
* `boolean`: yes/no state
* `text-list`: finite visible labels such as status or plan
* `id-list`: related entity IDs such as assignee or project
* `custom`: product-owned custom filter payload

### `filterOptions` [#filteroptions]

Optional configuration for the selected `filterType`.

Option-list filters support a shared presentation hook:

```ts
renderOption?: (option: { value: string | boolean; label: string }) => React.ReactNode
```

Use `renderOption` when the built-in option editor should show richer rows, such as avatars, icons, color dots, or status badges. The selected filter payload still stores the option `value`; `renderOption` only changes presentation.

#### Text-list options [#text-list-options]

```ts
{
  options: string[] | { value: string; label: string }[]
  renderOption?: (option: { value: string; label: string }) => React.ReactNode
}
```

#### ID-list options [#id-list-options]

```ts
{
  options: { value: string; label: string }[]
  isLoading?: boolean
  emptyText?: string
  searchPlaceholder?: string
  renderOption?: (option: { value: string; label: string }) => React.ReactNode
}
```

#### Boolean options [#boolean-options]

```ts
{
  options?: [{ value: true; label: string }, { value: false; label: string }]
  renderOption?: (option: { value: boolean; label: string }) => React.ReactNode
}
```

#### Date options [#date-options]

```ts
{
  presets?: ("today" | "yesterday" | "last7days" | "last30days" | "thisMonth" | "lastMonth")[]
}
```

Reference note: the type system supports more filter shapes than every shipped filter UI currently exposes. Document the product surface you actually ship.

See:

* [Add column filters](/docs/guides/add-column-filters)
* [Customizing filter UI](/docs/customization/customizing-filter-ui)

## Grouping fields [#grouping-fields]

### `enableGrouping` [#enablegrouping]

Whether the column can be used in grouping controls.

### `groupingSpec` [#groupingspec]

Controls how values group when raw values are not the right product bucket.

```ts
interface ColumnGroupingSpec {
  supportsOffline?: boolean
  supportsOnline?: boolean
  variants: Record<string, GroupingVariant>
  defaultVariant: string
}
```

### `supportsOffline` [#supportsoffline]

Set to `false` when a grouping model should only be handled by your backend.

### `supportsOnline` [#supportsonline]

Set to `false` when a grouping model only makes sense in local mode.

### `variants` [#variants]

Named grouping strategies.

```ts
type GroupingVariant =
  | { kind: "raw"; emptyLabel?: string }
  | { kind: "date_trunc"; granularity: "day" | "week" | "month" | "year"; emptyLabel?: string }
  | { kind: "bucket"; buckets: GroupingBucket[]; emptyLabel?: string }
```

#### Raw grouping [#raw-grouping]

Groups by the raw value directly.

#### Date truncation [#date-truncation]

Useful for month, week, or year buckets built from a machine-readable date.

#### Buckets [#buckets]

Useful for numeric ranges such as seat tiers, deal size bands, or SLA buckets.

```ts
interface GroupingBucket {
  id: string
  label: string
  min?: number
  max?: number
}
```

### `defaultVariant` [#defaultvariant]

The variant key used unless the grouping flow explicitly chooses another one.

See [Add grouping](/docs/guides/add-grouping).

## Runtime column metadata [#runtime-column-metadata]

The source also defines a lower-level `ColumnMetadata` interface used inside the resolved table model:

```ts
interface ColumnMetadata {
  width?: number
  showSortInHeader?: boolean
  isSticky?: boolean
  isLastStickyColumn?: boolean
  stickyLeftOffset?: number
  filterType?: FilterType
  isSpacer?: boolean
  [key: string]: unknown
}
```

This is mostly useful when extending internal rendering behavior on the copied source, not for normal table setup.

## Practical reminders [#practical-reminders]

* Keep column IDs stable over time.
* Choose filter and grouping semantics from the data model, not from the badge or cell styling.
* Treat `cell` as a rendering seam, not a place to hide behavioral rules.
* In online mode, remember that your backend still owns the real sorting, filtering, grouping, and facet behavior.

## Related pages [#related-pages]

* [Define columns](/docs/guides/define-columns)
* [Column ordering](/docs/guides/add-column-ordering)
* [Online API](/docs/reference/online-api)
* [TypeScript types](/docs/reference/typescript-types)


# Component API (https://react-datatable.com/docs/reference/component-api)

Use this page when you already know which capability you want and need the exact top-level prop or export surface. For implementation guidance, start with the rewritten guides and concepts pages.

## Public imports [#public-imports]

```tsx
import {
  Datatable,
  DataTableProvider,
  useDatatableColumns,
  useDatatableColumnSizing,
  useDatatableStore,
  useDatatableStoreApi,
  type DatatableColumn,
  type DatatableProps,
} from "./react-datatable"
```

* `Datatable` is the component export.
* `DatatableProps` is the component prop type.
* `DataTableProvider` and store hooks are lower-level exports for advanced integrations around the shipped table state model.

## Main component contract [#main-component-contract]

```ts
interface DatatableProps<TData> {
  tableKey: string
  columns: DatatableColumn<TData>[]
  getRowId?: (row: TData) => string
  initialState?: Partial<DatatableState>
  runtimeRestoration?: boolean | { key?: string; pagination?: boolean; scroll?: boolean }
  onReadyStateChange?: (ready: boolean) => void
  rowHeight?: number
  headerHeight?: number
  virtualization?: DataTableVirtualizationConfig
  columnReordering?: DataTableColumnReorderingConfig
  selection?: DataTableRowSelectionConfig<TData>
  bulkActions?: DataTableBulkActionsConfig<TData>
  rowPresentation?: DataTableRowPresentationConfig<TData>
  keyboardNavigation?: DataTableKeyboardNavigationConfig
  rowActions?: DataTableRowActionsConfig<TData>
  preview?: DataTableRowPreviewConfig<TData>
  enableColumnResizing?: boolean
  columnResizeMode?: "onChange" | "onEnd"
  persistState?: { ... }
  urlSync?: boolean | Omit<UseDatatableUrlOptions<TData>, "columns">
  stickyColumnsCount?: number
  columnVisibilityUI?: ColumnVisibilityUIConfig
  displayOptions?: boolean | DataTableDisplayOptionsConfig
  views?: { ... }
  toolbar?: boolean | { ... }
  viewColumnsButton?: boolean | { ... }
  debug?: boolean
}

type DatatableLocalModeProps<TData> = {
  data: TData[]
  online?: never
}

type DatatableOnlineModeProps<TData> = {
  online: OnlineConfig<TData>
  data?: never
}
```

## Required setup [#required-setup]

### `tableKey` [#tablekey]

`tableKey` is required. Use a stable product-surface key such as `"customers"`, `"deals"`, or `"workspace-members"`. The table uses it as the default key for runtime restoration, persistence, saved views, and floating preview position.

### `columns` [#columns]

`columns` is required. The table uses this model for rendering, sorting, filtering, grouping, visibility, and customization seams.

See [Column API](/docs/reference/column-api) for the full column shape.

### `data` or `online` [#data-or-online]

Provide exactly one primary data mode:

* `data`: local/offline mode. The table owns filtering, sorting, grouping, and viewport rendering against the array you pass in.
* `online`: server-driven mode. The table owns interaction state, but your query function owns row retrieval, totals, facets, and backend ordering.

If the first online response is already loaded by a route loader or parent cache, pass it through `online.initialData`. Top-level `data` is only for local mode.

If you provide neither, the component throws during render.

See:

* [Choose a data mode](/docs/guides/choose-a-data-mode)
* [Data loading](/docs/concepts/data-loading)
* [Online API](/docs/reference/online-api)

### `getRowId` [#getrowid]

Use `getRowId` when your row key is not the default TanStack row index. In practice you should provide it for any real product table so selection, preview, persistence, and online transitions stay stable.

## Initialization and readiness [#initialization-and-readiness]

### `initialState` [#initialstate]

```tsx
<Datatable
  tableKey="customers"
  initialState={{
    sorting: [{ id: "updatedAt", desc: true }],
    globalFilter: "active",
    grouping: ["status"],
  }}
/>
```

`initialState` seeds the store before saved views, persisted state, and URL state are merged in. Treat it as your developer default, not as a forced final state.

See [State Lifecycle](/docs/concepts/state-lifecycle).

### `onReadyStateChange` [#onreadystatechange]

`onReadyStateChange(ready)` fires when the table has finished loading coordinated state sources and the interactive surface is ready.

Use it when surrounding UI must wait for:

* persisted current-view state
* default saved views
* initial URL state
* initial online loading

### `runtimeRestoration` [#runtimerestoration]

Runtime restoration keeps navigation position available while the current browser session is alive. It is useful in SPAs where a table can unmount and remount as users switch tabs, open a row detail route, or move between sibling screens.

It is enabled by default and uses the top-level `tableKey`.

```tsx
<Datatable
  tableKey="customers"
  runtimeRestoration={{
    pagination: true,
    scroll: true,
  }}
/>
```

The available shape is:

```ts
boolean | {
  key?: string
  pagination?: boolean
  scroll?: boolean
}
```

Use `runtimeRestoration={false}` when route changes should always return the table to its initial runtime position. Use `{ pagination: false }` when page movement should reset on remount but scroll should still come back, or `{ scroll: false }` when page state should return but scroll should start at the top.

This is separate from `persistState`. Runtime pagination and scroll position use `sessionStorage` by default so they survive remounts and hard refreshes in the same browser tab. Persisted state is durable user preference storage.

## Sizing and layout [#sizing-and-layout]

### `rowHeight` [#rowheight]

Height of data rows.

* default: `40`

### `headerHeight` [#headerheight]

Height of header rows.

* default: `40`

### `stickyColumnsCount` [#stickycolumnscount]

Initial number of left-frozen columns. Users can still change frozen columns later if you expose the relevant display options controls.

### `enableColumnResizing` [#enablecolumnresizing]

Enables header drag resizing.

* default: `true`

### `columnResizeMode` [#columnresizemode]

```ts
"onChange" | "onEnd"
```

* `onChange`: resize continuously while dragging
* `onEnd`: update width after drag ends

## Feature configuration groups [#feature-configuration-groups]

The top-level API is intentionally grouped by reader job. Most capabilities live under one focused prop object.

```tsx
<Datatable
  tableKey="customers"
  virtualization={{ ... }}
  columnReordering={{ ... }}
  selection={{ ... }}
  bulkActions={{ ... }}
  rowPresentation={{ ... }}
  keyboardNavigation={{ ... }}
  rowActions={{ ... }}
  preview={{ ... }}
  persistState={{ ... }}
  urlSync={{ ... }}
  views={{ ... }}
  toolbar={{ ... }}
  displayOptions={{ ... }}
  viewColumnsButton={{ ... }}
/>
```

### `virtualization` [#virtualization]

Controls viewport rendering policy and overscan.

```ts
{
  mode?: "viewport" | "full"
  rowOverscanCount?: number
  columnOverscanCount?: number
}
```

Use this for render-cost tuning, not data fetching.

See [Tune virtualization](/docs/guides/tune-virtualization).

### `columnReordering` [#columnreordering]

Controls drag behavior for visible columns.

```ts
{
  allowFrozenBoundaryCrossing?: boolean
  widthMorph?: "none" | "snap" | "interpolate"
}
```

See [Add column ordering](/docs/guides/add-column-ordering).

### `selection` [#selection]

Enables row selection.

```ts
{
  enabled: boolean
  mode?: "multi"
  showCheckboxOnHover?: boolean
  maxSelectedRows?: number
  allowSelectAllMatching?: boolean
  getRowCanSelect?: (row) => boolean
}
```

See [Add row selection](/docs/guides/add-row-selection).

### `bulkActions` [#bulkactions]

Configures the selected-row action flow.

```ts
{
  actions: DataTableBulkAction<TData>[]
  triggerLabel?: string
  serverExecutor?: (request: DataTableBulkServerActionRequest) => void | Promise<void>
}
```

See [Add bulk actions](/docs/guides/add-bulk-actions).

### `rowPresentation` [#rowpresentation]

Adds state-aware row and cell styling hooks.

Use it when selection, active-row, or preview state should change classes or attributes without replacing the underlying table behavior.

See [Styling rows and cells](/docs/customization/styling-rows-and-cells).

### `keyboardNavigation` [#keyboardnavigation]

```ts
{
  enabled?: boolean
  autoFocus?: boolean
}
```

Enables active-row keyboard movement and related Enter/Space behavior.

See [Add keyboard navigation](/docs/guides/add-keyboard-navigation).

### `rowActions` [#rowactions]

```ts
{
  onOpenRow?: (context) => void | Promise<void>
  onTogglePreviewRow?: (context) => void | Promise<void>
}
```

Use `rowActions` when the table should signal row intent but your app owns the actual route navigation or domain-specific side effect.

### `preview` [#preview]

```ts
{
  enabled?: boolean
  floating?: {
    draggable?: boolean
    storageKey?: string
  }
  renderPreview: ({ row, rowId, close }) => ReactNode
}
```

Adds the built-in preview surface for the current preview row.

See:

* [Add row preview](/docs/guides/add-row-preview)
* [Customizing preview UI](/docs/customization/customizing-preview-ui)

## Persistence, sharing, and URL state [#persistence-sharing-and-url-state]

### `persistState` [#persiststate]

Use `persistState` for the current user's remembered table state.

```tsx
<Datatable
  tableKey="customers"
  persistState={{
    adapter: localStorageAdapter,
    workspaceId: "wsp_123",
    userId: "usr_456",
    debounceMs: 1000,
    onSave: () => {},
    onError: (error) => console.error(error),
  }}
/>
```

Required fields:

* `adapter`

Optional fields:

* `tableKey` when this adapter should use a namespace different from the top-level table key
* `workspaceId`
* `userId`
* `debounceMs`
* `onSave`
* `onError`

See [Add current-view persistence](/docs/guides/add-current-view-persistence).

### `urlSync` [#urlsync]

```ts
boolean | {
  enabled?: boolean
  acceptUrlParams?: boolean
  historyMode?: "push" | "replace"
  ...
}
```

* `false`: do not write ongoing state to the URL, but still accept incoming URL params by default
* `true`: enable continuous bidirectional URL synchronization
* object: configure the URL behavior explicitly

Only one table per page should actively write to the shared query param space.

See [Add URL sync](/docs/guides/add-url-sync).

### `views` [#views]

Use `views` for named saved views.

```tsx
<Datatable
  tableKey="customers"
  views={{
    adapter,
    workspaceId: "wsp_123",
    userId: "usr_456",
    enableWorkspaceSharing: true,
    enableUserDefaults: true,
    onSuccess: () => {},
    onError: (error) => console.error(error),
  }}
  toolbar={{ views: true }}
/>
```

Required fields:

* `adapter`

Optional fields:

* `tableKey` when this adapter should use a namespace different from the top-level table key
* `workspaceId`
* `userId`
* `enableWorkspaceSharing`
* `enableUserDefaults`
* `onSuccess`
* `onError`

If `views` is configured but `toolbar.views` is hidden, the saved-view data model still exists but the shipped toolbar entry point does not render.

See:

* [Add saved views](/docs/guides/add-saved-views)
* [Persistence and Sharing](/docs/concepts/persistence-and-sharing)
* [Customizing saved view UI](/docs/customization/customizing-saved-view-ui)

## Toolbar and display surfaces [#toolbar-and-display-surfaces]

### `toolbar` [#toolbar]

```ts
boolean | {
  quickSearch?: boolean | {
    placeholder?: string
    debounceMs?: number
  }
  filterButton?: boolean
  displayOptions?: boolean
  copyLink?: boolean
  views?: boolean
  appliedState?: {
    showSorting?: boolean
    showFilters?: boolean
  }
}
```

Use this to choose which shipped toolbar controls appear. It does not replace the underlying feature contracts; it exposes or hides the surface.

See:

* [Add global search](/docs/guides/add-global-search)
* [Configure display options](/docs/guides/configure-display-options)
* [Customizing toolbar and controls](/docs/customization/customizing-toolbar-and-controls)

### `displayOptions` [#displayoptions]

```ts
boolean | {
  sections?: {
    grouping?: boolean
    ordering?: boolean
    freezeColumns?: boolean
    displaySettings?: boolean
    columnVisibility?: boolean
  }
  controls?: {
    showEmptyGroups?: boolean
    showOrderingBadge?: boolean
  }
}
```

`false` hides the display options button completely. An object keeps the button but limits what users can control.

### `columnVisibilityUI` [#columnvisibilityui]

Controls how column visibility management renders.

* `badges`
* `dropdown`
* `auto`

### `viewColumnsButton` [#viewcolumnsbutton]

```ts
boolean | {
  show?: boolean
  width?: number
}
```

Controls the optional right-side view-columns affordance.

## Lower-level exports [#lower-level-exports]

### `DataTableProvider` [#datatableprovider]

Creates the isolated store and coordinates `initialState`, persistence, saved views, and URL state before the table body renders.

Use it only when you are building a more custom wrapper around the shipped table internals.

### `useDatatableColumns` [#usedatatablecolumns]

Returns column metadata from provider context for internal-style integrations that need the current public column model.

### `useDatatableColumnSizing` [#usedatatablecolumnsizing]

Lower-level sizing hook exported from `DataTableBody`.

### `useDatatableStore` and `useDatatableStoreApi` [#usedatatablestore-and-usedatatablestoreapi]

Advanced hooks into the Zustand-backed table store.

Reach for these only when prop-level APIs are not enough and you are intentionally extending the source-owned table behavior.

## Related pages [#related-pages]

* [Column API](/docs/reference/column-api)
* [Online API](/docs/reference/online-api)
* [Define your table](/docs/guides/define-your-table)
* [Customization overview](/docs/customization/customization-overview)


# Online API (https://react-datatable.com/docs/reference/online-api)

Use this page when you need the exact backend contract for server-driven tables. For the higher-level decision, start with [Choose a data mode](/docs/guides/choose-a-data-mode).

## Main config [#main-config]

```ts
interface OnlineConfig<TData> {
  mode: "infinite" | "pagination"
  queryKey: readonly unknown[]
  supportedGroupingColumns?: string[]
  query: (input: OnlineQueryInput) => Promise<OnlineQueryResponse<TData>>
  initialData?: OnlineQueryResponse<TData>
  initialDataQueryState?: OnlineQueryStateInput
  pageSize?: number
  prefetchRows?: number
  initialPageIndex?: number
}
```

Online mode means the backend owns query semantics:

* global search
* column filters
* sorting
* grouping
* totals
* stable row ordering
* page or window slicing

The client still owns viewport rendering, row measurement, and which visible range should be loaded next.

## Required fields [#required-fields]

### `mode` [#mode]

```ts
"infinite" | "pagination"
```

* `pagination`: one page at a time, with `pageIndex` and pagination controls
* `infinite`: server windows addressed by data-row `offset`, which supports long scrolling and direct scrollbar jumps

### `queryKey` [#querykey]

Stable query identity for this table.

Keep it stable across renders and specific enough to isolate tenant or table identity.

### `query` [#query]

Your backend query function.

```tsx
online={{
  mode: "pagination",
  queryKey: ["customers", workspaceId],
  query: (input) => trpc.customer.listOnline.query(input),
}}
```

This is the authoritative boundary between the datatable and your backend. The table sends interaction state; your backend returns fully ordered rows plus totals and optional grouping/facet metadata.

## Optional fields [#optional-fields]

### `supportedGroupingColumns` [#supportedgroupingcolumns]

List of column IDs your backend can group by.

When provided, the table sanitizes persisted and URL-loaded grouping state so unsupported columns do not stay selected or get sent to the server.

### `initialData` [#initialdata]

Optional prefetched first response.

Use this when the route loader or parent component already fetched the first online result before the table mounts.

### `initialDataQueryState` [#initialdataquerystate]

The exact query state that produced `initialData`.

If provided, the table only seeds `initialData` when the current filter/sort/search/grouping state still matches it. This prevents showing stale prefetched rows after persisted state or URL state changes the real query.

### `pageSize` [#pagesize]

Rows requested per server call.

* default: `50`

### `prefetchRows` [#prefetchrows]

How aggressively online infinite mode warms data before and after the visible range.

* default: `pageSize`

This is separate from virtualization overscan:

* virtualization overscan controls mounted DOM rows
* `prefetchRows` controls server data warmed around the visible range

### `initialPageIndex` [#initialpageindex]

Initial page in pagination mode.

* default: `0`
* ignored in infinite mode

## Query input types [#query-input-types]

### Shared query state [#shared-query-state]

```ts
interface OnlineQueryStateInput {
  limit: number
  filters: ColumnFilter[]
  sorting: SortingState
  globalFilter: string
  grouping?: {
    columns: string[]
    showEmptyGroups?: boolean
  }
}
```

The table always sends the current query semantics in this shape.

#### `limit` [#limit]

Requested page or window size.

#### `filters` [#filters]

Column filters in the datatable's own internal format.

#### `sorting` [#sorting]

TanStack-style sorting state.

#### `globalFilter` [#globalfilter]

Current quick-search string.

#### `grouping` [#grouping]

Present only when grouping is active.

```ts
{
  columns: string[]
  showEmptyGroups?: boolean
}
```

* `columns`: group-by columns in order
* `showEmptyGroups`: request zero-count groups when your backend knows a finite group domain

## Navigation-specific input [#navigation-specific-input]

### Pagination input [#pagination-input]

```ts
interface PaginationOnlineQueryInput extends OnlineQueryStateInput {
  mode: "pagination"
  pageIndex: number
  offset: number
}
```

Example:

```ts
{
  mode: "pagination",
  limit: 50,
  pageIndex: 0,
  offset: 0,
  filters: [],
  sorting: [{ id: "company", desc: false }],
  globalFilter: "",
}
```

### Infinite input [#infinite-input]

```ts
interface InfiniteOnlineQueryInput extends OnlineQueryStateInput {
  mode: "infinite"
  offset: number
}
```

Example:

```ts
{
  mode: "infinite",
  limit: 50,
  offset: 80000,
  filters: [],
  sorting: [{ id: "company", desc: false }],
  globalFilter: "",
}
```

Important: in infinite mode, `offset` is the first data-row index needed for the visible range. Requests may arrive out of order.

## Response type [#response-type]

```ts
interface OnlineQueryResponse<TData> {
  rows: OnlineTableRow<TData>[]
  totalDataRows: number
  totalRenderedRows: number
  hasMore: boolean
  grouping?: OnlineGroupingSummary
  facets?: Record<string, Array<{ value: string; count: number }>>
}
```

## Response fields [#response-fields]

### `rows` [#rows]

Rows in final render order.

Ungrouped mode returns only data rows. Grouped mode returns both structural group headers and data rows.

### `totalDataRows` [#totaldatarows]

Count of matching data records across the full filtered result.

### `totalRenderedRows` [#totalrenderedrows]

Count of full rendered rows across the filtered result, including structural rows such as group headers.

This matters for grouped pagination and grouped infinite mode.

### `hasMore` [#hasmore]

Whether more results remain beyond the current page or loaded window.

### `grouping` [#grouping-1]

Optional full-query grouping summary used by the client to build the rendered row plan in grouped online mode.

### `facets` [#facets]

Optional aggregated filter counts keyed by column ID.

Facet counts should use the same tenant, permission, search, and filter scope as the returned rows.

## Row model [#row-model]

```ts
type OnlineTableRow<TData> =
  | {
      type: "group-header"
      groupId: string
      columnId: string
      value: string
      depth: number
      count: number
      isExpanded?: boolean
      groupPath: string[]
    }
  | {
      type: "data"
      rowId: string
      item: TData
      groupPath: string[]
    }
```

### Group header rows [#group-header-rows]

Use these when the backend returns grouped online output.

* `groupId`: stable server-owned identifier for the group
* `columnId`: grouped column
* `value`: visible group value
* `depth`: grouping depth (`0` for primary group, `1` for subgroup, and so on)
* `count`: data-row count in the group
* `groupPath`: ancestor group IDs in order

### Data rows [#data-rows]

* `rowId`: stable row identifier
* `item`: your domain object
* `groupPath`: ancestor group IDs for grouped output, or `[]` when ungrouped

## Grouping summary [#grouping-summary]

```ts
interface OnlineGroupingSummary {
  groups: Record<
    string,
    {
      total: number
      renderedRowCount: number
      subgroups?: Record<
        string,
        {
          total: number
          renderedRowCount: number
        }
      >
    }
  >
}
```

This summary describes the full grouped result, not just the currently loaded page.

Use it so the client can:

* build sparse rendered rows for infinite loading
* insert group headers in the right places
* preserve empty groups when requested
* translate visible rendered ranges back into data-row offsets

For grouped infinite mode, `totalRenderedRows` should include structural group rows for the whole filtered result, not only the returned slice.

## Inspecting real query behavior in the showcase backend [#inspecting-real-query-behavior-in-the-showcase-backend]

The showcase `/api/showcase/data` route emits lightweight diagnostics headers so you can confirm which backend path actually ran without attaching a profiler.

* `server-timing`: total request execution time for the datatable query path
* `x-react-datatable-query-plan`: `flat_window` or `grouped_window`
* `x-react-datatable-query-path`: `flat_sql` or `grouped_sql`
* `x-react-datatable-query-duration-ms`: query execution duration in milliseconds

Use this to verify that real requests are taking the SQL-backed path and to spot regressions quickly during staging or production debugging.

## Facets [#facets-1]

```ts
facets: {
  status: [
    { value: "active", count: 842 },
    { value: "trial", count: 91 },
  ],
}
```

Keys should match column IDs.

Use facets when your filter UI needs backend-aware counts for the currently filtered/search-scoped result.

## Server responsibilities [#server-responsibilities]

Apply the online query in a stable order:

1. global search
2. column filters
3. group key ordering when grouping is active
4. sorting
5. grouping and group-header creation
6. pagination or infinite offset slicing
7. stable tie-breaker ordering

That stable ordering matters because online infinite mode may fetch windows out of order.

## Infinite-loading behavior [#infinite-loading-behavior]

The client does not fetch rows sequentially forever. It requests the visible data-row range plus prefetched nearby windows.

That means your backend should be comfortable receiving requests like:

* offset `0`
* then offset `200`
* then offset `80000`

without assuming all prior pages were loaded first.

## Empty groups [#empty-groups]

When `grouping.showEmptyGroups` is `true`, grouped responses may include empty groups if your backend knows the finite group domain.

A zero-count group can look like:

```ts
{
  total: 0,
  renderedRowCount: 1
}
```

The included local server helper can derive this from static `filterOptions.options` domains. Production backends should implement the equivalent behavior from their own enums or domain tables.

## Helper export [#helper-export]

`react-datatable-server` exports `runInMemoryDatatableQuery`.

Use it for:

* demos
* fixtures
* tests
* local examples

For production, implement the same contract against your real database or ORM instead of relying on the helper as a hosted abstraction.

See [Server helper API](/docs/reference/server-helper-api).

## Practical reminders [#practical-reminders]

* Keep `rowId` and `groupId` stable.
* Treat online offsets as data-row offsets, not rendered-row offsets.
* Return rows in final render order.
* Keep facet counts and totals scoped exactly the same way as the row result.
* Do not confuse virtualization with server pagination; one is rendering policy, the other is data ownership.

## Related pages [#related-pages]

* [Choose a data mode](/docs/guides/choose-a-data-mode)
* [Data loading](/docs/concepts/data-loading)
* [Paginated Table](/docs/examples/paginated-table)
* [Infinite Scroll Table](/docs/examples/infinite-scroll-table)
* [Server helper API](/docs/reference/server-helper-api)


# Server helper API (https://react-datatable.com/docs/reference/server-helper-api)

Use this page when you want a contract-faithful in-memory helper for demos, fixtures, tests, or local examples. For a real production backend, implement the same wire contract against your database.

## What it exports [#what-it-exports]

```ts
import {
  runInMemoryDatatableQuery,
  type OnlineQueryInput,
  type OnlineQueryResponse,
  type OnlineTableRow,
  type OnlineGroupingSummary,
  type OnlineQueryStateInput,
  type OnlineNavigationMode,
} from "./react-datatable-server"
```

The package is intentionally small.

Its main job is to expose the online request/response contract plus one in-memory query implementation.

## Main helper [#main-helper]

### `runInMemoryDatatableQuery` [#runinmemorydatatablequery]

```ts
runInMemoryDatatableQuery<TData>({
  data,
  columns,
  input,
  getRowId,
}): Promise<OnlineQueryResponse<TData>>
```

This helper simulates an online data adapter against an in-memory array. Most apps do not need it in production. It is useful for demos, fixtures, tests, or edge cases where a separate in-browser query engine should drive online mode.

It applies:

* global search
* column filters
* sorting
* grouping
* page or offset slicing

against an in-memory array.

## Call shape [#call-shape]

```tsx
const response = await runInMemoryDatatableQuery({
  data: customers,
  columns,
  input,
  getRowId: (row) => row.id,
})
```

### `data` [#data]

Full in-memory dataset to query.

### `columns` [#columns]

`DatatableColumn<TData>[]` definitions used to interpret accessors, sorting functions, filter types, grouping specs, and static option domains.

### `input` [#input]

`OnlineQueryInput` contract from the online table surface.

See [Online API](/docs/reference/online-api).

### `getRowId` [#getrowid]

Stable row ID resolver.

## What the helper is good for [#what-the-helper-is-good-for]

Use it for:

* local demos
* repository examples
* fixtures
* integration tests
* contract validation while designing a real backend
* small internal tools where an in-memory dataset is genuinely enough

This is exactly why the examples can show online pagination and infinite loading without requiring a hosted service.

## Helper scope [#helper-scope]

The helper demonstrates the online request and response contract for demos, tests, contract validation, and small in-memory tools.

For production datasets, keep the same request/response contract but replace the helper with SQL, ORM, or service-layer queries that enforce your own tenant, permission, and audit rules.

## Type surface [#type-surface]

`react-datatable-server` re-exports a backend-friendly version of the online types.

```ts
type OnlineQueryStateInput = {
  limit: number
  filters: unknown[]
  sorting: Array<{ id: string; desc: boolean }>
  globalFilter: string
  grouping?: {
    columns: string[]
    showEmptyGroups?: boolean
  }
}
```

Important detail: the server helper keeps `filters` looser (`unknown[]`) than the client package.

That is deliberate. Treat incoming request bodies as untrusted input and validate them at your API boundary before mapping them into SQL or ORM logic.

## Behavior notes [#behavior-notes]

### Grouping support [#grouping-support]

The helper supports grouped online output by building structural `group-header` rows and, when needed, a full `grouping` summary.

### Empty groups [#empty-groups]

When grouping is active and `showEmptyGroups` is true, the helper can emit empty groups if the grouped column has a static option domain in `filterOptions.options`.

That makes it useful for reproducing the expected grouped-online contract in demos and tests.

### Infinite mode [#infinite-mode]

In infinite mode, the helper still treats `offset` as a data-row offset.

For grouped infinite output, it returns:

* the grouped slice for the requested data window
* `totalDataRows`
* full `totalRenderedRows`
* a full grouping summary

That mirrors the real online contract closely enough for UI development.

## When to replace it [#when-to-replace-it]

Replace the helper when:

* the dataset is too large to load into memory
* tenant or permission scope must be enforced in the database
* counts and facets must come from indexed backend truth
* the table must reflect live writes or streaming updates
* you need database-native performance for sorting, grouping, or filtering

## Minimal API-route pattern [#minimal-api-route-pattern]

```ts
export async function POST(request: Request) {
  const input = await request.json()

  // validate input here

  const result = await runInMemoryDatatableQuery({
    data: seededRows,
    columns,
    input,
    getRowId: (row) => row.id,
  })

  return Response.json(result)
}
```

Use this as a contract model. In production, swap `seededRows` and the helper call for your real query layer.

## Relationship to the examples [#relationship-to-the-examples]

The repository examples use this helper so you can inspect the online protocol without extra infrastructure.

See:

* [Paginated Table](/docs/examples/paginated-table)
* [Infinite Scroll Table](/docs/examples/infinite-scroll-table)

## Practical reminders [#practical-reminders]

* Keep `getRowId` stable.
* Keep authorization, tenant scope, and audit rules in your production query layer.
* Validate incoming `input` before trusting it in a real API route.
* Preserve the same `OnlineQueryInput` → `OnlineQueryResponse` contract when you replace the helper.

## Related pages [#related-pages]

* [Online API](/docs/reference/online-api)
* [Choose a data mode](/docs/guides/choose-a-data-mode)
* [Server query endpoint](/docs/guides/server-query-endpoint)


# Troubleshooting (https://react-datatable.com/docs/reference/troubleshooting)

Use this page when the table is already integrated but something feels wrong. Start with the symptom that is closest to what you see.

## First debugging step [#first-debugging-step]

Turn on debug logging while reproducing the issue.

```tsx
<Datatable tableKey="customers" debug />
```

That helps you distinguish a rendering problem from a state-loading, persistence, or online-query problem.

## The table renders unstyled or popovers look broken [#the-table-renders-unstyled-or-popovers-look-broken]

### Likely cause [#likely-cause]

Tailwind is not scanning the copied table source, or the required CSS variables are missing.

### Check [#check]

```css
@import "tailwindcss";

@source ".";
@source "./src/react-datatable";
```

Also make sure your theme exposes the variables used by the shipped UI, including:

* `--background`
* `--foreground`
* `--border`
* `--input`
* `--ring`
* `--popover`
* `--muted`
* `--primary`

### Usually fixes it [#usually-fixes-it]

* add the copied datatable source to Tailwind scanning
* copy or map the expected design-token variables
* verify your local wrapper did not drop the table stylesheet imports

## Online mode does not load data [#online-mode-does-not-load-data]

### Likely cause [#likely-cause-1]

The `online.query` function is throwing, returning the wrong response shape, or receiving unsupported filter/grouping input.

### Check [#check-1]

```tsx
<Datatable
  tableKey="customers"
  online={{
    mode: "pagination",
    queryKey: ["customers"],
    query: async (input) => {
      console.log(input)
      return fetchRows(input)
    },
  }}
/>
```

### Usually fixes it [#usually-fixes-it-1]

* log the query input and confirm the backend accepts the filter, sort, grouping, and pagination fields
* return `rows`, `totalDataRows`, `totalRenderedRows`, and `hasMore`
* set `supportedGroupingColumns` when only some columns can be grouped server-side

Local mode, saved views, URL sync, and copy links do not require a URL-state provider.

## Selection, preview, or saved views point at the wrong rows or columns [#selection-preview-or-saved-views-point-at-the-wrong-rows-or-columns]

### Likely cause [#likely-cause-2]

Row IDs or column IDs are unstable.

### Check [#check-2]

```tsx
<Datatable
  tableKey="customers"
  data={rows}
  columns={columns}
  getRowId={(row) => row.id}
/>
```

### Usually fixes it [#usually-fixes-it-2]

* use a real row identifier, not an array index
* keep column `id` values stable across renders and releases
* do not derive IDs from labels that product text may change later

Identity drift is one of the fastest ways to break selection, preview, persistence, grouping, and online grouping summaries all at once.

## Current-view persistence does not restore what you expected [#current-view-persistence-does-not-restore-what-you-expected]

### Likely cause [#likely-cause-3]

The wrong persistence scope is loading, or a higher-priority source is overriding it.

### Check [#check-3]

* `persistState.adapter` is configured
* `tableKey` is stable
* `workspaceId` and `userId` match the intended scope
* storage is available in the current browser context
* URL state or a saved view is not overriding the persisted state during initialization

### The precedence [#the-precedence]

The coordinated startup model loads state in layers. In practice, persisted state can still be overridden by later sources like selected views or accepted URL parameters.

### Usually fixes it [#usually-fixes-it-3]

* confirm the exact table scope keys
* clear stale persisted state when changing table identity
* check whether a saved default view is winning
* check whether `acceptUrlParams` is applying a one-time shared state on load

## A copied link works once, then the URL clears [#a-copied-link-works-once-then-the-url-clears]

### Likely cause [#likely-cause-4]

This is expected shareable-link behavior, not a bug.

When `urlSync` uses `enabled: false` with `acceptUrlParams: true`, the table reads the datatable params once and then removes them from the address bar.

### Usually fixes confusion [#usually-fixes-confusion]

* use this mode for one-time shared links
* use continuous `urlSync` if the URL should remain a live product surface
* document the difference for support and product teams

## URL sync is writing too many history entries or back/forward feels wrong [#url-sync-is-writing-too-many-history-entries-or-backforward-feels-wrong]

### Likely cause [#likely-cause-5]

`historyMode` does not match the page behavior you want.

### Check [#check-4]

* `historyMode: "push"` creates navigation entries as state changes
* `historyMode: "replace"` keeps the URL current without building a long browser history trail

### Usually fixes it [#usually-fixes-it-4]

* use `replace` for dashboards where URL state should stay current quietly
* use `push` when back/forward through table states is part of the product experience

## Shared links are too long to be practical [#shared-links-are-too-long-to-be-practical]

### Likely cause [#likely-cause-6]

The copied link contains a large table state directly in the URL.

### Usually fixes it [#usually-fixes-it-5]

* save the state as a named view instead of a URL
* reduce large filter payloads or overly wide shared state
* prefer current-view persistence or saved views for heavy internal workflows

## Online rows, totals, or grouping counts look wrong [#online-rows-totals-or-grouping-counts-look-wrong]

### Likely cause [#likely-cause-7]

The backend response does not match the online contract.

### Check [#check-5]

* `totalDataRows` counts matching data records
* `totalRenderedRows` includes structural rows like group headers
* `grouping` summary matches the same backend scope as `rows`
* `facets` are computed from the same filtered dataset as the returned rows

### Usually fixes it [#usually-fixes-it-6]

* keep tenant, permission, search, filters, grouping, and sorting in one backend-owned query scope
* do not compute facets from a broader or narrower dataset than the rows
* keep grouped infinite mode explicit about data-row offsets versus rendered-row counts

If route-prefetched `initialData` appears for the wrong query, re-check `initialDataQueryState`.

## Online grouping selections or persisted grouping values disappear [#online-grouping-selections-or-persisted-grouping-values-disappear]

### Likely cause [#likely-cause-8]

The current grouping state includes columns your backend does not support.

### Check [#check-6]

Set `supportedGroupingColumns` in the `online` config when only some groupings are allowed.

### Usually fixes it [#usually-fixes-it-7]

* declare the supported grouping columns explicitly
* let the table sanitize persisted or URL grouping state before it reaches the backend
* keep your server and docs aligned on which grouped views are actually supported

## Filters show the wrong options or filter chips do not match backend truth [#filters-show-the-wrong-options-or-filter-chips-do-not-match-backend-truth]

### Likely cause [#likely-cause-9]

Facet keys, filter types, or product-specific filter UI assumptions drifted away from the actual column contract.

### Check [#check-7]

* facet keys match column IDs exactly
* column `filterType` matches the UI you expect
* select-style filters receive option domains that match the actual backend data

### Usually fixes it [#usually-fixes-it-8]

* align facet response keys with column IDs
* keep `text`, `text-list`, `number`, and date filters on the documented UI path
* treat boolean, ID-list, and custom filters as product-owned extension surfaces unless you built the matching UI yourself

## Infinite scrolling feels jumpy or loads the wrong rows [#infinite-scrolling-feels-jumpy-or-loads-the-wrong-rows]

### Likely cause [#likely-cause-10]

Backend ordering is unstable, or pagination concepts are leaking into infinite mode.

### Check [#check-8]

* the backend ordering is deterministic
* tie-breakers exist when two rows sort equally
* `offset` is treated as a data-row offset
* `prefetchRows` is sized for how quickly users move through the list

### Usually fixes it [#usually-fixes-it-9]

* make the backend ordering stable for the full active query
* reset to the start of the result set when filters, search, sorting, or grouping changes
* keep virtualization concerns separate from online query semantics

## Virtualization shows misaligned rows, sticky-column glitches, or rough scrolling [#virtualization-shows-misaligned-rows-sticky-column-glitches-or-rough-scrolling]

### Likely cause [#likely-cause-11]

Rendered row heights are not predictable, or too much detail is being forced into the grid.

### Check [#check-9]

```tsx
<Datatable
  tableKey="customers"
  rowHeight={48}
  headerHeight={48}
  virtualization={{ mode: "viewport" }}
/>
```

### Usually fixes it [#usually-fixes-it-10]

* keep row and header heights predictable
* move long or multi-line detail into preview panels or detail routes
* tune overscan before changing deeper rendering assumptions
* keep sticky-column counts modest enough that horizontal scroll remains usable

## Grouping shows unexpected empty groups [#grouping-shows-unexpected-empty-groups]

### Likely cause [#likely-cause-12]

`showEmptyGroups` is enabled and the grouped column exposes a finite option domain.

### Usually fixes it [#usually-fixes-it-11]

* turn off `showEmptyGroups` if those zero-count buckets are not useful
* keep it on only when users genuinely need to see missing categories
* remember that online mode needs backend support for the same behavior

## After copying source updates, the table regressed [#after-copying-source-updates-the-table-regressed]

### Likely cause [#likely-cause-13]

A source refresh overwrote local adapters, theme mapping, or product-specific integrations.

### Usually fixes it [#usually-fixes-it-12]

Before shipping a copied update:

* compare your local edits against the copied source diff
* preserve adapter wiring, theme tokens, and product-specific wrappers
* re-test persistence, views, URL sync, online mode, and bulk actions together
* run the repository checks, not just a visual smoke test

## Related pages [#related-pages]

* [Getting started](/docs/quickstart/getting-started)
* [Component API](/docs/reference/component-api)
* [Online API](/docs/reference/online-api)
* [TypeScript types](/docs/reference/typescript-types)
* [State Lifecycle](/docs/concepts/state-lifecycle)


# TypeScript types (https://react-datatable.com/docs/reference/typescript-types)

Use this page when you already understand the feature surface and want the fastest route to the right exported type.

## Main package exports [#main-package-exports]

```ts
import type {
  DatatableProps,
  DatatableColumn,
  DatatableState,
  OnlineQueryInput,
  OnlineQueryResponse,
  OnlineTableRow,
  DataTableVirtualizationConfig,
  DataTableDisplayOptionsConfig,
  DataTableRowSelectionConfig,
  DataTableBulkActionsConfig,
  DataTableSelectionDescriptor,
} from "./react-datatable"
```

The package re-exports most application-facing contracts from `kit/src/react-datatable/types`.

## Top-level component types [#top-level-component-types]

### `DatatableProps<TData>` [#datatablepropstdata]

Main component prop contract.

Use this when you need the full surface for:

* `columns`
* `data` or `online`
* toolbar and display configuration
* row selection, preview, bulk actions, and keyboard behavior
* persistence, views, copy links, and URL sync
* virtualization and debug options

See [Component API](/docs/reference/component-api).

## Column and filter types [#column-and-filter-types]

### `DatatableColumn<TData, TValue = unknown>` [#datatablecolumntdata-tvalue--unknown]

Column-definition contract.

Use this when authoring columns, accessors, headers, widths, sorting/filtering behavior, grouping metadata, and cell rendering.

See [Column API](/docs/reference/column-api).

### Filter contracts [#filter-contracts]

Key exports from `filter.types.ts`:

* `FilterType`
* `ColumnFilter`
* `FilterPayload`
* `TextFilterPayload`
* `NumberFilterPayload`
* `DateFilterPayload`
* `BooleanFilterPayload`
* `TextListFilterPayload`
* `IdListFilterPayload`
* `FilterOptions`

Use these when you need to type custom filter state, server validation, or filter-aware product code.

## Online-query types [#online-query-types]

### `OnlineQueryInput` [#onlinequeryinput]

Union of:

* `InfiniteOnlineQueryInput`
* `PaginationOnlineQueryInput`

This is the backend request contract for online mode.

### `OnlineQueryResponse<TData>` [#onlinequeryresponsetdata]

Server response contract for online mode.

### `OnlineTableRow<TData>` [#onlinetablerowtdata]

Rendered online row union:

* `type: "group-header"`
* `type: "data"`

### `OnlineGroupingSummary` [#onlinegroupingsummary]

Counts metadata for grouped online mode.

### `OnlineConfig<TData>` [#onlineconfigtdata]

Top-level `online` prop contract used by `Datatable`.

See [Online API](/docs/reference/online-api).

## Table-state types [#table-state-types]

### `DatatableState` [#datatablestate]

Canonical Zustand-backed table state.

Includes:

* display toggles
* global search and column filters
* column order, visibility, and widths
* sorting
* row selection, active row, and preview row
* grouping and group expansion
* active saved view

### `DatatableRowSelectionState` [#datatablerowselectionstate]

Union of:

* `ExplicitRowSelectionState`
* `AllMatchingRowSelectionState`

Use this when your surrounding app needs to reason about loaded-row selection versus server-wide all-matching selection.

## Common config object types [#common-config-object-types]

These nested config contracts are useful when you split table configuration into reusable constants:

* `DataTableVirtualizationConfig`
* `DataTableAppliedStateConfig`
* `DataTableDisplayOptionsConfig`
* `DataTableColumnReorderingConfig`
* `DataTableRowSelectionConfig<TData>`
* `DataTableRowPresentationConfig<TData>`
* `DataTableKeyboardNavigationConfig`
* `DataTableRowActionsConfig<TData>`
* `DataTableRowPreviewConfig<TData>`
* `DataTableBulkActionsConfig<TData>`

These map directly to top-level `Datatable` props like `virtualization`, `displayOptions`, `selection`, `rowPresentation`, `keyboardNavigation`, `rowActions`, `rowPreview`, and `bulkActions`.

## Bulk-action types [#bulk-action-types]

Use these when you build product-owned bulk workflows:

* `DataTableBulkAction<TData>`
* `DataTableBulkActionItem<TData>`
* `DataTableBulkActionContext<TData>`
* `DataTableBulkActionStep`
* `DataTableBulkActionStepContext<TData>`
* `DataTableBulkServerActionRequest`
* `DataTableSelectionDescriptor`

These types are especially important when the UI selects *all matching* rows and the backend must resolve the final target set.

## Persistence and views types [#persistence-and-views-types]

These are not all re-exported from the top-level package, but they are key source contracts when you implement adapters.

### Table-state persistence [#table-state-persistence]

From `persistence/table-state-adapter.types.ts`:

* `PersistedTableState`
* `PersistedTableStateSnapshot`
* `TableStateAdapter`
* `TableStateAdapterConfig`

`PersistedTableStateSnapshot` is the direct stored snapshot:

```ts
interface PersistedTableStateSnapshot {
  version: 1
  query: {
    filters: ColumnFilter[]
    sorting: SortingState
    globalFilter: string
    grouping: {
      columns: string[]
      showEmptyGroups: boolean
      expansion: {
        defaultExpanded: boolean
        overrides: Record<string, boolean>
      }
    } | null
    filterMode: "AND" | "OR"
  }
  presentation: {
    showColumnHeaders: boolean
    stickyColumnsCount: number
    showHorizontalLines: boolean
    showVerticalLines: boolean
    showOrderingBadge: boolean
    columnOrder: string[]
    columnVisibility: Record<string, boolean>
    columnWidths: Record<string, number>
    activeViewId: string | null
  }
}
```

Use these for current-view persistence adapters.

### Saved views [#saved-views]

From `persistence/datatable-view-adapter.types.ts`:

* `DatatableView`
* `DatatableViewState`
* `DatatableViewAdapter`
* `DatatableViewAdapterConfig`
* `adapterSupportsSharing()`
* `adapterSupportsDefaults()`

`DatatableViewState` is the direct saved-view state payload:

```ts
interface DatatableViewState {
  version: 1
  query: BackendQueryState
  presentation: BackendPresentationState
}
```

A `DatatableView` returned from an adapter includes:

```ts
{
  id: string
  name: string
  state: DatatableViewState
  isShared: boolean
  isUserDefault: boolean
  isWorkspaceDefault: boolean
  createdBy: string
  createdAt: Date
  updatedAt: Date
  workspaceId?: string
}
```

Use these for named-view storage, sharing, and default-view behavior.

If you need the same shape from `react-datatable-server`, use `DatatableViewState` there too.

## Server helper types [#server-helper-types]

From `react-datatable-server`:

* `OnlineNavigationMode`
* `OnlineQueryStateInput`
* `OnlineQueryInput`
* `OnlineTableRow<TData>`
* `OnlineGroupingSummary`
* `OnlineQueryResponse<TData>`

These mirror the online contract while keeping backend-facing filter typing looser for API-boundary validation.

See [Server helper API](/docs/reference/server-helper-api).

## Practical lookup guide [#practical-lookup-guide]

Use:

* `DatatableProps` when configuring the whole component
* `DatatableColumn` when defining columns
* `OnlineQueryInput` and `OnlineQueryResponse` when writing backend queries
* `DatatableState` when working with internal table state
* `PersistedTableState` when implementing current-view persistence
* `DatatableView` when implementing saved views
* `DataTableSelectionDescriptor` and bulk-action types when executing selection-driven workflows

## Related pages [#related-pages]

* [Component API](/docs/reference/component-api)
* [Column API](/docs/reference/column-api)
* [Online API](/docs/reference/online-api)
* [Server helper API](/docs/reference/server-helper-api)


# Why react-datatable (https://react-datatable.com/docs/why-react-datatable)

`react-datatable` exists for teams that want a production-shaped table fast, but do not want to give up source ownership once product requirements get specific.

<ImageZoom src="/docs-media/overview/why-react-datatable-product-hero.png" alt="A production-shaped table with search, filters, grouping, display controls, owner context, tags, and revenue columns visible together." className="my-7 w-full rounded-xs border-0" />

## The problem it solves [#the-problem-it-solves]

Most table projects start in one of two places:

* a **headless library** gives you strong primitives, but you still have to assemble the real product behavior around them
* a **closed grid package** gives you many features, but changing the shipped UI or interaction model becomes expensive

That tradeoff gets painful once a table stops being a demo and becomes part of the product. Search affects filters. Filters affect selection. Views need to capture table state. Shared links need to reproduce that state. Preview panels, grouping, bulk actions, and online loading all need to cooperate.

`react-datatable` is meant for that middle ground: you get the integrated behavior up front, and you still own the source.

## Why teams pick it [#why-teams-pick-it]

### 1. It starts from a working system, not a feature checklist [#1-it-starts-from-a-working-system-not-a-feature-checklist]

In the current source, `DataTableBody` already coordinates the toolbar, applied state bar, virtualized grid, view columns affordance, bulk action island, floating preview, and pagination or loading controls. `DataTableToolbar` already organizes quick search, filters, views, display options, and copy-link controls into one product surface.

That matters because real table work is usually about how features interact, not whether each feature exists in isolation.

### 2. You can change the shipped UI directly [#2-you-can-change-the-shipped-ui-directly]

Because the table lives as normal React source in your repository, you can:

* restyle or replace toolbar controls
* change cell rendering and row presentation
* adapt menus, dialogs, icons, and copy to your product
* keep the state and behavior contracts while changing presentation

This is a better fit for teams that expect their table UI to become product-specific rather than staying generic forever.

### 3. It works well with coding agents [#3-it-works-well-with-coding-agents]

Agents are much more effective when they can inspect local source, types, examples, and tests. With `react-datatable`, an agent can follow existing patterns to add a column, wire online mode, customize a preview panel, or update persistence behavior without first inventing the whole table architecture.

<Callout title="Why this matters in practice">
  You spend less time asking an agent to compose a complete datatable from primitives, and more time asking for focused product changes on top of working source.
</Callout>

### 4. It leaves room to grow [#4-it-leaves-room-to-grow]

The same docs corpus and source tree already support several common stages of table maturity:

* local data for a first internal tool or admin screen
* paginated or infinite online mode for server-owned data
* richer workflows like grouping, bulk actions, saved views, and shareable state
* deeper UI customization once the table becomes a product surface

That makes it a strong fit when you know the table will get more important over time.

## What it is better than [#what-it-is-better-than]

`react-datatable` is usually a better choice than starting from primitives when:

* you need product behavior quickly, not just rows and columns
* you want one coherent system for filtering, sorting, views, sharing, and preview
* you expect source-level customization to be normal
* you want agent-friendly local source instead of a black box

It is usually a better choice than a closed grid when:

* the shipped UI will need meaningful product-specific changes
* you want to own the implementation details that matter to your UX
* you do not want to wait on vendor APIs or extension points for every customization

## When not to choose it [#when-not-to-choose-it]

`react-datatable` is not the right answer for every table.

Skip it when:

* you only need a simple static table
* you need spreadsheet-style editing first
* you are not building in React
* you do not want to copy and maintain source in your app
* a package with strict vendor boundaries is a better organizational fit for your team

## How this page fits the rest of the docs [#how-this-page-fits-the-rest-of-the-docs]

If you want a first working table next, start with [Installation](/docs/installation), then render static rows in [Getting started](/docs/quickstart/getting-started).