Overview

TanStack Table is a headless UI library for building powerful tables and datagrids. Its core is framework agnostic, which means its API is the same regardless of the framework you are using. Official adapters are provided for React, Preact, Vue, Solid, Svelte, Angular, and Lit, and you can use the core directly in vanilla TypeScript or JavaScript via @tanstack/table-core.

These docs are for TanStack Table v9, which is currently in beta. The docs for v8, the latest stable release, live at tanstack.com/table/v8. When installing v9 packages, use the beta npm tag (see the Installation page).

If you are upgrading from v8, start with the migration guide for your framework:

Migrating to V9

What is "Headless" UI?

Headless UI is a term for libraries and utilities that provide the logic, state, processing, and APIs for UI elements and interactions, but do not provide markup, styles, or pre-built implementations. The hardest parts of building complex UIs usually revolve around state, events, side effects, and data processing. By removing those concerns from the markup and styles, your logic becomes more modular and reusable, while you keep complete control over the look and feel. When you use a headless library like TanStack Table, the complex work of data processing, state management, and business logic is handled for you, leaving you to focus on the higher-cardinality decisions that differ across designs and use cases.

Want to dive deeper? Read more about Headless UI.

Component-Based vs Headless Libraries

In the ecosystem of table and datagrid libraries, there are two main categories, and each comes with tradeoffs:

Component-based table libraries ship a feature-rich, drop-in solution with ready-to-use components, markup, styles, and theming. AG Grid is a great example of this kind of library, and is by far our favorite grid-sibling (don't tell the others). You get a turn-key experience with little setup, at the cost of less control over markup, theme-based styling, larger bundle sizes, and tighter coupling to specific frameworks and platforms. If you want a ready-to-use table and design or bundle size are not hard requirements, a component-based library like AG Grid is a great choice.

Headless table libraries supply functions, state, and utilities that you wire into your own table markup (or attach to existing markup). You get full control over markup and styles, support for every styling pattern (CSS, CSS-in-JS, UI component libraries), smaller bundle sizes, and portability anywhere JavaScript runs, at the cost of a bit more setup and no provided markup or themes. If you want a lighter-weight table or full control over the design, TanStack Table was made for you.

TypeScript

While TanStack Table is written in TypeScript, using TypeScript in your application is optional (but recommended, as it comes with outstanding benefits to both you and your codebase).

If you use TypeScript, you will get top-notch type safety and editor autocomplete for all table APIs and state.

Agnostic

Since TanStack Table is headless and runs on a vanilla TypeScript core, it is agnostic in a couple of ways:

TanStack Table is framework agnostic, which means you can use it with any JavaScript framework (or library) that you want. TanStack Table provides ready-to-use adapters for React, Preact, Vue, Solid, Svelte, Angular, and Lit out of the box, and the framework-agnostic core works in vanilla TypeScript or JavaScript and even in JS-to-native platforms like React Native. You can also create your own adapter if you need to.
TanStack Table is CSS / component library agnostic, which means that you can use TanStack Table with whatever CSS strategy or component library you want. TanStack Table itself does not render any table markup or styles. You bring your own! Want to use Tailwind or ShadCN? No problem! Want to use Material UI or Bootstrap? No problem! Have your own custom design system? TanStack Table was made for you!

Core Objects and Types

Before diving into the object model, it helps to understand three concepts that are new in v9 and shape how everything else works:

Opt-in features: Every table feature (sorting, filtering, row selection, and so on) is now opt-in. You declare exactly which features your table uses via the features table option, built with the tableFeatures() helper. This enables tree-shaking, so you only bundle the code for the features you actually use. If you want every feature enabled, v8-style, you can pass the provided stockFeatures object instead.
State atoms backed by TanStack Store: Each slice of table state (sorting, pagination, column visibility, and so on) lives in its own reactive atom powered by TanStack Store. Adapters subscribe to only the atoms you actually read, enabling fine-grained re-rendering, and you can supply your own external atoms to take full control of any state slice.
Row models as explicit opt-ins: Data transformations such as filtering, sorting, grouping, expanding, and pagination are performed by row models that you register explicitly as factory slots on the tableFeatures() call, using factories like createSortedRowModel() and createFilteredRowModel(). If you do not register a row model, its processing code never ships in your bundle.
The table core then uses the following abstractions, commonly exposed by adapters:
Data - The core data array you provide the table
Column Defs: Objects used to configure a column and its data model, display templates, and more
Table Instance: The core table object containing both state and API
Row Models: How the data array is transformed into useful rows depending on the features you are using
Rows: Each row mirrors its respective row data and provides row-specific APIs
Cells: Each cell mirrors its respective row-column intersection and provides cell-specific APIs
Header Groups: Header groups are computed slices of nested header levels, each containing a group of headers
Headers: Each header is either directly associated with or derived from its column def and provides header-specific APIs
Columns: Each column mirrors its respective column def and also provides column-specific APIs

Features

TanStack Table will help you build just about any type of table you can imagine. It has built-in state and APIs for the following features, each of which you can opt in to individually:

Faceting - List unique values or min/max values for a column or for the entire table
Column Filtering - Filter rows based on search values for a column
Column Grouping - Group columns together, run aggregations, and more
Column Ordering - Dynamically change the order of columns
Column Pinning - Pin (Freeze) columns to the left or right of the table
Column Resizing - Let users resize columns with drag handles
Column Sizing - Dynamically change the size of columns
Column Visibility - Hide/show columns
Global Filtering - Filter rows based on search values for the entire table
Row Expanding - Expand/collapse rows (sub-rows)
Row Pagination - Paginate rows
Row Pinning - Pin (Freeze) rows to the top or bottom of the table
Row Selection - Select/deselect rows (checkboxes)
Row Sorting - Sort rows by column values

These are just some of the capabilities that you can build with TanStack Table. There are many more features that are possible with TanStack Table that you can add along-side the built-in features.

Virtualization is an example of a feature that is not built in to TanStack Table, but can be achieved by using another library (like TanStack Virtual) alongside your other table rendering logic. Each framework has its own Virtualization guide in the Feature Guides section of the navigation.

TanStack Table also supports custom features (plugins) that you can use to modify the table instance and add your own custom logic to the table in a more integrated way. See the Custom Features guide for your framework to learn more.

And of course, you can just write your own state and hooks to add whatever other features you want for your table. The features from the TanStack Table core are just a solid foundation to build on, with a large focus on performance and DX.