+
+
-
-
- 
-
+
+
+
-
- 
-
-
- 
-
-
- 
-
-
-> [Looking for version 7 of `react-table`? Click here!](https://github.com/tanstack/table/tree/v7)
-
-## Enjoy this library?
-
-Try other [TanStack](https://tanstack.com) libraries:
-
-- [TanStack Query](https://github.com/TanStack/query) 
-- [TanStack Table](https://github.com/TanStack/table) 
-- [TanStack Router](https://github.com/TanStack/router) 
-- [TanStack Virtual](https://github.com/TanStack/virtual) 
-- [TanStack Form](https://github.com/TanStack/form) 
-- [TanStack Ranger](https://github.com/TanStack/ranger) 
-
-## Visit [tanstack.com/table](https://tanstack.com/table) for docs, guides, API and more!
-
-You may know **TanStack Table** by our adapter names, too!
-
-- [Angular Table](https://tanstack.com/table/v8/docs/framework/angular/angular-table)
-- [Lit Table](https://tanstack.com/table/v8/docs/framework/lit/lit-table)
-- [Qwik Table](https://tanstack.com/table/v8/docs/framework/qwik/qwik-table)
-- [**React Table**](https://tanstack.com/table/v8/docs/framework/react/react-table)
-- [Solid Table](https://tanstack.com/table/v8/docs/framework/solid/solid-table)
-- [Svelte Table](https://tanstack.com/table/v8/docs/framework/svelte/svelte-table)
-- [Vue Table](https://tanstack.com/table/v8/docs/framework/vue/vue-table)
-
-## Summary
-
-TanStack Table is a **headless** table library, which means it does not ship with components, markup or styles. This means that you have **full control** over markup and styles (CSS, CSS-in-JS, UI Component Libraries, etc) and this is also what gives it its portable nature. You can even use it in React Native!
-
-If you want a **lightweight table with full control over markup and implementation**, then you should consider using **TanStack Table, a headless table library**.
-
-If you want a **ready-to-use component-based table with more power but more constraints around markup/styles/implementation**, you should consider using [AG Grid](https://ag-grid.com/react-data-grid/?utm_source=reacttable&utm_campaign=githubreacttable), a component-based table library from our OSS partner [AG Grid](https://ag-grid.com).
-
-TanStack Table and AG Grid are respectfully the
-**best table/datagrid libraries around**. Instead
-of competing, we're working together to ensure the highest
-quality table/datagrid options are available for the entire
-JS/TS ecosystem and every use-case.
-
-## Quick Features
-
-- Agnostic core (JS/TS)
-- 1st-class framework bindings for React, Vue, Solid
-- ~15kb or less (with tree-shaking)
-- 100% TypeScript (but not required)
-- Headless (100% customizable, Bring-your-own-UI)
-- Auto out of the box, opt-in controllable state
-- Filters (column and global)
-- Sorting (multi-column, multi-directional)
-- Grouping & Aggregation
-- Pivoting (coming soon!)
-- Row Selection
-- Row Expansion
-- Column Visibility/Ordering/Pinning/Resizing
-- Table Splitting
-- Animatable
-- Virtualizable
-- Server-side/external data model support
-
-# Migrating from React Table v7
-
-## Notable Changes
-
-- Full rewrite to TypeScript with types included in the base package
-- Removal of plugin system to favor more inversion of control
-- Vastly larger and improved API (and new features like pinning)
-- Better controlled state management
-- Better support for server-side operations
-- Complete (but optional) data pipeline control
-- Agnostic core with framework adapters for React, Solid, Svelte, Vue, and potentially more in the future
-- New Dev Tools
-
-## Migration
-
-There are a fair amount of breaking changes (they're worth it, trust us!):
-
-- Turns out that TypeScript makes your code **a lot** better/safer, but also usually requires breaking changes to architecture.
-- Plugin system has been removed so plugins must be rewritten to wrap/compose the new functional API. Contact us if you need help!
-- Column configuration options have changed, but only slightly.
-- Table options are mostly the same, with some larger changes around optional state management/control and data pipeline control
-- The `table` instance while similar in spirit to v7 has been reconfigured to be much faster.
-
-## Installation
-
-Install one of the following packages based on your framework of choice:
-
-```bash
-# Npm
-npm install @tanstack/angular-table
-npm install @tanstack/lit-table
-npm install @tanstack/qwik-table
-npm install @tanstack/react-table
-npm install @tanstack/solid-table
-npm install @tanstack/svelte-table
-npm install @tanstack/vue-table
-npm install @tanstack/table-core #vanilla js that can work with any framework
-```
-
-## How to help?
-
-- Try out the already-migrated examples
-- Try it out in your own projects.
-- Introspect the types! Even without the docs finished, the library ships with 100% typescript to help you explore its capabilities.
-- [Read the contribution guidelines](https://github.com/tanstack/table/tree/main/CONTRIBUTING.md)
-- Write some docs! Start with the [API docs](https://github.com/TanStack/react-table/tree/main/docs/api) and try adding some information about one or more of the features. The types do a decent job of showing what's supported and the capabilities of the library.
-- **Using a plugin?** Try rewriting your plugin (v8 doesn't have a plugin system any more) as a functional wrapper that uses TanStack Table internally. The new API is much more powerful and easier to compose. If you find something you can't figure out, let us know and we'll add it to the API.
-
-### [Become a Sponsor](https://github.com/sponsors/tannerlinsley/)
+
+ 
+
+
+ 
+ |
+
+
+ 
+ |
+
+
+ 
+ |
+
++We're looking for TanStack Table Partners to join our mission! Partner with us to push the boundaries of TanStack Table and build amazing things together. +
+LET'S CHAT +| ` or similar cell element in your UI. There are a few properties and methods on `header` objects that you can use to interact with the table state and extract cell values from the table based on the state of the table. +Header objects are similar to [Cell](../guide/cells) objects, but meant for the `` section of the table instead of the ` | ` section. Every header object can be associated with a `` or similar cell element in your UI. There are a few properties and methods on `header` objects that you can use to interact with the table state and extract cell values from the table based on the state of the table. #### Header IDs -Every header object has an `id` property that makes it unique within the table instance. Usually you only need this `id` as a unique identifier for React keys or if you are following the [performant column resizing example](../../framework/react/examples/column-resizing-performant). +Every header object has an `id` property that makes it unique within the table instance. Usually you only need this `id` as a unique identifier for React keys or if you are following the [performant column resizing example](../framework/react/examples/column-resizing-performant). For simple headers with no advanced nested or grouped headers logic, the `header.id` will be the same as it's parent `column.id`. However, if the header is part group column or a placeholder cell, it will have a more complicated id that is constructed from the header family, depth/header row index, column id, and header group id. @@ -65,11 +65,11 @@ There are a few properties on `header` objects that are only useful if the heade #### Header Parent Objects -Every header stores a reference to its parent [column](../columns) object and its parent [header group](../header-groups) object. +Every header stores a reference to its parent [column](../guide/columns) object and its parent [header group](../guide/header-groups) object. ### More Header APIs -Headers have a few more useful APIs attached to them that are useful for interacting with the table state. Most of them relate to the Column sizing and resizing features. See the [Column Resizing Guide](../column-resizing) for more information. +Headers have a few more useful APIs attached to them that are useful for interacting with the table state. Most of them relate to the Column sizing and resizing features. See the [Column Sizing Guide](../guide/column-sizing) for more information. ### Header Rendering @@ -81,4 +81,4 @@ Since the `header` column option you defined can be either a string, jsx, or a f {/* Handles all possible header column def scenarios for `header` */} {flexRender(header.column.columnDef.header, header.getContext())} | -))} \ No newline at end of file +))} diff --git a/docs/guide/pagination.md b/docs/guide/pagination.md index 8ff1aec367..6cc2b73f01 100644 --- a/docs/guide/pagination.md +++ b/docs/guide/pagination.md @@ -6,17 +6,17 @@ title: Pagination Guide Want to skip to the implementation? Check out these examples: -- [pagination](../../framework/react/examples/pagination) -- [pagination-controlled (React Query)](../../framework/react/examples/pagination-controlled) -- [editable-data](../../framework/react/examples/editable-data) -- [expanding](../../framework/react/examples/expanding) -- [filters](../../framework/react/examples/filters) -- [fully-controlled](../../framework/react/examples/fully-controlled) -- [row-selection](../../framework/react/examples/row-selection) +- [pagination](../framework/react/examples/pagination) +- [pagination-controlled (React Query)](../framework/react/examples/pagination-controlled) +- [editable-data](../framework/react/examples/editable-data) +- [expanding](../framework/react/examples/expanding) +- [filters](../framework/react/examples/filters) +- [fully-controlled](../framework/react/examples/fully-controlled) +- [row-selection](../framework/react/examples/row-selection) ## API -[Pagination API](../../api/features/pagination) +[Pagination API](../api/features/pagination) ## Pagination Guide @@ -30,7 +30,7 @@ Using client-side pagination means that the `data` that you fetch will contain * Client-side pagination is usually the simplest way to implement pagination when using TanStack Table, but it might not be practical for very large datasets. -However, a lot of people underestimate just how much data can be handled client-side. If your table will only ever have a few thousand rows or less, client-side pagination can still be a viable option. TanStack Table is designed to scale up to 10s of thousands of rows with decent performance for pagination, filtering, sorting, and grouping. The [official pagination example](../../framework/react/examples/pagination) loads 100,000 rows and still performs well, albeit with only handful of columns. +However, a lot of people underestimate just how much data can be handled client-side. If your table will only ever have a few thousand rows or less, client-side pagination can still be a viable option. TanStack Table is designed to scale up to 10s of thousands of rows with decent performance for pagination, filtering, sorting, and grouping. The [official pagination example](../framework/react/examples/pagination) loads 100,000 rows and still performs well, albeit with only handful of columns. Every use-case is different and will depend on the complexity of the table, how many columns you have, how large every piece of data is, etc. The main bottlenecks to pay attention to are: diff --git a/docs/guide/pinning.md b/docs/guide/pinning.md index c8951f9695..3d33e44ebb 100644 --- a/docs/guide/pinning.md +++ b/docs/guide/pinning.md @@ -6,5 +6,5 @@ title: Pinning Guide Pinning is split into 2 different feature guides: -- [Column Pinning](../column-pinning) -- [Row Pinning](../row-pinning) \ No newline at end of file +- [Column Pinning](./column-pinning.md) +- [Row Pinning](./row-pinning.md) \ No newline at end of file diff --git a/docs/guide/row-pinning.md b/docs/guide/row-pinning.md index e5ee91921b..8554253c9a 100644 --- a/docs/guide/row-pinning.md +++ b/docs/guide/row-pinning.md @@ -6,15 +6,15 @@ title: Row Pinning Guide Want to skip to the implementation? Check out these examples: -- [row-pinning](../../framework/react/examples/row-pinning) +- [row-pinning](../framework/react/examples/row-pinning) ## API -[Row Pinning API](../../api/features/row-pinning) +[Row Pinning API](../api/features/row-pinning) ## Row Pinning Guide There are 2 table features that can reorder rows, which happen in the following order: 1. **Row Pinning** - If pinning, rows are split into top, center (unpinned), and bottom pinned rows. -2. [Sorting](../sorting) \ No newline at end of file +2. [Sorting](../guide/sorting) diff --git a/docs/guide/row-selection.md b/docs/guide/row-selection.md index c3e7b29651..a5a868833b 100644 --- a/docs/guide/row-selection.md +++ b/docs/guide/row-selection.md @@ -6,13 +6,13 @@ title: Row Selection Guide Want to skip to the implementation? Check out these examples: -- [React row-selection](../../framework/react/examples/row-selection) -- [Vue row-selection](../../framework/vue/row-selection) -- [React expanding](../../framework/react/examples/expanding) +- [React row-selection](https://github.com/TanStack/table/tree/main/examples/react/row-selection) +- [Vue row-selection](https://github.com/TanStack/table/tree/main/examples/vue/row-selection) +- [React expanding](https://github.com/TanStack/table/tree/main/examples/react/expanding) ## API -[Row Selection API](../../api/features/row-selection) +[Row Selection API](../api/features/row-selection.md) ## Row Selection Guide diff --git a/docs/guide/rows.md b/docs/guide/rows.md index d2426453fc..a54fd50fd5 100644 --- a/docs/guide/rows.md +++ b/docs/guide/rows.md @@ -4,7 +4,7 @@ title: Rows Guide ## API -[Row API](../../api/core/row) +[Row API](../api/core/row) ## Rows Guide @@ -24,7 +24,7 @@ const row = table.getRow(rowId) #### Row Models -The `table` instance generates `row` objects and stores them in useful arrays called ["Row Models"](../row-models). This is discussed in much more detail in the [Row Models Guide](../row-models), but here are the most common ways you may access the row models. +The `table` instance generates `row` objects and stores them in useful arrays called ["Row Models"](../guide/row-models). This is discussed in much more detail in the [Row Models Guide](../guide/row-models), but here are the most common ways you may access the row models. ##### Render Rows @@ -85,7 +85,7 @@ const firstName = row.original.firstName // { firstName: 'John', lastName: 'Doe' ### Sub Rows -If you are using either grouping or expanding features, your rows may contain sub-rows or parent row references. This is discussed in much more detail in the [Expanding Guide](../expanding), but here is a quick overview of useful properties and methods for working with sub-rows. +If you are using either grouping or expanding features, your rows may contain sub-rows or parent row references. This is discussed in much more detail in the [Expanding Guide](../guide/expanding), but here is a quick overview of useful properties and methods for working with sub-rows. - `row.subRows`: An array of sub-rows for the row. - `row.depth`: The depth of the row (if nested or grouped) relative to the root row array. 0 for root level rows, 1 for child rows, 2 for grandchild rows, etc. @@ -94,4 +94,4 @@ If you are using either grouping or expanding features, your rows may contain su ### More Row APIs -Depending on the features that you are using for your table, there are dozens more useful APIs for interacting with rows. See each features' respective API docs or guide for more information. \ No newline at end of file +Depending on the features that you are using for your table, there are dozens more useful APIs for interacting with rows. See each features' respective API docs or guide for more information. diff --git a/docs/guide/sorting.md b/docs/guide/sorting.md index ec58b7fed4..13e756dfb8 100644 --- a/docs/guide/sorting.md +++ b/docs/guide/sorting.md @@ -6,12 +6,12 @@ title: Sorting Guide Want to skip to the implementation? Check out these examples: -- [sorting](../../framework/react/examples/sorting) -- [filters](../../framework/react/examples/filters) +- [sorting](../framework/react/examples/sorting) +- [filters](../framework/react/examples/filters) ## API -[Sorting API](../../api/features/sorting) +[Sorting API](../api/features/sorting) ## Sorting Guide diff --git a/docs/guide/tables.md b/docs/guide/tables.md index 2ee721f6e9..781ae37c6c 100644 --- a/docs/guide/tables.md +++ b/docs/guide/tables.md @@ -4,72 +4,102 @@ title: Table Instance Guide ## API -[Table API](../../api/core/table) +[Table API](../api/core/table.md) ## Table Instance Guide -TanStack Table is a headless UI library. When we talk about the `table` or "table instance", we're not talking about a literal `
|---|
|
+ |
+ }
+
|
+ |
+ }
+ }
+
|---|
|
+ |
+ }
+
|
+ |
+ }
+
|
+ @if (!header.isPlaceholder) {
+ |
+ }
+
|---|
|
+ |
+ }
+
+ {{ rawExpandedState() }}
+
+ {{ rawRowSelectionState() }}
+|
+ |
+ }
+ }
+
|---|
|
+ |
+ }
+
{{ sortedIds() | json }}
+|
+ @if (!header.isPlaceholder) {
+ |
+ }
+
|---|
|
+ |
+ }
+
|
+ |
+
+
+ {{ row.original | json }}
+
+
+| {header.isPlaceholder ? null : flexRender( header.column.columnDef.header, - header.getContext() + header.getContext(), )} | ))} @@ -114,9 +114,9 @@ const App = component$(() => { ))}|||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| {flexRender(cell.column.columnDef.cell, cell.getContext())} | @@ -125,15 +125,15 @@ const App = component$(() => { ))}|||||||||||||
| {header.isPlaceholder ? null : flexRender( header.column.columnDef.footer, - header.getContext() + header.getContext(), )} | ))} diff --git a/examples/qwik/filters/package.json b/examples/qwik/filters/package.json index 4d62e5619a..bc6efee9fc 100644 --- a/examples/qwik/filters/package.json +++ b/examples/qwik/filters/package.json @@ -1,7 +1,6 @@ { "name": "tanstack-table-example-qwik-filters", "private": true, - "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", @@ -16,7 +15,7 @@ "vite": "^5.3.2" }, "dependencies": { - "@tanstack/qwik-table": "^8.20.5", - "@tanstack/match-sorter-utils": "^8.19.4" + "@tanstack/match-sorter-utils": "^8.19.4", + "@tanstack/qwik-table": "^8.21.3" } } diff --git a/examples/qwik/filters/src/main.tsx b/examples/qwik/filters/src/main.tsx index 95063efa5f..3bdc78c474 100644 --- a/examples/qwik/filters/src/main.tsx +++ b/examples/qwik/filters/src/main.tsx @@ -59,7 +59,7 @@ const fuzzySort: SortingFn
| {header.isPlaceholder ? null : ( @@ -235,7 +235,7 @@ const App = component$(() => { > {flexRender( header.column.columnDef.header, - header.getContext() + header.getContext(), )} {{ asc: ' 🔼', @@ -256,10 +256,10 @@ const App = component$(() => { ))} | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| {flexRender(cell.column.columnDef.cell, cell.getContext())} | diff --git a/examples/qwik/row-selection/package.json b/examples/qwik/row-selection/package.json index 900aed03c1..fd842b4594 100644 --- a/examples/qwik/row-selection/package.json +++ b/examples/qwik/row-selection/package.json @@ -1,7 +1,6 @@ { "name": "tanstack-table-example-qwik-row-selection", "private": true, - "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", @@ -16,6 +15,6 @@ "vite": "^5.3.2" }, "dependencies": { - "@tanstack/qwik-table": "^8.20.5" + "@tanstack/qwik-table": "^8.21.3" } } diff --git a/examples/qwik/row-selection/src/main.tsx b/examples/qwik/row-selection/src/main.tsx index 3c24e842a7..bd9313c416 100644 --- a/examples/qwik/row-selection/src/main.tsx +++ b/examples/qwik/row-selection/src/main.tsx @@ -97,30 +97,30 @@ const columns: ColumnDef
| {flexRender(cell.column.columnDef.cell, cell.getContext())} | @@ -204,7 +204,7 @@ const App = component$(() => { onClick$={() => console.info( 'table.getSelectedRowModel().flatRows', - table.getSelectedRowModel().flatRows + table.getSelectedRowModel().flatRows, ) } > diff --git a/examples/qwik/sorting/package.json b/examples/qwik/sorting/package.json index 290747eeb0..14bdeeadd2 100644 --- a/examples/qwik/sorting/package.json +++ b/examples/qwik/sorting/package.json @@ -1,7 +1,6 @@ { "name": "tanstack-table-example-qwik-sorting", "private": true, - "version": "0.0.0", "type": "module", "scripts": { "dev": "vite", @@ -16,6 +15,6 @@ "vite": "^5.3.2" }, "dependencies": { - "@tanstack/qwik-table": "^8.20.5" + "@tanstack/qwik-table": "^8.21.3" } } diff --git a/examples/qwik/sorting/src/main.tsx b/examples/qwik/sorting/src/main.tsx index d1a4d4488f..0d6ebaae57 100644 --- a/examples/qwik/sorting/src/main.tsx +++ b/examples/qwik/sorting/src/main.tsx @@ -25,41 +25,41 @@ type Person = { const columns: ColumnDef
| {flexRender( cell.column.columnDef.cell, - cell.getContext() + cell.getContext(), )} | ) diff --git a/examples/react/basic/package.json b/examples/react/basic/package.json index 8c7c6bd7e0..d2aa60342f 100644 --- a/examples/react/basic/package.json +++ b/examples/react/basic/package.json @@ -1,6 +1,5 @@ { "name": "tanstack-table-example-basic", - "version": "0.0.0", "private": true, "scripts": { "dev": "vite", @@ -9,7 +8,7 @@ "start": "vite" }, "dependencies": { - "@tanstack/react-table": "^8.20.6", + "@tanstack/react-table": "^8.21.3", "react": "^18.3.1", "react-dom": "^18.3.1" }, diff --git a/examples/react/basic/src/main.tsx b/examples/react/basic/src/main.tsx index c1f615525e..b2226b2746 100644 --- a/examples/react/basic/src/main.tsx +++ b/examples/react/basic/src/main.tsx @@ -50,31 +50,31 @@ const columnHelper = createColumnHelper
| {header.isPlaceholder ? null : flexRender( header.column.columnDef.header, - header.getContext() + header.getContext(), )} | ))} @@ -108,9 +108,9 @@ function App() { ))}||||||
|---|---|---|---|---|---|---|
| {flexRender(cell.column.columnDef.cell, cell.getContext())} | @@ -119,15 +119,15 @@ function App() { ))}||||||
| {header.isPlaceholder ? null : flexRender( header.column.columnDef.footer, - header.getContext() + header.getContext(), )} | ))} @@ -149,5 +149,5 @@ if (!rootElement) throw new Error('Failed to find the root element') ReactDOM.createRoot(rootElement).render(||||||
| {header.isPlaceholder ? null : flexRender( header.column.columnDef.header, - header.getContext() + header.getContext(), )} | ))} @@ -95,9 +95,9 @@ function App() { ))}||||||
| {flexRender(cell.column.columnDef.cell, cell.getContext())} | @@ -106,15 +106,15 @@ function App() { ))}||||||
| {header.isPlaceholder ? null : flexRender( header.column.columnDef.footer, - header.getContext() + header.getContext(), )} | ))} @@ -137,5 +137,5 @@ if (!rootElement) throw new Error('Failed to find the root element') ReactDOM.createRoot(rootElement).render(
| {header.isPlaceholder ? null : flexRender( header.column.columnDef.header, - header.getContext() + header.getContext(), )} | ))} @@ -125,9 +125,9 @@ function App() { ))}
|---|
| {flexRender(cell.column.columnDef.cell, cell.getContext())} | @@ -136,15 +136,15 @@ function App() { ))}
| {header.isPlaceholder ? null : flexRender( header.column.columnDef.footer, - header.getContext() + header.getContext(), )} | ))} @@ -166,5 +166,5 @@ if (!rootElement) throw new Error('Failed to find the root element') ReactDOM.createRoot(rootElement).render(