[#st_tablebodycell-]
The `` element that surrounds the cell value or custom `Cell` render.
##### \ [#st_tablebodycellvalue-]
Renders the value of a cell. This is a popular component to use as an alternative to TanStack Table's `flexRender` method. It renders everything inside of the ``, but not the ` ` itself.
##### \ [#st_tablebodyrowgrabhandle-]
A button for grabbing a row for dragging.
##### \ [#st_tablebodyrowpinbutton-]
A button or buttons for pinning a row.
#### TableFooter Components [#tablefooter-components]
[View TableFooter Components Source Code on GitHub](https://github.com/anindosarker/shadcn-table/tree/master/packages/shadcn-table/src/components/ui/shadcn-table/footer)
##### \ [#st_tablefooter-]
The `` element, and all of the table footer rows.
##### \ [#st_tablefooterrow-]
The `` element that contains all of the table footer cells in a row.
##### \ [#st_tablefootercell-]
The `` element that surrounds the cell value or custom `Footer` render.
#### Input Components [#input-components]
[View Input Components Source Code on GitHub](https://github.com/anindosarker/shadcn-table/tree/master/packages/shadcn-table/src/components/ui/shadcn-table/inputs)
##### \ [#st_editcelltextfield-]
The textfield component for editing a cell value that can either show in a modal or table cell.
##### \ [#st_globalfiltertextfield-]
The search textfield component for global filtering.
##### \ [#st_filtertextfield-]
The textfield component for filtering a column. A somewhat comprehensive component that can be a textfield, select, multi-select, or date picker.
##### \ [#st_filtercheckbox-]
The checkbox component for filtering a column by boolean values.
##### \ [#st_filterrangeslider-]
The range slider component for filtering a column by a range of numbers.
##### \ [#st_filterfilterrangefields-]
A Container component that will render two ST_FilterTextField components for filtering in a range (min and max).
##### \ [#st_selectcheckbox-]
A checkbox component for selecting a row or selecting all rows from the table header.
# ST Hooks (/docs/api/st-hooks)
table.{/* or maybe here */}}> ,
},
], []);
const table = useShadcnTable({
columns,
data,
renderTopToolbarCustomActions: ({ table }) => table{/* or maybe here */}}>Click Me ,
});
const someEventHandler = () => {
table. //call any of the table instance methods here
};
return Examples **
# Aggregation and Grouping Example (/docs/examples/aggregation-and-grouping)
Grouping and Aggregation features are usually hard to implement, but ST (thanks to [TanStack Table](https://tanstack.com/table/latest/docs/framework/react/guide/grouping)) makes it easy. Once enabled, simply click the vertical ellipses (⋮) icon for the column you want to group by and select **Group by (column name)**.
You can group by a single column or multiple columns at a time. Then, you can run aggregations on grouped columns to calculate totals, averages, max, min, etc.
The Grouping and Aggregation features work hand in hand with the Expanding and Sorting features. Try grouping by various columns in the example below and sorting by the aggregated columns, such as "age" or "salary".
See the [Column Grouping](/docs/features/column-grouping) and [Aggregation](/docs/features/aggregation) docs for more information.
Examples **
# Basic Example (/docs/examples/basic)
Shadcn Table enables client-side sorting, filtering, search, pagination, column hiding, and more by default. These features can easily be disabled or customized further, but here is a showcase of their default behavior. Be sure to check out a more [Advanced Example](/docs/examples/advanced) to see how more features can be customized.
Examples **
# Chart Detail Panel Example (/docs/examples/chart-detail-panel)
The detail panel features can be used for a variety of purposes. In this example, we are integrating the new [Recharts](https://recharts.org/) library to display an expandable line chart for each row.
You could, of course, use any charting library that you prefer, but using Recharts will give you a consistent look and feel with Shadcn Table and any other shadcn/ui components you may be using.
Examples **
# Column Grouping Example (/docs/examples/column-grouping)
Shadcn Table has a few different UI options and behaviors for displaying grouped columns. See the [Column Grouping Guide](/docs/guides/column-grouping) to learn more.
Examples **
# Column DnD Ordering Example (/docs/examples/column-ordering)
Shadcn Table has built-in support for column drag and drop re-ordering. Learn more about column ordering in the [Column Ordering Feature Guide](/docs/guides/column-ordering-dnd).
Examples **
# Column Pinning Example (/docs/examples/column-pinning)
Shadcn Table has an easy-to-enable column pinning feature. Columns can be pinned to the left or right of the table, and the column will be frozen in place while the rest of the table scrolls horizontally. See the [Column Pinning Feature Guide](/docs/guides/column-pinning) for more information.
Examples **
# Column Virtualization Example (/docs/examples/column-virtualization)
Shadcn Table has a built-in column virtualization feature (via [`@tanstack/react-virtual`](https://tanstack.com/virtual/v3)) that allows you to render a large number of columns without major performance issues that you would normally see with a large number of DOM elements.
Try out the performance of the table below with **500 columns**! Filtering, Search, and Sorting also maintain usable performance.
Be sure to also check out the full [virtualization feature guide docs](/docs/guides/virtualization) to learn about both Row and Column Virtualization.
> NOTE: You should only enable row virtualization if you have a large number of rows or columns. Depending on the size of the table, if you are rendering fewer than a couple dozen rows at a time, you will actually just be adding extra overhead to the table renders. Virtualization only becomes necessary when you have over 50 rows or so at the same time with no pagination or dozens of columns.
Examples **
# Custom Filter UI Example (/docs/examples/custom-filter-ui)
Shadcn Table supports rendering your own custom filter UI. This can be useful if you want to render your filters in a custom top toolbar, sidebar, or drawer. Learn more in the full [Column Filtering Feature Guide](/docs/guides/column-filtering).
Examples **
# Custom Headless Example (/docs/examples/custom-headless)
For advanced use cases where you want to be in 100% control of your UI components, you can use Shadcn Table in a more headless way, kind of like how you would use [stock TanStack Table](https://tanstack.com/table/latest/docs/framework/react/examples/basic-use-table).
The power and flexibility here is almost limitless, as you can combine some already built-in Shadcn Table components alongside your own custom components. For the ST components to work properly, all you need to do is pass the `table` object returned from the `useShadcnTable` hook.
Examples **
# Customized Grouping Example (/docs/examples/customized-grouping)
Here is an advanced example showing off various ways in which the expand column can be customized with column grouping features. See the [Column Grouping Guide](/docs/guides/column-grouping) to learn more.
Examples **
# Detail Panel Example (/docs/examples/detail-panel)
Shadcn Table has multiple types of "expanding" row features. In its simplest form, you can use the `renderDetailPanel` option to render a component when a row is clicked. This is useful for showing additional information about a row, such as a list of nested data. Learn more in the [Detail Panel Feature Guide](/docs/guides/detail-panel).
Examples **
# Dynamic Columns Example (/docs/examples/dynamic-columns)
This example shows how to generate column definitions dynamically from remote data after first render using TanStack Query. You may need to manage the `columnOrder` state manually if doing this.
Examples **
# Editing CRUD Inline Cell Example (/docs/examples/editing-crud-inline-cell)
Full CRUD (Create, Read, Update, Delete) functionality can be easily implemented with Shadcn Table, with a combination of editing, toolbar, and row action features.
This example below uses the inline [`"cell"`](/docs/guides/editing#row-editing-mode) editing mode, which allows you to edit a single cell at a time. Hook up your own event listeners to save the data to your backend.
Check out the other editing modes down below, and the [editing guide](/docs/guides/editing) for more information.
Examples **
# Editing CRUD Inline Row Example (/docs/examples/editing-crud-inline-row)
Full CRUD (Create, Read, Update, Delete) functionality can be easily implemented with Shadcn Table, with a combination of editing, toolbar, and row action features.
This example below uses the inline [`"row"`](/docs/guides/editing#row-editing-mode) editing mode, which allows you to edit a single row at a time with built-in save and cancel buttons.
Check out the other editing modes down below, and the [editing guide](/docs/guides/editing) for more information.
Examples **
# Editing CRUD Inline Table Example (/docs/examples/editing-crud-inline-table)
Full CRUD (Create, Read, Update, Delete) functionality can be easily implemented with Shadcn Table, with a combination of editing, toolbar, and row action features.
This example below uses the inline [`"table"`](/docs/guides/editing#row-editing-mode) editing mode, which allows you to edit a single cell at a time, but all rows are always in an open editing state. Hook up your own event listeners to save the data to your backend.
Check out the other editing modes down below, and the [editing guide](/docs/guides/editing) for more information.
Examples **
# Editing CRUD Tree Example (/docs/examples/editing-crud-tree)
Editing nested row data can be challenging. In this example, rows can be expanded to show sub rows, and editing and creating new rows can be done at any level.
Adding a new blank row in the exact row index position is now possible with the new `positionCreatingRow` table option.
This example also shows some complex client-side optimistic updates, where the table data is updated immediately after a valid user action.
Examples **
# Editing CRUD Example (/docs/examples/editing-crud)
Full CRUD (Create, Read, Update, Delete) functionality can be easily implemented with Shadcn Table, with a combination of editing, toolbar, and row action features.
This example below uses the default [`"modal"`](/docs/guides/editing#modal-editing-mode) editing mode, where a dialog opens up to edit 1 row at a time.
Check out the other editing modes down below, and the [editing guide](/docs/guides/editing) for more information.
Examples **
# Expanding Parsed Tree Example (/docs/examples/expanding-tree-flat-parse)
Shadcn Table supports showing rows in a expanding tree structure and parsing them from a flat data structure with the `getSubRows` option. Learn more about how to customize this in the [expanding sub-rows feature guide](/docs/guides/expanding-sub-rows).
Examples **
# Expanding Tree Example (/docs/examples/expanding-tree)
Shadcn Table supports showing rows in a expanding tree structure. This example is the **_simplest_** implementation of this feature where each row of data potentially has a special `subRows` property that contains an array of sub rows. You don't have to follow this exact structure, but this is how ST will expect to find your sub rows by default.
Learn more about how to customize this in the [expanding sub-rows feature guide](/docs/guides/expanding-sub-rows).
Examples **
# CSV Export Example (/docs/examples/export-csv)
Shadcn Table does not have a data exporting feature built in. However, you can easily integrate your own exporting feature, if desired.
In the example below, `export-to-csv` is connected to some export buttons in the top toolbar. If you need to export in Excel or PDF format, there are a variety of NPM packages that can be used to export in these formats.
Examples **
# PDF Export Example (/docs/examples/export-pdf)
Shadcn Table does not have a data exporting feature built-in. However, you can easily integrate your own exporting features.
In the example below, `jspdf` and `jspdf-autotable` are connected to some export buttons in the top toolbar to export table rows to a PDF file that can be downloaded.
Examples **
# Faceted Values Example (/docs/examples/faceted-values)
Shadcn Table can scan your data and automatically generate filter autocomplete suggestions, filter select options, or min and max values for your column filters. This is made possible by the faceted values feature from TanStack Table. Learn more in the full [Column Filtering Feature Guide](/docs/guides/column-filtering).
Examples **
# Filter Switching Example (/docs/examples/filter-switching)
Shadcn Table supports letting users switch between multiple filter modes. Learn more in the full [Column Filtering Feature Guide](/docs/guides/column-filtering).
Examples **
# Filter Variants Example (/docs/examples/filter-variants)
Shadcn Table not only has filtering built in, but it also has a lot of different filter variants that take care of a lot of the heavy lifting for you. Text filters, date filters, range filters, range slider filters, and more are all built in and ready to use. There is much more you can do to customize the behavior of filtering, so be sure to check out the full [Column Filtering Feature Guide](/docs/guides/column-filtering) for more information.
Examples **
# Examples (/docs/examples)
## Quick Examples [#quick-examples]
item.href === '/docs/examples').items}
/>
# Infinite Scrolling Example (/docs/examples/infinite-scrolling)
An infinite scrolling table is a table that streams data from a remote server as the user scrolls down the table. This works great with large datasets, just like our [Virtualized Example](/docs/examples/virtualized), except here we do not fetch all of the data at once upfront. Instead, we just fetch data a little bit at a time, as it becomes necessary.
Using a library like [`@tanstack/react-query`](https://tanstack.com/query/v4) makes it easy to implement an infinite scrolling table in Shadcn Table with the `useInfiniteQuery` hook.
Enabling the virtualization feature is actually optional here but is encouraged if the table will be expected to render more than 100 rows at a time.
Examples **
# Lazy Detail Panel Example (/docs/examples/lazy-detail-panel)
Fetching the additional data for the detail panels only after the user clicks to expand the row can be a good way to improve performance, and it is pretty easy to implement in Shadcn Table.
It's even easier if you are using [React Query.](https://tanstack.com/query/latest) In this example, react query is used to fetch the data for the detail panel, but only after the user clicks to expand the row. The data is also cached for a certain period of time so that when the detail panel is closed and reopened, the data is already available and won't need to be re-fetched.
Examples **
# Lazy Sub-Rows Example (/docs/examples/lazy-sub-rows)
If you have a ton of nested data that you want to display, but you don't want to fetch it all up front, you can set up Shadcn Table to only fetch the sub-rows data when the user expands the row.
There are quite a few ways in which you could implement fetching sub-rows lazily. This example is just one way to do it.
This example combines concepts from the [React Query Example](/docs/examples/react-query) and the [Expanding Parsed Tree Example](/docs/examples/expanding-tree-flat-parse).
Examples **
# Minimal Example (/docs/examples/minimal)
Shadcn Table gives you a lot out of the box, but it's also easy to turn off any features that you do not need.
Every feature has an `enable...` table option that let's you turn it on or off.
For example, you can turn off sorting or hide the top or bottom toolbars if you want.
Examples **
# Popover Filters Example (/docs/examples/popover-filters)
Shadcn Table supports displaying column filters in other ways than in the default sub-header location. This example shows how to only display column filters when the user clicks on the filter icon in the header and then display the filters in a popover. Learn more in the full [Column Filtering Feature Guide](/docs/guides/column-filtering).
Examples **
# React Query Example (/docs/examples/react-query)
This is just like the [Remote Data Fetching Example](/docs/examples/remote), but react-query is used to simplify all the state management of the fetching and loading of data.
For a step-by-step build of this pattern with a service, a query hook and a reusable state hook, read the [Building Production-Ready Tables](/docs/guides/production-ready-tables) guide.
[React Query](https://tanstack.com/query/v4) is by far the best way to fetch remote data in React. It has features like caching, refetching, polling, pagination, and more that work together very well with table logic as seen in this example.
Also, be sure to check out the [Virtualized Example](/docs/examples/virtualized), which shows off the use of another TanStack library, [React Virtual](https://tanstack.com/virtual/v3), to render thousands of rows at once while still maintaining great performance.
Examples **
# Remote Data Fetching Example (/docs/examples/remote)
You will most likely be using a remote data source for your table, which is fully supported. Here is an example of data being fetched from a remote server but also filtered, paginated, and sorted on the server.
Also, be sure to check out the [React Query Example](/docs/examples/react-query), which is very similar to this one, except it uses react-query to simplify much of the state management needed for fetching data, so that you don't need to fetch from a `useEffect` hook.
Examples **
# Row Dragging Example (/docs/examples/row-dragging)
Shadcn Table has built-in support row drag and drop features that can be used in a variety of ways. Learn more about column ordering in the [Row Ordering/DnD Feature Guide](/docs/guides/row-ordering-dnd).
Examples **
# Row DnD Ordering Example (/docs/examples/row-ordering)
Shadcn Table has built-in support for row drag and drop re-ordering. Learn more about column ordering in the [Row Ordering Feature Guide](/docs/guides/row-ordering-dnd).
Examples **
# Row Virtualization Example (/docs/examples/row-virtualization)
Shadcn Table has a built-in row virtualization feature (via [`@tanstack/react-virtual`](https://tanstack.com/virtual/v3)) that allows you to render a large number of rows without major performance issues that you would normally see with a large number of DOM elements.
Try out the performance of the table below with **10,000 rows**! Filtering, Search, and Sorting also maintain usable performance.
Be sure to also check out the full [virtualization feature guide docs](/docs/guides/virtualization) to learn about both Row and Column Virtualization.
> NOTE: You should only enable row virtualization if you have a large number of rows or columns. Depending on the size of the table, if you are rendering fewer than a couple dozen rows at a time, you will actually just be adding extra overhead to the table renders. Virtualization only becomes necessary when you have over 50 rows or so at the same time with no pagination or dozens of columns.
Examples **
# Static Row Pinning Example (/docs/examples/static-row-pinning)
Shadcn Table has the ability to pin rows and keep them in view while scrolling. In this example, when rows are pinned, they will be pinned statically to either the top or bottom of the table. Learn more about row pinning in the [Row Pinning Feature Guide](/docs/guides/row-pinning).
Examples **
# Sticky Header Example (/docs/examples/sticky-header)
Shadcn Table allows you to easily make the header and footer sticky while scrolling. See the [Sticky Header Feature Guide](/docs/guides/sticky-header) for more information.
Examples **
# Sticky Row Pinning Example (/docs/examples/sticky-row-pinning)
Shadcn Table has the ability to pin rows and keep them in view while scrolling. In this example, when rows are pinned, they will initially appear to stay in place, but when the user scrolls up or down, the rows will stick to the top or bottom of the table. Learn more about row pinning in the [Row Pinning Feature Guide](/docs/guides/row-pinning).
Examples **
# Sticky Row Selection Example (/docs/examples/sticky-row-selection)
Shadcn Table has the ability to pin rows as they are selected and keep them in view while scrolling. In this example, when rows are selected, they will initially appear to stay in place, but when the user scrolls up or down, the selected rows will stick to the top or bottom of the table. Learn more about row pinning in the [Row Pinning Feature Guide](/docs/guides/row-pinning).
Examples **
# Virtualized Example (/docs/examples/virtualized)
Shadcn Table has a built-in virtualization features (via [`@tanstack/react-virtual`](https://tanstack.com/virtual/v3)) that allows you to render a large number of rows or columns without major performance issues that you would normally see with a large number of DOM elements.
Try out the performance of the table below with **10,000 rows** and over a dozen columns! Filtering, Search, and Sorting also maintain usable performance.
Be sure to also check out the full [virtualization feature guide docs](/docs/guides/virtualization) to learn about both Row and Column Virtualization.
> NOTE: You should only enable row virtualization if you have a large number of rows or columns. Depending on the size of the table, if you are rendering fewer than a couple dozen rows at a time, you will actually just be adding extra overhead to the table renders. Virtualization only becomes necessary when you have over 50 rows or so at the same time with no pagination or dozens of columns.
Examples **
# AI Agent Setup (/docs/getting-started/agents)
### Ask your agent [#ask-your-agent]
- ` address works on either base.
```bash
pnpm dlx shadcn@latest registry add @st=https://www.shadcn-table.com/r/{style}/{name}.json
pnpm dlx shadcn@latest add @st/shadcn-table
```
GitHub fallback when the site is unreachable: `anindosarker/shadcn-table/shadcn-table` (Radix UI) and `anindosarker/shadcn-table/shadcn-table-base` (Base UI).
### Skill [#skill]
The same file installs as a skill, so the agent knows the table before you ask:
```bash
npx skills add anindosarker/shadcn-table
```
### Docs as markdown [#docs-as-markdown]
- [`/llms.txt`](/llms.txt): index of all pages
- [`/llms-full.txt`](/llms-full.txt): all pages in one file
- Any page: its path under `/llms.mdx/docs` plus `/content.md`, for example [`/llms.mdx/docs/api/table-options/content.md`](/llms.mdx/docs/api/table-options/content.md). "Copy page" in the page bar copies the same text.
### Project rules [#project-rules]
For `CLAUDE.md` or `AGENTS.md` when the skill is not installed:
```md
## shadcn-table
- Data table: components/ui/shadcn-table (from the shadcn registry, edit freely).
- Before changing table options read /llms.mdx/docs/api/table-options/content.md
on the docs site. Column options: /llms.mdx/docs/api/column-options/content.md.
- `data` and `columns` given to useShadcnTable must be stable
(useMemo, useState or module scope).
- Reinstall: pnpm dlx shadcn@latest add https://www.shadcn-table.com/r/
### Initialize shadcn/ui [#initialize-shadcnui]
Skip this if the project already uses shadcn/ui. The table needs shadcn/ui on the Radix UI or Base UI base, Tailwind CSS v4 and React 18 or newer; React Aria is not supported. It is built on TanStack Table v9 (`@tanstack/react-table` 9.3.1 is installed with it); a project still on TanStack Table v8 needs the [v9 migration](/docs/getting-started/migrating-v1) first. Pick your base with the Radix UI | Base UI tabs: the switch in the header does the same for the whole site, the examples included.
### Add shadcn-table [#add-shadcn-table]
Copies the table source into `components/ui/shadcn-table/` and installs the shadcn/ui parts and npm packages it needs, in the edition for the selected base. Run it again with `--overwrite` to update.
### Import [#import]
```tsx
import { ShadcnTable, useShadcnTable } from '@/components/ui/shadcn-table';
```
Columns, data and the hook: [Usage](/docs/getting-started/usage). Letting an agent do all of this: [AI Agent Setup](/docs/getting-started/agents). Every [example](/docs/examples) renders, shows its source and installs for the selected base.
# Migrating to v1 (TanStack Table v9) (/docs/getting-started/migrating-v1)
shadcn-table v1 is built on TanStack Table v9. The table keeps its own option names (`enableRowPinning`, `st*Props`, `renderDetailPanel`, ...); where TanStack renamed something, the table and its `ST_*` types follow TanStack, with no aliases for the old names. Update with the install command and `--overwrite`, then apply the changes below to your own code. TanStack's own list is in the [TanStack Table v9 migration guide](https://tanstack.com/table/latest/docs/framework/react/guide/migrating).
### Dependency [#dependency]
- `@tanstack/react-table` 9.3.1 is required (it brings `@tanstack/table-core` 9.3.1, `@tanstack/react-store` and `@tanstack/store` 0.11.2). The install command updates it; a project that pins v8 elsewhere has to move to v9, TanStack Table v8 is no longer supported.
### Renamed names [#renamed-names]
| v0.x (TanStack Table v8) | v1 (TanStack Table v9) |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `table.getState()` | `table.state` (`ST_TableState`: the TanStack slices plus `density`, `isFullScreen`, `creatingRow`, ... in one object) |
| column option `sortingFn` | `sortFn` |
| table option `sortingFns` | `sortFns` |
| type `ST_SortingFn`, registry `ST_SortingFns` | `ST_SortFn`, `ST_SortFns` |
| `@/components/ui/shadcn-table/fns/sortingFns` | `@/components/ui/shadcn-table/fns/sortFns` |
| state `columnSizingInfo`, type `ST_ColumnSizingInfoState` | `columnResizing`, `ST_ColumnResizingState` |
| `table.setColumnSizingInfo`, option `onColumnSizingInfoChange` | `table.setColumnResizing`, `onColumnResizingChange` |
| `columnPinning: { left, right }` | `columnPinning: { start, end }` (logical sides; `start` is left in LTR) |
| `column.pin('left' \| 'right' \| false)` | `column.pin('start' \| 'end' \| false)`, `column.getIsPinned()` returns `'start' \| 'end' \| false` (new type `ST_ColumnPinningPosition`) |
| `table.getLeftLeafColumns()`, `table.getRightLeafColumns()` | `table.getStartLeafColumns()`, `table.getEndLeafColumns()` |
| every other `Left`/`Right` method (`getLeftVisibleLeafColumns`, `getLeftTotalSize`, `row.getLeftVisibleCells`, ...) | the `Start`/`End` name; `column.getStart()`, `getAfter()`, `getIsFirstColumn()`, `getIsLastColumn()`, `getIndex()` take `'start' \| 'end' \| 'center'` |
| `table.getPaginationRowModel()`, `table.getPrePaginationRowModel()` | `table.getPaginatedRowModel()`, `table.getPrePaginatedRowModel()` |
### Row selection [#row-selection]
- The `enableBatchRowSelection` table option is removed. Shift-click range selection is TanStack's `enableRowRangeSelection` (default `true`); `isRowRangeSelectionEvent` customises which events count as a range selection.
- `table.refs.lastSelectedRowId` is removed (TanStack keeps the range anchor internally). `getST_RowSelectionHandler({ row, table })` no longer reads `staticRowIndex` (it is still accepted in the props type).
- `table.getIsSomeRowsSelected()`, `table.getIsSomePageRowsSelected()` and `row.getIsSomeSelected()` now mean "at least one" (the all-selected case included), per TanStack. The library gates its own indeterminate checkboxes with the matching `getIsAll*` check; do the same when one of these drives an indeterminate state in your code: `table.getIsSomeRowsSelected() && !table.getIsAllRowsSelected()`.
### Aggregation and the function registries [#aggregation-and-the-function-registries]
- Custom aggregation functions are v9 definitions: `constructAggregationFn({ aggregate: (context) => ..., merge? })` objects instead of `(columnId, leafRows, childRows)` callables. `ST_AggregationFn` is a definition or a name; `ST_AggregationFns.*` are definitions (call `.aggregate(context)`). A string `aggregationFn`, including names from the `aggregationFns` table option, is resolved by the library; an `aggregationFn` array still yields an array of results.
- The `filterFns`, `sortFns` and `aggregationFns` table options are typed by the library: `Record>`, `Record>` and `Record>`. The built-in registries live on the static features object; custom names are resolved by name.
- `ST_FilterFns.*` and `ST_SortFns.fuzzy` have v9 signatures (filter functions generic over the features with an optional `addMeta`; the fuzzy sort is built with `constructSortFn`).
### Table instance and types [#table-instance-and-types]
- New exports `stFeatures` and `ST_Features` (`utils/tanstack.features.ts`, also from the index): the `tableFeatures({...})` object with all 15 features, 8 row models and 3 registries. Use `createColumnHelper()` or TanStack types as `Column`; the public `ST_*` types keep their `` and `` signatures.
- `ST_TableInstance` is built on `ReactTable>`: `table.store`, `table.atoms`, `table.baseAtoms`, `table.Subscribe` and `table.FlexRender` are available.
- `ST_TableOptions` no longer accepts `features`, `onStateChange` or the `get*RowModel` options; the row models and `features` are set by the library.
- `ST_VisibilityState` now aliases TanStack's `ColumnVisibilityState` (same shape); `ST_ColumnResizingState` aliases TanStack's `columnResizingState`.
- `initialState.columnPinning` may still be partial (`{ start }` or `{ end }` alone); the library fills the missing side with `[]` because v9 does not. The `state.columnPinning` and `rowPinning` objects need both sides (`{ start: [], end: [...] }`, `{ top: [...], bottom: [] }`), and `rowSelection` only holds `true` entries (`Record`).
# Usage (/docs/getting-started/usage)
A first table in four steps. It will not cover all features of the library, but it is the shape every example builds on. [Install](/docs/getting-started/install) first.
### Import [#import]
```tsx
import {
ShadcnTable,
useShadcnTable,
} from '@/components/ui/shadcn-table';
```
`ShadcnTable` renders the table. `useShadcnTable` is the hook that takes the columns, the data and every other table option.
The install put the table in `components/ui/shadcn-table/` (edit anything), the shadcn/ui parts it uses in `components/ui/`, and the packages `@tanstack/react-table`, `@tanstack/react-virtual`, `@tanstack/match-sorter-utils`, `highlight-words`, `class-variance-authority`, `lucide-react` and `radix-ui` in your dependencies. English is the only locale installed; the others are separate items, see [Localization](/docs/guides/localization).
### Define the data [#define-the-data]
An array of objects whose keys match the accessors in your column definitions. Flat objects are easiest; nested data works with a little more column setup.
```jsx
//must be memoized or stable (useState, useMemo, defined outside of the component, etc.)
const data = [
{
name: 'John', // key "name" matches `accessorKey` in ColumnDef down below
age: 30, // key "age" matches `accessorKey` in ColumnDef down below
},
{
name: 'Sara',
age: 25,
},
];
```
> **Common Gotcha**: `data` passed to `useShadcnTable` must be _memoized_ or _stable_ (`useState`, `useMemo`, defined outside of your table component, etc.). Otherwise you may get infinite renders.
Data fetched from an API works the same way; see the [Remote Data examples](/docs/examples/react-query).
### Define the columns [#define-the-columns]
`accessorKey` points a column at a key of your data. `accessorFn` computes the value when it needs processing. Custom markup goes in `Cell`, never in the accessor.
```jsx
//simple column definitions pointing to flat data
const columns = useMemo(
() => [
{
header: 'Name',
accessorKey: 'name', //simple recommended way to define a column
//more column options can be added here to enable/disable features, customize look and feel, etc.
//optional custom cell render
Cell: ({ row }) => (
{row.name}
),
},
{
header: 'Age',
accessorFn: (dataRow) => parseInt(dataRow.age), //alternate way to access data if processing logic is needed
},
],
[],
);
```
> Note: Do NOT have your accessors resolve JSX or markup. That's what custom `Cell` renders are for. Accessors should only return primitive data so that the table can sort, filter, search, and group properly.
### Create the table and render it [#create-the-table-and-render-it]
```tsx
const table = useShadcnTable({ columns, data });
return
### Full Simple Example [#full-simple-example]
Put it all together, and you have a basic table! You can also play around and enable some features, either per column in the column definitions, or as table options passed to `useShadcnTable`.
```tsx
import { useMemo } from 'react';
import {
ShadcnTable,
useShadcnTable,
type ST_ColumnDef, //if using TypeScript (optional, but recommended)
} from '@/components/ui/shadcn-table';
//If using TypeScript, define the shape of your data (optional, but recommended)
interface Person {
name: string;
age: number;
}
//mock data - strongly typed if you are using TypeScript (optional, but recommended)
const data: Person[] = [
{
name: 'John',
age: 30,
},
{
name: 'Sara',
age: 25,
},
];
export default function App() {
//column definitions - strongly typed if you are using TypeScript (optional, but recommended)
const columns = useMemo[]>(
() => [
{
accessorKey: 'name', //simple recommended way to define a column
header: 'Name',
stTableHeadCellProps: { style: { color: 'green' } }, //custom props
enableHiding: false, //disable a feature for this column
},
{
accessorFn: (originalRow) => parseInt(originalRow.age), //alternate way
id: 'age', //id required if you use accessorFn instead of accessorKey
header: 'Age',
Header: Age , //optional custom markup
Cell: ({ cell }) => {cell.getValue().toLocaleString()} , //optional custom cell render
},
],
[],
);
//pass table options to useShadcnTable
const table = useShadcnTable({
columns,
data, //must be memoized or stable (useState, useMemo, defined outside of this component, etc.)
enableRowSelection: true, //enable some features
enableColumnOrdering: true, //enable a feature for all columns
enableGlobalFilter: false, //turn off a feature
});
//note: you can also pass table options as props directly to Team Score: {cell.getValue()}
,
},
];
const table = useShadcnTable({
columns,
data,
enableGrouping: true,
initialState: { grouping: ['team'], expanded: true },
});
return Team Score: {cell.getValue()}
,
},
];
```
Register reusable definitions by name in the `aggregationFns` table option and reference them from `aggregationFn: 'myAggregation'`.
### Aggregation on All Rows in Footer [#aggregation-on-all-rows-in-footer]
Shadcn Table does not automatically aggregate all rows for you to calculate totals for the entire table. However, it is still easy enough to do this manually and add in your custom calculations into the `footer` or `Footer` of a column definition. It is recommended that you do any necessary aggregation calculations on your data in a useMemo hook before passing it to the columns footer in your columns definition.
```jsx
//calculate the total points for all players in the table in a useMemo hook
const averageScore = useMemo(() => {
const totalPoints = data.reduce((acc, row) => acc + row.points, 0);
const totalPlayers = data.length;
return totalPoints / totalPlayers;
}, [data]);
const columns = useMemo(
() => [
{
accessorKey: 'name',
header: 'Name',
},
{
accessorKey: 'score',
header: 'Score',
Footer: () => Average Score: {averageScore}
, //do not do calculations in render, do them in useMemo hook and pass them in here
},
],
[averageScore],
);
```
> Please remember to perform heavy aggregation calculations in a useMemo hook to avoid unnecessary re-renders!
### Custom Cell Renders for Aggregation and Grouping [#custom-cell-renders-for-aggregation-and-grouping]
There are a few custom cell render overrides that you should be aware of when using grouping and aggregation features.
#### AggregatedCell Column Option [#aggregatedcell-column-option]
"Aggregation Cells" are cells in an aggregated row (not a normal data row) that can display aggregates (avg, sum, etc.) of the data in a group. The cell that the table is grouped on, however, is not an Aggregate Cell, but rather a [GroupedCell](#groupedcell-column-option).
You can specify the custom render for these cells with the `AggregatedCell` render option on a column definition.
```jsx
const columns = [
{
accessorKey: 'points',
header: 'Points',
aggregationFn: 'sum',
AggregatedCell: ({ cell }) => Total Score: {cell.getValue()}
,
},
];
```
#### GroupedCell Column Option [#groupedcell-column-option]
"Grouped Cells" are cells in a grouped row (not a normal data row) that by default display the value that the rows are grouped on and the number of rows in the group. You can override the default render for these cells with the `GroupedCell` render option on a column definition.
```jsx
const columns = [
{
accessorKey: 'team',
header: 'Team',
GroupedCell: ({ cell }) => Team: {cell.getValue()}
,
},
];
```
#### PlaceholderCell Column Option [#placeholdercell-column-option]
"Placeholder Cells" are cells that are usually meant to be empty in grouped rows and columns. They are simply rendered with a value of `null` by default, but you can override the default render for these cells with the `PlaceholderCell` render option on a column definition.
```jsx
const columns = [
{
accessorKey: 'team',
header: 'Team',
PlaceholderCell: ({ cell, row }) => (
{row.original.someOtherRowValue}
),
},
];
```
### Aggregation/Grouping Example [#aggregationgrouping-example]
{/*get the count from the first aggregation*/}
Count: {cell.getValue()[0]}
{/*get the average from the second aggregation*/}
Average Salary: {cell.getValue()[1]}
>`.
```tsx
import {
ShadcnTable,
useShadcnTable,
type ST_ColumnDef, // <--- import ST_ColumnDef
} from '@/components/ui/shadcn-table';
import { type User } from './types'; // <--- import your TData type from wherever you defined it
// define your columns, pass User as a generic to ST_ColumnDef
const columns: Array> = [
{
accessorKey: 'id', //you should get type hints for all of your keys if you defined your TData type correctly
header: 'ID',
enableSorting: false, //you should get type hints for all possible column options that you can define here
},
{
accessorKey: 'name',
header: 'Name',
},
{
accessorFn: (originalRow) => Number(originalRow.age), //you should also get type hints for your accessorFn
header: 'Age',
Cell: ({ cell }) => {cell.getValue()} , //cell.getValue() will be typed as `unknown` by default, but you can pass a generic to get the correct type
//see the createSRTColumnHelper example below for a better way to get type safety with cell.getValue()
},
];
```
#### createSRTColumnHelper Utility [#createsrtcolumnhelper-utility]
Alternatively you can use the `createSRTColumnHelper` utility function to define your columns. This works the same way as the TanStack `createColumnHelper`.
Additional `TValue` type-safety is provided by using this utility. That means that when you call `cell.getValue()` in either a custom `Cell` render, or in any of the `st*Props`, you will get the correct type for the data in that column instead of `unknown`.
```tsx
import {
ShadcnTable,
useShadcnTable,
createSRTColumnHelper, // <--- import createSRTColumnHelper
} from '@/components/ui/shadcn-table';
import { type User } from './types'; // <--- import your TData type from wherever you defined it (if using TS)
const columnHelper = createSRTColumnHelper(); // <--- pass your TData type as a generic to createSRTColumnHelper (if using TS)
//columns will be inferred as Array>
const columns = [
//accessorKey as first argument, rest of column options as second argument
columnHelper.accessor('name', {
header: 'Last Name',
}),
//accessorFn as first argument, rest of column options as second argument
columnHelper.accessor((row) => Number(row.age), {
id; 'age', //id required for accessorFn
header: 'Age',
filterVariant: 'range-slider', //you should get type hints for all possible column options that you can define here
Cell: ({ cell }) => {cell.getValue()} , //cell.getValue() will be typed as number instead of unknown
}),
//display column (no accessor needed)
columnHelper.display({
header: 'Contact',
Cell: ({ row }) => (
sendEmail(row.original.email)}>Send Email
),
}),
];
```
#### Use JSDoc instead of TypeScript [#use-jsdoc-instead-of-typescript]
If you are in a situation where you are not able to install TypeScript in your project, you can technically do the same thing as up above in JavaScript using JSDoc.
```jsx
import {
ShadcnTable,
useShadcnTable,
} from '@/components/ui/shadcn-table';
//define TData type with JSDoc
/**
* @typedef {Object} User
* @property {number} id
* @property {string} name
* @property {number} age
*/
//import ST_ColumnDef type with JSDoc
/**
* @type {import('@/components/ui/shadcn-table').ST_ColumnDef[]}
*/
const columns = [
{
accessorKey: 'id', //you should get type hints for all of your keys if you defined your TData type correctly
header: 'ID',
enableSorting: false, //you should get type hints for all possible column options that you can define here
},
{
accessorKey: 'name',
header: 'Name',
},
{
accessorFn: (originalRow) => Number(originalRow.age), //you should also get type hints for your accessorFn
header: 'Age',
},
];
```
### Re-Usable ST Components [#re-usable-st-components]
If you are going to have multiple tables in your app, chances are that you will want to make a re-usable component built on top of Shadcn Table. This is a good idea and good practice, but here are a few suggestions to maintain type safety with some TypeScript generics.
#### Re-usable Components or Options? [#re-usable-components-or-options]
In my opinion, instead of creating a re-usable component, it is instead actually best to define your default options and share them between all of your tables.
##### Re-usable Default Options [#re-usable-default-options]
In this example, we are simply creating a factory function that creates all of the default options that you want all of your tables to start with.
```ts
import {
type ST_RowData,
type ST_TableOptions,
} from '@/components/ui/shadcn-table';
//define re-useable default table options for all tables in your app
export const getDefaultSRTOptions = (): Partial<
ST_TableOptions
> => ({
//list all of your default table options here
enableGlobalFilter: false,
enableRowPinning: true,
initialState: { showColumnFilters: true },
manualFiltering: true,
manualPagination: true,
manualSorting: true,
stTableHeadCellProps: {
style: { fontSize: '1.1rem' },
},
paginationDisplayMode: 'pages',
//etc...
defaultColumn: {
//you can even list default column options here
},
});
```
Then you can use these options in every new table that you create:
```tsx
import {
ShadcnTable,
useShadcnTable,
type ST_ColumnDef,
} from '@/components/ui/shadcn-table';
import { getDefaultSRTOptions } from './utils'; //your default options
interface User {
id: number;
name: string;
age: number;
}
const defaultSRTOptions = getDefaultSRTOptions(); //get your default options
export const OneOfYourTableComponents = () => {
const columns: ST_ColumnDef[] = [
//...
];
const { data } = useQuery({
//...
});
const table = useShadcnTable({
...defaultSRTOptions, //spread your default options
columns,
data,
enableGlobalFilter: true, //override default options
initialState: {
...defaultSRTOptions.initialState, //spread default initial state
showColumnFilters: false, //override default initial state for just this table
},
//...
});
//you will have access to the entire table instance where you need it
console.log(table.state);
return )
type ST_TableOptions,
} from '@/components/ui/shadcn-table';
interface Props extends ST_TableOptions {
columns: ST_ColumnDef[];
data: TData[];
}
export const CustomSRTTable = ({
columns,
data,
...rest
}: Props) => {
const table = useShadcnTable({
columns,
data,
//your custom table options...
...rest, //accept props to override default table options
});
return [] = [
//...
];
export const YourComponent = () => {
//no easy access to the table instance or table state here unless you manage all of the state in this component
const [pagination, setPagination] = useState({
pageIndex: 0,
pageSize: 10,
});
const [sorting, setSorting] = useState([]);
//etc...
const { data } = useQuery({
//...
});
return (
Examples **
# Click to Copy Guide (/docs/guides/click-to-copy)
Shadcn Table has an easy-to-implement feature that allows a user to copy a cell's value to the clipboard.
### Relevant Table Options [#relevant-table-options]
Examples **
# Column Actions Guide (/docs/guides/column-actions)
By default, Shadcn Table renders a column actions button for each column header. It contains a drop-down menu to help your users use the other features of the table. All of these actions can be triggered in some other way other than from this drop-down menu, so this serves as a UI/UX alternative to make sure your users can find many of the table features easily.
### Relevant Table Options [#relevant-table-options]
Custom Menu Item 1 ,
Custom Menu Item 2 ,
];
},
});
return Examples **
# Column Filtering Guide (/docs/guides/column-filtering)
Filtering is one of the most powerful features of Shadcn Table and is enabled by default. There is a lot of flexibility and customization available here. Whether you want to customize the powerful client-side filtering already built in or implement your own [server-side filtering](#manual-server-side-column-filtering), Shadcn Table has got you covered.
### Relevant Table Options [#relevant-table-options]
();
//fetch unique values from server, ideally including the count of each unique value
return uniqueValueMap;
},
})
```
### Column Filter Display Modes [#column-filter-display-modes]
By default, column filters inputs show below the column header. You can switch to a more "excel-like" UI by setting the `columnFilterDisplayMode` table option to `'popover'`. This will show a filter icon in the column header that can be clicked to open a popover with the filter input.
```jsx
const table = useShadcnTable({
columns,
data,
columnFilterDisplayMode: 'popover', //filter inputs will show in a popover (like excel)
});
```
Alternatively, if you want to render your own column filter UI in a separate sidebar, but still want to use the built-in filtering functionality, you can set the `columnFilterDisplayMode` table option to `'custom'`.
```jsx
const table = useShadcnTable({
columns,
data,
columnFilterDisplayMode: 'custom', //render your own column filter UI (e.g. in a sidebar)
});
```
, id: string, filterValue: string | number) => boolean;
```
This function will be used to filter 1 row at a time and should return a `boolean` indicating whether or not that row passes the filter.
#### Add Custom Filter Functions [#add-custom-filter-functions]
You can add custom filter functions to the `filterFns` table option. These will be available to all columns to use. The `filterFn` table option on a column will override any filter function with the same name in the `filterFns` table option.
```jsx
const columns = [
{
accessorKey: 'name',
header: 'Name',
filterFn: 'customFilterFn',
},
];
const table = useShadcnTable({
columns,
data,
filterFns: {
customFilterFn: (row, id, filterValue) => {
return row.customField === value;
},
},
});
```
### Filter Modes [#filter-modes]
#### Enable Column Filter Modes (Filter Switching) [#enable-column-filter-modes-filter-switching]
If you want to let the user switch between multiple different filter modes from a drop-down menu on the Filter Textfield, you can enable that with the `enableColumnFilterModes` table option or column option. This will enable the filter icon in the filter text field to open a drop-down menu with the available filter modes when clicked.
```tsx
const table = useShadcnTable({
columns,
data,
enableColumnFilterModes: true,
});
```
#### Customize Filter Modes [#customize-filter-modes]
You can narrow down the available filter mode options by setting the `columnFilterModeOptions` table option or a column specific `columnFilterModeOptions` option.
```tsx
const columns = [
{
accessorKey: 'firstName',
header: 'First Name',
columnFilterModeOptions: ['fuzzy', 'contains', 'startsWith'],
},
{
accessorKey: 'age',
header: 'Age',
columnFilterModeOptions: ['between', 'lessThan', 'greaterThan'],
},
];
```
#### Render Custom Filter Mode Menu [#render-custom-filter-mode-menu]
You can also render custom menu items in the filter mode drop-down menu by setting the `renderColumnFilterModeMenuItems` table option or column option. This option is a function that takes in the column and returns an array of `MenuItem` components. This is useful if you want to add custom filter modes that are not included in Shadcn Table, or if you just want to render the menu in your own custom way
```jsx
const columns = [
{
accessorKey: 'firstName',
header: 'First Name',
renderColumnFilterModeMenuItems: ({ column, onSelectFilterMode }) => [
onSelectFilterMode('startsWith')}
>
Start With
,
onSelectFilterMode('yourCustomFilterFn')}
>
Your Custom Filter Fn
,
],
},
];
const table = useShadcnTable({
columns,
data,
enableColumnFilterModes: true,
// renderColumnFilterModeMenuItems could go here if you want to apply to all columns
});
return `theme.palette.warning.main` color.
Filter Match Highlighting will only work on columns with the default `text` filter variant. Also, if you are using a custom `Cell` render override for a column, you will need to use the `renderedCellValue` table option instead of `cell.getValue()` in order to preserve the filter match highlighting.
```jsx
const columns = [
{
accessorKey: 'name',
header: 'Name',
Cell: ({ renderedCellValue }) => {renderedCellValue} , // use renderedCellValue instead of cell.getValue()
},
];
```
#### Disable Filter Match Highlighting [#disable-filter-match-highlighting]
This feature can be disabled by setting the `enableFilterMatchHighlighting` table option to `false`.
```jsx
const table = useShadcnTable({
columns,
data,
enableFilterMatchHighlighting: false,
});
```
View Extra Storybook **Examples **
# Column Grouping Guide (/docs/guides/column-grouping)
Shadcn Table has built-in column grouping features. There are options for both automatic client-side grouping as well as manual server-side grouping. This guide will walk you through the different options and how to use and customize them.
### Relevant Table Options [#relevant-table-options]
Examples **
# Column Ordering/DnD Guide (/docs/guides/column-ordering-dnd)
Whether you just want to change the default column order in your table or let columns be reordered by dragging and dropping, Shadcn Table has a simple API for this.
### Relevant Table Options [#relevant-table-options]
Examples **
# Column Pinning Guide (/docs/guides/column-pinning)
Column pinning is a cool feature that lets users pin (freeze) columns to the left or right of the table. Pinned columns will not scroll horizontally with the rest of the columns so that they always stay visible to the user.
### Relevant Table Options [#relevant-table-options]
Examples **
# Column Resizing Guide (/docs/guides/column-resizing)
Shadcn Table has a built-in column resizing draggable handle feature.
> The Column Size features was recently split into its own [Guide](/docs/guides/column-size). View that guide as a prerequisite to this one.
### Relevant Table Options [#relevant-table-options]
{' '}
{/* app-wide style? */}
);
```
Examples **
# Column Size Guide (/docs/guides/column-size)
Shadcn Table lets you easily change the default widths (sizes) of columns.
### Relevant Table Options [#relevant-table-options]
`, ``, ``, etc. elements.
2. `"grid"` (default when virtualization is enabled) - uses CSS Grid and Flexbox styles instead of default styles.
3. `"grid-no-grow"` (default when column resizing is enabled) - uses CSS Grid and Flexbox styles, but also sets `flex-grow: 0` on all columns and adds an empty "spacer" column to the end of the table to fill the potential remaining space.
If you want your columns to have an absolute width, you can use the `"grid-no-grow"` layout mode and set the `size` option on each column.
### Column Size [#column-size]
You can change the width of any column by setting its `size` option on the column definition. There are `minSize` and `maxSize` column options available to enforce limits during resizing events.
The `size`, `minSize`, and `maxSize` do not take in any CSS width unit. They are only numbers that represent the width of the column in pixels.
```jsx
const columns = [
{
accessorKey: 'id',
header: 'ID',
grow: false, //don't allow this column to grow to fill in remaining space
size: 50, //small column
},
{
accessorKey: 'username',
header: 'Username',
minSize: 100, //min size enforced during resizing
maxSize: 400, //max size enforced during resizing
size: 180, //medium column
},
{
accessorKey: 'email',
header: 'Email',
grow: true, //allow this column to grow to fill in remaining space
size: 300, //large column
},
];
```
### Column Grow [#column-grow]
You can also set `grow` properties on the column definitions when using layoutMode `"grid-no-grow"` or `"grid"`.
If the layout mode of your table is `"grid"` and you set `grow: false` on a column, that column will have a fixed size and will not grow to fill in the remaining space of the table.
If the layout mode of your table is `"grid-no-grow"` and you set `grow: true` on a column, that column will grow to fill in the remaining space of the table.
If the layout mode of your table is `"grid-no-grow"` and you set `grow: 1` on one column, and `grow: 2` on another column, the first column will grow to fill in 1/3 of the remaining space of the table, and the second column will grow to fill in 2/3 of the remaining space of the table.
If the layout mode of your table is `"semantic"`, the `grow` column option will have no effect, but columns will size themselves to fit their own content better than the other layout modes.
### But I Want My Columns to Have a Percentage Width [#but-i-want-my-columns-to-have-a-percentage-width]
Shadcn Table is not designed to use percentage column widths well by default. This is because having horizontal scrollbars on tables is both a very common use case, and usually the best way to ensure that the actual content of the cells in each column is visible and not cutoff or wrapped excessively.
If you disagree with that, that's fair, and you're not out of luck. Shadcn Table exposes all `st*Props`, so if you really want to, you can add whatever CSS you want to achieve your own custom column widths behavior. This is not recommended by the maintainer, but some developers have found it useful to set all column sizes and minSizes to a very small number like `1`, `1.5`, `2`, ect., and then use either `layoutMode: "semantic"` or `layoutMode: "grid"`. This makes the columns act more like they are using percentage widths, up until a certain point. If you really need to never have a horizontal scrollbar, you can edit the `stTableContainerProps` `className` or `style` to set `overflow-x: hidden`. Be very careful with this though, as this could cause your table to be unusable on smaller screens.
If the above still does not get you to where you need to be, `stTableHeadCellProps`, `stTableBodyCellProps`, and `stTableFooterCellProps` (`className` or `style`) and more are all exposed and available to you to override with whatever custom CSS that you need. Just be aware that non of the built-in TanStack Table size APIs will be accurate anymore.
#### Side Note: Just Make Your Scrollbars Prettier [#side-note-just-make-your-scrollbars-prettier]
Making your scrollbars look better (especially on Windows and Linux) can go a long way to not letting a horizontal scrollbar ruin the look of your table.
Here's what this docs site uses in its global CSS to make scrollbars to more like the default Mac OS scrollbars for everyone:
```css
::-webkit-scrollbar-track {
background-color: transparent;
}
::-webkit-scrollbar {
right: 0;
width: 12px;
height: 12px;
}
::-webkit-scrollbar-thumb {
background-color: #999;
border-radius: 8px;
width: 12px;
height: 12px;
}
```
### Default Column [#default-column]
By default, columns will have the following size properties defined:
```jsx
defaultColumn = { minSize: 40, maxSize: 1000, size: 180 }; //units are in px
```
You can modify the default column widths by setting the `defaultColumn` table option on the table.
```jsx
const table = useShadcnTable({
columns,
data,
defaultColumn: {
minSize: 20, //allow columns to get smaller than default
maxSize: 9001, //allow columns to get larger than default
size: 260, //make columns wider by default
},
});
```
### Change Sizes of Built-in Display Columns [#change-sizes-of-built-in-display-columns]
As discussed further in the [Display Columns Guide](/docs/guides/display-columns), you can customize the options of the built-in columns that get generated under the hood by ST by enabling certain features.
```jsx
const table = useShadcnTable({
columns,
data,
displayColumnDefOptions: {
'st-row-select': {
size: 50, //adjust the size of the row select column
grow: false, //default is false for this column
},
'st-row-numbers': {
size: 40,
grow: true, //allow this column to grow to fill in remaining space
},
},
enableRowNumbers: true,
});
return Examples **
# Customize (Style) Components Guide (/docs/guides/customize-components)
One of the strengths of Shadcn Table is that it exposes a majority of all the underlying shadcn/ui component props used to build the table.
Additionally, in one of the sections below, you will learn [how to theme your table](#theming) to customize colors, typography, or any other default CSS that is used by Shadcn Table.
### Relevant Table Options [#relevant-table-options]
All props labeled `st...Props` get forwarded to shadcn/ui components. Here is a list of all the props that are exposed in both the root props and column options.
);
```
#### Custom Theme Example [#custom-theme-example]
Customized No Rows Overlay
),
});
```
# Custom Icons Guide (/docs/guides/customize-icons)
Shadcn Table uses [Lucide icons](https://lucide.dev) by default for all of its internal icons.
If you need to, you can customize and replace some or all of the icons with your own custom icons. You can either use other Lucide icons or icons from a completely different library.
### Relevant Table Options [#relevant-table-options]
[]>( //TS helps with the autocomplete while writing columns
() => [
{
accessorKey: 'username', //normal recommended usage of an accessorKey
header: 'Username',
},
{
accessorKey: 'name.firstName', //example of dot notation used to access nested data
header: 'First Name',
},
{
accessorKey: 'name.lastName', //example of dot notation used to access nested data
header: 'Last Name',
},
{
accessorKey: 'customerAge',
id: 'age' //id overridden, usually not necessary to do this, but can be helpful
header: 'Age',
},
],
[],
);
```
#### Method 2 - Using an accessorFn and id [#method-2---using-an-accessorfn-and-id]
You can alternatively use the `accessorFn` column option. Here are at least three ways you can use it.
In each case, the `id` property is now required since there is no `accessorKey` for ST to derive it from.
```tsx
const columns = useMemo[]>(
() => [
{
//simple accessorFn that works the same way as an `accessorKey`
accessorFn: (row) => row.username,
id: 'username',
header: 'Username',
},
{
//accessorFn function that combines multiple data together
accessorFn: (row) => `${row.firstName} ${row.lastName}`,
id: 'name',
header: 'Name',
},
{
//accessorFn used to access nested data, though you could just use dot notation in an accessorKey
accessorFn: (row) => row.personalInfo.age,
id: 'age',
header: 'Age',
},
],
[],
);
```
#### Method 3 - Using createSRTColumnHelper [#method-3---using-createsrtcolumnhelper]
Alternatively you can use the `createSRTColumnHelper` utility function to define your columns definitions in a slightly more type-safe way. Instantiate a `columnHelper` by passing in your `TData` type as a generic argument. Then the first argument of the `columnHelper.accessor()` method can be either an `accessorKey` or an `accessorFn`. Then you can specify the rest of the column options as the second argument.
```tsx
const columnHelper = createSRTColumnHelper(); //TS now knows the shape of your data
const columns = [
//accessorKey as first argument, rest of column options as second argument
columnHelper.accessor('name', {
//TS should provide autocomplete for valid accessorKeys
header: 'Last Name',
}),
//accessorFn as first argument, rest of column options as second argument
columnHelper.accessor((row) => Number(row.age), {
//TS should provide autocomplete for valid properties on your data
header: 'Age',
id: 'age', //id is required when using accessorFn
}),
];
```
### Custom Header Render [#custom-header-render]
If you want to pass in custom JSX to render the header, you can pass in a `Header` option in addition to the `header` string property.
> The `header` (lowercase) property is still required and still must only be a string because it is used within multiple components in the table and has string manipulation methods performed on it.
```tsx
const columns = useMemo(
() => [
{
accessorKey: 'name',
header: 'Name',
Header: ({ column }) => (
{column.columnDef.header} //re-use the header we already defined
), //arrow function
},
{
accessorKey: 'age',
header: 'Age',
Header: Age , //plain jsx with no function
},
],
[],
);
```
### Custom Cell Render [#custom-cell-render]
Similarly, the data cells in a column can have a custom JSX render with the `Cell` option. This is one of the most common features used in ST.
Using the `Cell` column option should be the only way that you use to render custom JSX in table cells. Do not put JSX in an accessorFn, or else the table will not be able to sort, filter, search, or group properly.
```tsx
const columns = useMemo(
() => [
{
accessorFn: (row) => `${row.firstName} ${row.lastName}`,
header: 'Name',
//Add a link in a cell render
Cell: ({ renderedCellValue, row }) => (
${cell.getValue().toLocaleString()}
),
},
{
accessorKey: 'profileImage',
header: 'Profile Image',
//Render images in a cell render
Cell: ({ cell }) =>
Max Age:
{Math.round(maxAge)}
),
},
],
[],
);
```
> See the [Customize Components Guide](/docs/guides/customize-components) for more ways to style and customize header and cell components.
### Set Column Widths [#set-column-widths]
This topic is covered in detail in the [Column Size Guide](/docs/guides/column-size), but here is a brief overview.
Setting a CSS (`className` or `style`) width prop in the `stTableHeadCellProps`, `stTableBodyCellProps`, etc. might not work well, and is redundant. ST/TanStack Table has an official way to set column widths with the `size`, `minSize`, `maxSize`, and `grow` column options.
```tsx
const columns = [
{
accessorKey: 'id',
header: 'ID',
size: 50, //small column
grow: false, //don't allow this column to grow (if layoutMode is grid)
},
{
accessorKey: 'username',
header: 'Username',
minSize: 100, //min size enforced during resizing
maxSize: 200, //max size enforced during resizing
size: 180, //medium column
},
{
accessorKey: 'email',
header: 'Email',
size: 300, //large column
},
];
```
There is a lot of different behaviors for column widths depending on what other features are enabled or how they are configured. See the [Column Size Guide](/docs/guides/column-size) for more details on the `layoutMode`s, and how and why they are enabled and how they affect column widths.
### Set Column Alignment [#set-column-alignment]
By default, all columns are left-aligned. You can change the alignment of a column by setting the `align` option to either `"center"`, `"right"`, or `"justify"` in the `stTableHeadCellProps` and `stTableBodyCellProps` props/column options.
```tsx
const columns = [
{
accessorKey: 'id',
header: 'ID',
//right align the header, body, and footer cells each individually
stTableHeadCellProps: {
align: 'right',
},
stTableBodyCellProps: {
align: 'right',
},
stTableFooterCellProps: {
align: 'right',
},
},
{
accessorKey: 'username',
header: 'Username',
//center align the header, body, and footer cells each individually
stTableHeadCellProps: {
align: 'center',
},
stTableBodyCellProps: {
align: 'center',
},
stTableFooterCellProps: {
align: 'center',
},
},
];
```
` elements will still be created for all rows, even if they do not have detail panel content. It is implemented this way in order to avoid bugs with row virtualization, or striped row CSS.
### Only Allow One Detail Panel Open At A Time [#only-allow-one-detail-panel-open-at-a-time]
If you want to only allow one detail panel to be open at a time, all you have to do is add your own `onClick` logic to the `stExpandButtonProps` table option.
```jsx
const table = useShadcnTable({
data,
columns,
renderDetailPanel: ({ row }) => ` element that contains the detail panel content.
If you need to customize the ` ` element containing the detail panel cell, you can just use the `stTableBodyRowProps` table option that you use for customizing all rows. There is a `isDetailPanel` parameter that is available to you to target only detail panel rows.
```jsx
const table = useShadcnTable({
data,
columns,
stDetailPanelProps: ({ row }) => ({
style: {
//...
},
}),
stTableBodyRowProps: ({ isDetailPanel, row }) => ({
style: {
// isDetailPanel ? ... : ...
},
}),
});
```
Examples **
# Display (Built-in) Columns (/docs/guides/display-columns)
Display columns are used to display non-data elements in a table. They only require an `id` and `header` in the column definition. They do not need an `accessorKey` or `accessorFn`, as they are not meant to connect to your data at all.
Display columns do not have any processing features, such as sorting, filtering, grouping, etc. enabled on them by default.
### Relevant Table Options [#relevant-table-options]
;
```
All of these values are able to be overridden if needed, and you'll learn about that in the next section down below.
### Customize Built-in ST Display Columns [#customize-built-in-st-display-columns]
It is possible to change and override the default behavior of built-in display columns. Whether you want to change the default column width, add some styles, or enable some features, such as column actions or column drag and drop, you can do it with the `displayColumnDefOptions` table option.
#### Default Display Column Table Option [#default-display-column-table-option]
First of all, if you want to enable or disable some feature for all display columns, you can just use the `defaultDisplayColumn` table option. This will apply to all display columns, including any custom display columns you create.
```jsx
const table = useShadcnTable({
columns,
data,
defaultDisplayColumn: {
enableColumnOrdering: true,
enableColumnResizing: true,
minSize: 100,
},
});
```
#### Display Column Definition Options Table Option [#display-column-definition-options-table-option]
Let's say you need to adjust the width of the Actions column to be wide enough to fit all of your action buttons. You could do that as follows:
```jsx
const table = useShadcnTable({
columns,
data,
displayColumnDefOptions: { 'st-row-actions': { size: 300 } }, //change width of actions column to 300px
enableRowActions: true,
renderRowActions: ({ row }) => (
Action 1
Action 2
Action 3
),
});
return sendEmail(row.original.userId)}>Send Email
),
},
{
id: 'name',
header: 'Name',
accessorKey: 'name',
},
];
```
# Editing Guide (/docs/guides/editing)
If your tables need full CRUD functionality, you can enable editing features in Shadcn Table.
There are five visually distinct editing modes to choose from, whether you want to let users [edit data in a modal](#modal-edit-display-mode), [inline one row at a time](#row-edit-display-mode), [one cell at a time](#cell-edit-display-mode), or just always have [editing enabled for every cell](#table-edit-display-mode), or a [completely custom editing UI](#custom-edit-display-mode).
### Relevant Table Options [#relevant-table-options]
{
table.setCreatingRow(true); //simplest way to open the create row modal with no default values
//or you can pass in a row object to set default values with the `createRow` helper function
// table.setCreatingRow(
// createRow(table, {
// //optionally pass in default values for the new row, useful for nested data or other complex scenarios
// }),
// );
}}
>
Create New User
),
});
```
### CRUD Examples [#crud-examples]
table.setEditingRow(row)}>Edit Customer
),
},
},
});
```
# Expanding Sub-Rows/Tree Data Guide (/docs/guides/expanding-sub-rows)
Shadcn Table has support for expanding sub-rows or tree data. This feature is useful for displaying hierarchical data. The sub-rows can be expanded and collapsed by clicking on the expand/collapse icon.
> NOTE: This feature is for expanding rows of the same data type. If you want to add expansion of more data for the same row, check out the [Detail Panel Feature Guide](/docs/guides/detail-panel).
### Relevant Table Options [#relevant-table-options]
`theme.palette.warning.main` color.
If you are using a custom `Cell` render override for a column, you will need to use the `renderedCellValue` table option instead of `cell.getValue()` to preserve the filter match highlighting.
```jsx
const columns = [
{
accessorKey: 'name',
header: 'Name',
Cell: ({ renderedCellValue }) => {renderedCellValue} , // use renderedCellValue instead of cell.getValue()
},
];
```
#### Disable Filter Match Highlighting [#disable-filter-match-highlighting]
Filter match highlighting can be disabled by setting the `enableFilterMatchHighlighting` table option to `false`.
```jsx
const table = useShadcnTable({
columns,
data,
enableFilterMatchHighlighting: false, //disable filter match highlighting
});
```
View Extra Storybook **Examples **
# Guides (/docs/guides)
item.href === '/docs/guides').items}
variant="heading"
/>
# Localization/i18n Guide (/docs/guides/localization)
Shadcn Table has full support for localization (i18n). Some locales are included by default, but if your language is not yet supported, you can still easily add your own custom translations to the `localization` table option.
### Relevant Table Options [#relevant-table-options]
`, installed after the table from the same base path of the registry (`/r/radix/` for a `radix-*` style in `components.json`, `/r/base/` for a `base-*` style):
```bash
pnpm dlx shadcn@latest add https://www.shadcn-table.com/r/radix/shadcn-table-locale-de.json # Radix UI
pnpm dlx shadcn@latest add https://www.shadcn-table.com/r/base/shadcn-table-locale-de.json # Base UI
```
With the `@st` namespace registered (see [Installation](/docs/getting-started/install)), `pnpm dlx shadcn@latest add @st/shadcn-table-locale-de` picks the path from the project's style. GitHub fallback: `anindosarker/shadcn-table/shadcn-table-locale-de` (Radix UI) and `anindosarker/shadcn-table/shadcn-table-base-locale-de` (Base UI).
The item lands in `components/ui/shadcn-table/locales/.ts` and is imported from `'@/components/ui/shadcn-table/locales/'`. Available codes:
`ar`, `az`, `bg`, `cs`, `da`, `de`, `el`, `en`, `es`, `et`, `fa`, `fi`, `fr`, `he`, `hr`, `hu`, `hy`, `id`, `it`, `ja`, `ko`, `nl`, `no`, `np`, `pl`, `pt`, `pt-BR`, `ro`, `ru`, `sk`, `sr-Cyrl-RS`, `sr-Latn-RS`, `sv`, `tr`, `uk`, `vi`, `zh-Hans`, `zh-Hant`
> If your language is not yet supported, please consider making a PR to add it to the library! See [here on GitHub](https://github.com/anindosarker/shadcn-table/tree/master/packages/shadcn-table/shared/components/ui/shadcn-table/locales). A locale is data shared by both bases: add one file under `shared/`.
#### Built-in Locale Examples [#built-in-locale-examples]
Scroll and find your language below to see an example of how to use it.
>['renderDetailPanel'] //TS needed to get the correct type of the inner arrow function below
>(
({ row, table }) =>
` component during column resizing, and column/row drag and drop events. This actually does make a significant performance improvement, and is why it is possible to have the performance that it does during these events.
If you need to reach into the internals and apply some custom memoization, ST exposes a limited way to do this. The Table Body, Table Rows, or all Table Cells can be memoized with the `memoMode` table option.
```jsx
const table = useShadcnTable({
columns,
data,
//memoize all cells. This value can be applied dynamically based on a certain scenario/condition if needed
memoMode: 'cells', // 'cells' | 'rows' | 'table-body'
});
```
Usually you should not ever need to do this, and be aware that this will stop certain features from functioning correctly. For example, if you memoize all table cells, the density toggle feature will not work anymore. If you memoize the entire table body, most features including virtualization will not work anymore. You'll be left with a table that is mostly frozen after first render, but it could improve the overall performance of your web page if you don't need any of these interactive features.
> Don't use `memoMode` unless you know what you're doing and have a specific use case for it.
### React Forget [#react-forget]
In the future, React may finally release their magical "React Forget" compiler that will make all memoization problems in React disappear, and you won't have to worry about any of this. But until then, the above solutions are the best we have.
View Extra Storybook Examples
# Pagination Guide (/docs/guides/pagination)
Client-side pagination is enabled by default in Shadcn Table. There are a number of ways to customize pagination, turn off pagination, or completely replace the built-in pagination with your own manual or server-side pagination logic.
### Relevant Table Options [#relevant-table-options]
Examples **
# Building Production-Ready Tables (/docs/guides/production-ready-tables)
This guide shows the pattern for a real-world table. The data comes from your API through React Query. The server does the paging, sorting, search and filtering, and the table only shows one page at a time. You need four pieces:
1. **Service:** an async function that calls your API.
2. **Query hook:** `useUsersQuery(params)` wraps the service in React Query.
3. **`useTableQueryParams`:** owns the table state and turns it into the params your server accepts.
4. **Table:** turns off client-side processing and reads its state from the hook.
```text
table state
▼ useTableQueryParams
server params
▼ useUsersQuery
▼ service
GET /api/users
▼
{ data, total } ──▶ table
```
This guide assumes you know React and the basics of React Query.
### Write the Service [#write-the-service]
The service is a plain async function. It knows your API's URL and response shape, and nothing about tables. Type the params and the response.
```ts title="lib/users.service.ts"
export type UsersQueryParams = {
page: number; //1-based
limit: number;
search?: string;
sortBy?: string[]; //"lastName:desc"
filter?: string[]; //"state[$contains]=tex"
};
export type PaginatedResponse = {
data: T[];
total: number;
page: number;
limit: number;
};
export async function getUsers(
params: UsersQueryParams,
): Promise> {
const url = new URL('/api/users', location.origin);
for (const [key, value] of Object.entries(params)) {
if (value === undefined) continue;
//arrays become repeated keys: sortBy=a&sortBy=b
for (const item of [value].flat()) {
url.searchParams.append(key, String(item));
}
}
const response = await fetch(url);
if (!response.ok) throw new Error(`GET /api/users: ${response.status}`);
return response.json();
}
```
Throw on a bad status. `fetch` does not, and React Query only sees an error if the function throws.
If you use axios, it does the URL building for you. To send arrays as repeated keys, use `qs`:
```ts
const http = axios.create({
paramsSerializer: (params) => qs.stringify(params, { arrayFormat: 'repeat' }),
});
const { data } = await http.get>('/users', { params });
```
### Wrap It in a Query Hook [#wrap-it-in-a-query-hook]
```ts title="hooks/useUsersQuery.ts"
import { keepPreviousData, useQuery } from '@tanstack/react-query';
import { getUsers, type UsersQueryParams } from '../lib/users.service';
export function useUsersQuery(params: UsersQueryParams) {
return useQuery({
queryKey: ['users', params], //new params, new cache entry, new request
queryFn: () => getUsers(params),
placeholderData: keepPreviousData, //keep the old page on screen while the next one loads
});
}
```
- **`params` in the `queryKey`:** React Query refetches when the key changes. Every page, sort and filter gets its own cache entry, so going back to page 1 is instant.
- **`keepPreviousData`:** without it, `data` is `undefined` while the next page loads, and the table flashes empty.
### Turn Table State Into Server Params [#turn-table-state-into-server-params]
This hook is the link between the table and your server. It holds the table state you control, and it translates that state into the params your API expects. The table state is always the same. The params are whatever your server wants, so you shape this hook to your server.
Start small. If your server only takes `page`, `limit` and `search`, this is the whole hook:
```ts title="hooks/useTableQueryParams.ts"
export function useTableQueryParams({ pageSize = 10 } = {}) {
const [pagination, setPagination] = useState({
pageIndex: 0,
pageSize,
});
const [search, setSearch] = useState('');
const handlers = {
onPaginationChange: setPagination,
onGlobalFilterChange: (value: string | undefined) => {
setSearch(value ?? '');
setPagination((prev) => ({ ...prev, pageIndex: 0 }));
},
};
const params = {
page: pagination.pageIndex + 1, //table is 0-based, server is 1-based
limit: pagination.pageSize,
search: search || undefined,
};
return { params, handlers, state: { pagination, globalFilter: search } };
}
```
Then grow it. The full version adds sorting, column filters and filter modes. Each change handler sends you back to the first page:
```ts title="hooks/useTableQueryParams.ts"
//filter values can be strings, numbers or Dates (date filters)
const toParam = (value: unknown) =>
value instanceof Date ? value.toISOString() : String(value);
export function useTableQueryParams({
columns,
pageSize = 10,
}: {
columns: ST_ColumnDef[];
pageSize?: number;
}) {
const [pagination, setPagination] = useState({
pageIndex: 0,
pageSize,
});
const [search, setSearch] = useState('');
const [sorting, setSorting] = useState([]);
const [columnFilters, setColumnFilters] = useState(
[],
);
//one filter mode per column, from the column's filterFn or 'contains'
const [columnFilterFns, setColumnFilterFns] =
useState(() =>
Object.fromEntries(
columns.map((column) => [
column.id ?? String(column.accessorKey),
typeof column.filterFn === 'string' ? column.filterFn : 'contains',
]),
),
);
//new search, sort or filter: the old page number means nothing, go back to page 1
const resetPageIndex = () =>
setPagination((prev) => ({ ...prev, pageIndex: 0 }));
const handlers = {
onPaginationChange: setPagination,
onGlobalFilterChange: (value: string | undefined) => {
setSearch(value ?? '');
resetPageIndex();
},
onSortingChange: (updater: ST_Updater) => {
setSorting(updater);
resetPageIndex();
},
onColumnFiltersChange: (updater: ST_Updater) => {
setColumnFilters(updater);
resetPageIndex();
},
onColumnFilterFnsChange: (
updater: ST_Updater,
) => {
setColumnFilterFns(updater);
resetPageIndex();
},
};
//translate table state into the params YOUR server accepts
const params: UsersQueryParams = {
page: pagination.pageIndex + 1, //table is 0-based, server is 1-based
limit: pagination.pageSize,
search: search || undefined,
sortBy: sorting.map(({ id, desc }) => `${id}:${desc ? 'desc' : 'asc'}`),
filter: columnFilters.map(
({ id, value }) =>
`${id}[$${columnFilterFns[id] ?? 'contains'}]=${toParam(value)}`,
),
};
return {
params,
handlers,
state: {
pagination,
globalFilter: search,
sorting,
columnFilters,
columnFilterFns,
},
};
}
```
The table calls each `on*Change` handler with either a value or an updater function. `useState` setters accept both, so you can pass the updater straight through. If you need the new value first, unwrap it as shown in [State Management](/docs/guides/state-management#add-side-effects-in-set-state-callbacks).
**Shape it to your server.** Only the `params` block changes from one backend to another:
| Table state | Demo server param | Other common shapes |
| ----------------------------------- | ----------------------------- | --------------------------------------- |
| `pagination.pageIndex` (0-based) | `page` (1-based) | `offset = pageIndex * pageSize`, `skip` |
| `pagination.pageSize` | `limit` | `size`, `per_page`, `take` |
| `globalFilter` | `search` | `q`, `query` |
| `sorting` | `sortBy=lastName:desc` | `sort=-lastName`, `orderBy` + `order` |
| `columnFilters` + `columnFilterFns` | `filter=state[$contains]=tex` | `state=tex`, `filters` as JSON |
If your server has no filter operators, drop `columnFilterFns` and send `field=value`.
### Build the Table [#build-the-table]
Define your columns the regular way. Then wire the hooks into the table:
```tsx title="components/UsersTable.tsx"
const { params, handlers, state } = useTableQueryParams({ columns });
const { data, isError, isFetching, isLoading, refetch } = useUsersQuery(params);
const table = useShadcnTable({
columns,
data: data?.data ?? [],
rowCount: data?.total ?? 0, //the server knows the total, the table does not
manualPagination: true, //turn off client-side pagination
manualSorting: true, //turn off client-side sorting
manualFiltering: true, //turn off client-side filtering
enableColumnFilterModes: true,
//only the operators the server understands
columnFilterModeOptions: [
'contains',
'startsWith',
'endsWith',
'equals',
'notEquals',
],
...handlers,
stToolbarAlertBannerProps: isError
? {
className: 'border-destructive text-destructive',
children: 'Error loading data',
}
: undefined,
state: {
...state,
isLoading, //first load only: skeleton rows
showProgressBars: isFetching, //every later request: thin progress bar
showAlertBanner: isError,
},
});
```
- **`manual*` flags:** the rows you pass are already paged, sorted and filtered. Without these flags, the table does it again on one page of data.
- **`rowCount`:** the table only holds one page, so it cannot count the rows. The server tells it.
- **State and handlers:** pass both. If you pass a handler but not its state, the table never sees the change. See [State Management](/docs/guides/state-management#manage-individual-states-as-needed).
- **Loading:** `isLoading` is true only on the first load, when there is no data yet. Later requests keep the old page (thanks to `keepPreviousData`) and show a progress bar.
- **Errors:** `showAlertBanner` shows the error above the table. Without it, a failed request just looks like an empty table.
The search box and the text column filters already debounce their input when `manualFiltering` is on (500ms for search, 400ms for filters), so you don't need your own debounce.
### Adapting to Your Server [#adapting-to-your-server]
**Extra params that aren't table state.** Merge them in before you call the query hook:
```ts
const { params, handlers, state } = useTableQueryParams({ columns });
const query = useUsersQuery({ ...params, organizationId });
```
Add `organizationId` to `UsersQueryParams` so it ends up in the `queryKey` too.
**A fixed filter the user can't remove.** Prepend it to the translated filters:
```ts
const query = useUsersQuery({
...params,
filter: ['status[$equals]=active', ...(params.filter ?? [])],
});
```
**Pagination only.** Turn off the features your server doesn't support, and use the minimal hook:
```ts
useShadcnTable({
columns,
data: data?.data ?? [],
rowCount: data?.total ?? 0,
manualPagination: true,
enableSorting: false,
enableGlobalFilter: false,
enableColumnFilters: false,
...handlers,
state: { ...state, isLoading, showProgressBars: isFetching },
});
```
**Refresh after a mutation.** Invalidate by the key prefix. That marks every page, sort and filter combination as stale:
```ts
const queryClient = useQueryClient();
useMutation({
mutationFn: updateUser,
onSuccess: () => queryClient.invalidateQueries({ queryKey: ['users'] }),
});
```
### Common Mistakes [#common-mistakes]
- **Not resetting the page.** You are on page 7, you type a search, and the result has 2 pages. Page 7 is empty. Reset `pageIndex` to 0 in every search, sort and filter handler.
- **Mixing up 0-based and 1-based pages.** The table's `pageIndex` starts at 0. Most servers start at 1. Convert in one place: the params block.
- **Passing `isFetching` as `isLoading`.** The whole table turns into skeletons on every page change. Use `isLoading` for the first load and `showProgressBars` for the rest.
- **Hiding errors.** Set `showAlertBanner` from `isError`, and make the service throw on a bad status.
- **Leaving params out of the `queryKey`.** The query never refetches, and the table is stuck on page 1.
- **Forgetting `rowCount`.** The pagination thinks there is only one page.
- **Adding your own debounce.** The built-in search and filter inputs already debounce in manual mode. A second debounce just adds lag.
### Related [#related]
- [State Management](/docs/guides/state-management)
- [Pagination: Manual or Server-Side Pagination](/docs/guides/pagination#manual-or-server-side-pagination)
- [Sorting: Manual Server-Side Sorting](/docs/guides/sorting#manual-server-side-sorting)
- [Column Filtering: Manual Server-Side Column Filtering](/docs/guides/column-filtering#manual-server-side-column-filtering)
- [Global Filtering: Manual Server-Side Global Filtering](/docs/guides/global-filtering#manual-server-side-global-filtering)
- [React Query Example](/docs/examples/react-query)
# Row Actions Guide (/docs/guides/row-actions)
The row actions feature is simply a pre-built [Display Column](/docs/guides/display-columns) feature that adds a column as a place to store either a row action menu or other row action buttons.
Using the built-in Row Actions column is optional, as you can simply create your own display columns, but this feature has some built-in conveniences that make it easy to add row actions to your table.
### Relevant Table Options [#relevant-table-options]
console.info('Edit')}>
Edit
,
console.info('Delete')}>
Delete
,
],
});
return
console.info('Edit')}>
console.info('Delete')}>
),
});
return
Button 1
Button 2
Button 3
),
});
```
#### Position Row Actions Column [#position-row-actions-column]
You can position the row actions column to the left or right (first or last column) of the table using the `positionActionsColumn` table option. The default is as the first column.
```jsx
const table = useShadcnTable({
columns,
data,
enableRowActions: true,
positionActionsColumn: 'last',
renderRowActions: ({ table }) => (
//...
),
})
```
View Extra Storybook **Examples **
# Row Numbers Guide (/docs/guides/row-numbers)
Shadcn Table has an easy to implement row number features. There are two row number modes that you can enable. You can have row numbers that are associated with the data in the table ([original mode](<#enable-row-numbers-(original-mode)>)), or you can have row numbers that are just statically part of the table ([static mode](<#enable-row-numbers-(static-mode)>)).
### Relevant Table Options [#relevant-table-options]
Examples **
# Row Ordering/DnD Guide (/docs/guides/row-ordering-dnd)
Shadcn Table has exposed all the APIs necessary to enable rich row drag-and-drop features that you can easily build to meet your needs. This includes the ability to reorder rows, drag rows to other tables, or drag rows to other UI in your application.
> This is not the [Sorting Guide](/docs/guides/sorting), which is a different feature.
### Relevant Table Options [#relevant-table-options]
Examples **
# Row Pinning Guide (/docs/guides/row-pinning)
Shadcn Table has a powerful row pinning feature that allows you to either pin rows to the top and bottom of the table as a user scrolls, or pin rows to the top and bottom of the table regardless of scrolling.
### Relevant Table Options [#relevant-table-options]
` element that itself is what is sticky.
Shift key and clicks a row, all rows between the last selected row and the clicked row will be selected. This is TanStack Table's range selection; it can be disabled with the `enableRowRangeSelection` table option, and the `isRowRangeSelectionEvent` option decides which events count as a range selection.
```jsx
const table = useShadcnTable({
columns,
data,
enableRowSelection: true,
enableRowRangeSelection: false, //disable batch row selection with shift key
});
```
### Access Row Selection State [#access-row-selection-state]
There are two ways to access the selection state. You can either manage the selection state yourself or read it from the table instance.
#### Manage Row Selection State [#manage-row-selection-state]
The row selection state is managed internally by default, but you will more than likely want to have access to that state yourself. Here is how you can simply get access to the row selection state, specifically:
```tsx
const [rowSelection, setRowSelection] = useState({}); //ts type available
const table = useShadcnTable({
columns,
data,
enableRowSelection: true,
onRowSelectionChange: setRowSelection,
state: { rowSelection },
});
return {
const rowSelection = table.state.rowSelection; //read state
const selectedRows = table.getSelectedRowModel().rows; //or read entire rows
}}
>
Download Selected Users
),
});
useEffect(() => {
//fetch data based on row selection state or something
}, [table.state.rowSelection]);
return Examples **
# Sorting Guide (/docs/guides/sorting)
Shadcn Table supports almost any sorting scenario you may have. Client-side sorting is enabled by default, but you can opt to implement your own server-side sorting logic or even replace the default client-side sorting with your own implementation.
### Relevant Table Options [#relevant-table-options]
Examples **
# State Management Guide (/docs/guides/state-management)
Shadcn Table does not try to hide any of its internal state from you. You can initialize state with custom initial values, manage individual states yourself as you discover the need to have access to them, or read any of the state from the table instance itself.
This is all optional, of course. If you do not need access to any of the internal state, you do not need to do anything and it will just automatically be managed internally.
See the [State Options API Docs](/docs/api/state-options) for more information on which states are available for you to manage.
### Relevant Table Options [#relevant-table-options]
) => {
//call the setState as normal, but need to check if using an updater callback with a previous state
setPagination((prevPagination) =>
//if updater is a function, call it with the previous state, otherwise just use the updater value
updater instanceof Function ? updater(prevPagination) : updater,
);
//put more code for your side effects here, guaranteed to only run once, even in React Strict Mode
};
const table = useShadcnTable({
columns,
data,
onPaginationChange: handlePaginationChange,
state: { pagination },
});
return
Export or Something
);
```
The table instance is the same object that you will also see as a provided parameter in many of the other callback functions throughout Shadcn Table, such as all the `render...` props or the `Cell` or `Header` render overrides in the column definition options.
```jsx
const columns = useMemo(
() => [
{
Header: 'Name',
accessor: 'name',
Cell: ({ cell, table }) => {cell.getValue()} ,
//The `table` parameter from the Cell option params and the `table` are the same object
},
],
[],
);
const table = useShadcnTable({
columns,
data,
renderTopToolbarCustomActions: ({ table }) => {
//The `table` parameter here and the table returned from the hook are the same object
return Button ;
},
});
return Examples **
# Table Event Listeners Guide (/docs/guides/table-event-listeners)
You can pretty much add ANY event listener to ANY component in Shadcn Table.
You can do this by passing props to any of the `st...Props` props. This guide gives a few examples of the most common use cases, but there are limitless possibilities.
### Add Event Listeners to any of the shadcn/ui Components [#add-event-listeners-to-any-of-the-shadcnui-components]
In the [customize components docs](/docs/guides/customize-components#props-and-types), we explained how to pass any prop you need to pass to any exposed shadcn/ui component that is in the table. The list of props that you can pass to shadcn/ui components includes any event listener.
Here are a few common examples of some useful event listeners you might want to add to the table, although the possibilities are countless.
#### Add an onClick to a Table Row [#add-an-onclick-to-a-table-row]
```jsx
const table = useShadcnTable({
columns,
data,
stTableBodyRowProps: ({ row }) => ({
onClick: (event) => {
console.info(event, row.id);
},
style: {
cursor: 'pointer', //you might want to change the cursor too when adding an onClick
},
}),
});
```
#### Add an onDoubleClick to a Table Cell [#add-an-ondoubleclick-to-a-table-cell]
```jsx
const table = useShadcnTable({
columns,
data,
stTableBodyCellProps: ({ cell }) => ({
onDoubleClick: (event) => {
console.info(event, cell.id);
},
}),
});
```
#### Add an onBlur to an Edit TextField [#add-an-onblur-to-an-edit-textfield]
```jsx
//add to every edit text field
const table = useShadcnTable({
columns,
data,
stEditTextFieldProps: ({ cell }) => ({
onBlur: (event) => {
console.info(event, cell.id);
},
}),
});
```
```jsx
//or add to just edit text fields in a specific column
const columns = [
{
accessorKey: 'name',
header: 'Name',
stEditTextFieldProps: ({ cell }) => ({
onBlur: (event) => {
console.info(event);
},
}),
},
];
```
#### Add an onChange to an Edit TextField [#add-an-onchange-to-an-edit-textfield]
> Warning: Be careful when using onChange, as it can trigger re-renders with every keystroke, which can lead to performance issues
```jsx
const table = useShadcnTable({
columns,
data,
stEditTextFieldProps: ({ cell }) => ({
onChange: (event) => {
console.info(event, cell.id);
},
}),
});
```
```jsx
//or add to just edit text fields in a specific column
const columns = [
{
accessorKey: 'name',
header: 'Name',
stEditTextFieldProps: ({ cell }) => ({
onChange: (event) => {
console.info(event);
},
}),
},
];
```
# Toolbar Customization Guide (/docs/guides/toolbar-customization)
This guide shows you how to [hide](#hide-or-disable-toolbars), [customize](#customize-toolbar-buttons), or [override](#override-with-custom-toolbar-components) the top and bottom toolbars in Shadcn Table.
### Relevant Table Options [#relevant-table-options]
showPrintPreview(true)}>
{/* built-in buttons (must pass in table prop for them to work!) */}
Customer's Table
),
//Adding a custom button to the bottom toolbar
renderBottomToolbarCustomActions: ({ table }) => (
handleDownloadRows(table.getSelectedRowModel().rows)}
>
Download Selected Rows
),
});
return ... ,
});
return
),
renderBottomToolbar: ({ table }) => (
Download
),
});
return ` element to prevent columns from wiggling back and forth during scrolling due to body cells having varying widths.
But now in ST Versions 1.4 and later, the `layoutMode` table option is automatically set to the `'grid'` value when either row or column virtualization is enabled, which means that all of the table markup will use CSS Grid and Flexbox instead of the traditional semantic styles that usually come with table tags. This is necessary to make the virtualization work properly with decent performance.
#### `enableStickyHeader` Prop [#enablestickyheader-prop]
The `enableStickyHeader` table option is automatically set to `true` when row virtualization is enabled. This keeps the table header sticky and visible while scrolling and adds a default max-height of 100vh to the table container.
### Customize Virtualizer Props [#customize-virtualizer-props]
You can adjust some of the virtualizer props that are used internally with the `rowVirtualizerOptions` and `columnVirtualizerOptions` props. The most useful virtualizer props are the `overscan` and `estimateSize` options. You may want to adjust these values if you have unusual row heights or column widths that are causing the default scrolling to behave strangely.
```jsx
400, //if your columns are wider or , try tweaking this value to make scrollbar size more accurate
}}
rowVirtualizerOptions={{
overscan: 10, //adjust the number or rows that are rendered above and below the visible area of the table
estimateSize: () => 100, //if your rows are taller than normal, try tweaking this value to make scrollbar size more accurate
}}
/>
```
See the official TanStack [Virtualizer Options API Docs](https://tanstack.com/virtual/v3/docs/api/virtualizer#optional-options) for more information.
### Access Underlying Virtualizer Instances [#access-underlying-virtualizer-instances]
In a similar way that you can [access the underlying table instance](/docs/guides/table-state-management#access-the-underlying-table-instance-reference), you can also access the underlying virtualizer instances. This can be useful for accessing methods like the `scrollToIndex` method, which can be used to programmatically scroll to a specific row or column.
```tsx
const columnVirtualizerInstanceRef = useRef(null);
const rowVirtualizerInstanceRef = useRef(null);
useEffect(() => {
if (rowVirtualizerInstanceRef.current) {
//scroll to the top of the table when sorting changes
rowVirtualizerInstanceRef.current.scrollToIndex(0);
}
}, [sorting]);
return (
Examples **
### Headless Virtualization with ST Hooks [#headless-virtualization-with-st-hooks]
If you are building a custom table in headless mode, you can still take advantage of some of the built-in virtualization functionality via the `useST_ColumnVirtualizer` and `useST_RowVirtualizer` hooks, which are wrappers for the TanStack Virtual `useVirtualizer` hook.
If you go this route, you will need to consult the [TanStack Virtual Docs](https://tanstack.com/virtual/v3) for more information on the exact styles and markup needed for the virtualization to work properly.
Here is the basics of how to use the ST virtualization hooks:
```tsx
import {
useShadcnTable,
useST_Rows,
useST_RowVirtualizer,
useST_ColumnVirtualizer,
} from '@/components/ui/shadcn-table';
const table = useShadcnTable({
columns,
data,
enableColumnVirtualization: true,
enableRowVirtualization: true,
columnVirtualizerOptions: {
//...virtualizer options
},
rowVirtualizerOptions: {
//...virtualizer options
},
});
const rows = useST_Rows(table); //alternative to table.getRowModel()
const columnVirtualizer = useST_ColumnVirtualizer(table);
const rowVirtualizer = useST_RowVirtualizer(table);
//down in your row render
const virtualRows = rowVirtualizer.getVirtualItems();
virtualRows.map((virtualRow) => {
const row = rows[virtualRow.index];
return |
;
});
```
Alternatively, just use the `useVirtualizer` hook directly from `@tanstack/react-virtual` if you want to build your own virtualization logic from scratch. The ST hooks are provided as opinionated wrappers for your potential convenience.