TanStack Table V9 RFC

[KevinVandy]

Introduction

TanStack Table V9 is nearing new alpha and beta releases. Significant effort has been dedicated to making TanStack Table a more modular and tree-shakable library. This will enable it to scale its feature set more effectively without introducing unnecessary bloat for features that only a small subset of applications require.

Goals of TanStack Table V9

TanStack does not release new major versions for no reason. Major version releases include breaking changes that are necessary to steer the library back into a more sustainable direction. Here are the main goals we have with the upcoming V9 release:

• Set up TanStack Table for a future where it can grow into a larger library with dramatically more features for niche use cases WITHOUT affecting bundle size adversely. (Modular architecture with better tree-shaking)
• Add much more official specifications and internal unit testing of those specifications to make it more clear how each API is expected to work. (And yes, better docs)
• Make TanStack Table more extensible and easier to customize with an official plugin system.
• Kick Type-Safety up a few notches without crashing the TypeScript server or making it much more difficult to use in userland.
• Fix some bugs that require breaking changes.
• Upgrade Peer Dependencies for each framework adapter to newer major versions. (Especially Svelte 5, Angular 19, and compatibility for the new React Compiler)

Lower Priorities (Not in Scope for Initial 9.0 Release)

There are lots of new features that we could add to TanStack Table, but we are not spending time on them yet. TanStack Table V9 is focussed on a new modular architecture, first and foremost. Outside of how the useTable hook is set up, we are hoping for easy upgrades.

• No grand new feature set yet
• No state management overhaul (like fine-grained re-rendering) yet

These are all important things that we really want to add to TanStack Table, but we will not be able to ship these without delaying a potential V9 release by an even longer amount of time. Plus, we want to stagger the amount of breaking changes we make to the API to make the upgrade paths as smooth as possible.

Scope of this RFC

This Request for Comments (RFC) focuses specifically on the new syntax and code organization in TanStack Table V9. We aim to keep this discussion targeted and avoid turning it into a broader conversation about individual feature implementations or a wish list for new features. The current goal is to lay the foundation for these enhancements.

This RFC is mostly using React syntax, but the same concepts apply to other frameworks.

Here are some links to TanStack Table V9 alpha examples in different frameworks:

• React Filtering V9 Example
• Solid Sorting V9 Example
• Svelte Sorting V9 Example
• Vue Sorting V9 Example
• Angular Filtering V9 Example

Feedback That We Are Looking For

This is an RFC, so we are looking for feedback on the new code structure, naming conventions, and other changes.

We are not necessarily looking for a big wish list of brand new features right now, unless you are willing to help implement them and get them shipped within the next few months. However, keep in mind that with the new plugin system, you will be able to add your own features to TanStack Table, or even install additional official plugins aside from the stock features that we are initially including. Eventually, we envision many plugins becoming official TanStack Table features.

Overview of Changes

This is not an exhaustive changelog, but a summary of the most important changes that have been worked on so far in the alpha branch.

• Renamed useReactTable to useTable, createSvelteTable to createTable, createAngularTable to injectTable, etc.

  • This renaming was done in order to follow the naming conventions of other TanStack libraries more closely.

• Tree-Shakable Features:

  • The new starting bundle size is approximately ~4KB (still in progress) compared to the previous 14-20KB. This is the bundle size of just importing the useTable hook.
    • Bundle size now grows based on imported and utilized features, reducing unnecessary code in your bundle.
    • If you are using all features, the bundle size will be slightly larger than V8 at up to 20kb, but the average usage of TanStack Table should be less < 10kb for an average table now.
  • Features (Related APIs found on the table, column, row, cell, etc. objects) are no longer included in the table instance by default. They must be explicitly imported and passed to the useTable hook's _features option.
  • Row Models:
    • Row models are now specified in the _rowModels table option, similar to _features.
    • The default row model implementation methods have been renamed from get*RowModel to create*RowModel.
    • The core row model is now included internally by default and does not need to be imported or specified unless overridden.
    • Functions such as sortFns, filterFns, and aggregationFns are no longer table options and no longer included by default under the hood. They must be imported and passed to the appropriate create*RowModel function.
    • If using server-side (manual) options, importing these functions is unnecessary, reducing bundle size.
  • New TFeatures TypeScript Generic:
    • V8 had two common generics: TData (for row data shape) and TValue (for column/cell value types).
    • V9 introduces TFeatures to track registered and loaded _features in a table instance.
      • All other TanStack Table types now respond to this TFeatures generic. TypeScript will warn if you attempt to use a table, row, column, etc., API for an unregistered feature. For example, calling column.pin() without registering columnPinningFeature will produce a TypeScript error.
  • TypeScript Types Refactor:
    • Almost every underlying type has been renamed or refactored in order to make more sense for the new tree-shakable architecture. As long as you were only importing types such as ColumnDef, Column, Row, Table, etc., you should not be affected by these changes.
  • Static function imports available:
    • The builder pattern APIs are still the recommended way to use TanStack Table (e.g. table.getState(), or column.pin()). However, due to the new tree-shakable architecture refactor, every API in TanStack Table now has an equivalent static function that can be imported and used. (e.g. table_getState(table), or column_pin(column)). These static functions will be un-memoized variants of the builder pattern APIs that can also be useful for advanced tree-shaking optimizations. Though, due to them being un-memoized, they are not recommended for most use cases, especially in React.

• New Utilities:

  • createTableHelper: Utility for making table factories to share code setup between multiple tables.
    • Includes a useTable method, a easier to use createColumnHelper method that reduces a lot of manual type-safety boilerplate.
  • tableOptions: Simpler utility for sharing common table options between tables.
  • tableFeatures: Easier way to make a _features object with auto-complete/type-safety.

Things That Are Staying the Same

• State Management:
  • State management in V9 will work identically to V8. Although fine-grained re-rendering has been explored, it will not be part of the initial V9 release.
• Render UI Logic:
  • Changes in V9 primarily affect how the table instance is defined in [create/use]Table hooks. The render logic remains unchanged, though you may need to adjust APIs if not using certain features. For example, if columnVisibilityFeature is unregistered, you would replace row.getVisibleCells with row.getAllCells, as column visibility APIs would be unavailable.
• Feature Set:
  • This release is foundational, focusing on architecture rather than introducing major new features. Breaking changes have been made for bug fixes, but most features remain unchanged. Future additions will leverage the new tree-shakable architecture. This refactor will make TanStack's ability to include many more features in the future possible.

Stock Feature Set

Here is the current stock feature list:

• columnFacetingFeature
• columnFilteringFeature
• columnGroupingFeature
• columnOrderingFeature
• columnPinningFeature
• columnResizingFeature
• columnSizingFeature
• columnVisibilityFeature
• globalFacetingFeature
• globalFilteringFeature
• rowExpandingFeature
• rowPaginationFeature
• rowPinningFeature
• rowSelectionFeature
• rowSortingFeature

The V9 refactor split groups of code into different features to be independently imported. Some features that used to be thought of as 1 single feature have been split into multiple features. This is to make it easier to only import the features that you need. For example, column size features have been split into columnSizingFeature and columnResizingFeature, so that tables that only need the logic to set initial column sizes can import just columnSizingFeature without importing the logic for users to be able to resize columns. Filtering features were split into columnFilteringFeature, globalFilteringFeature, columnFacetingFeature, and globalFacetingFeature in a similar way.

You will be able to import all of these features independently from each other (for the most part). There are a couple of features that are dependent on each other. For example globalFilteringFeature is dependent on columnFilteringFeature, and columnResizingFeature is dependent on columnSizingFeature also being present. This will be made clear in the docs, and we are exploring just adding some type-safe discriminated unions to the _features object to make it more obvious which features are dependent on each other.

Examples

Let's dive into the practical differences between V8 and V9 with some common examples.

Old V8 Example

Here’s an old V8 example for reference that shows off client-side sorting.

import {
  createColumnHelper,
  getCoreRowModel,
  getSortedRowModel,
  useReactTable,
  type ColumnDef,
  type SortingState,
} from '@tanstack/react-table'

const columnHelper = createColumnHelper<Person>()

const columns: Array<ColumnDef<Person>> = [
  columnHelper.accessor('firstName', {}),
  //...
]

//...
const [sorting, setSorting] = React.useState<SortingState>([])

const table = useReactTable({
  columns,
  data,
  getCoreRowModel: getCoreRowModel(), // core row model was required in V8
  getSortedRowModel: getSortedRowModel(), // only for client-side sorting
  onSortingChange: setSorting,
  state: {
    sorting,
  },
})

return // render table UI

Similar V9 Example

Next, let's take a look at what the same example as up above would look like after upgrading to V9. This is a typical upgrade path. Down below, we'll discuss some helper utils to make this code easier to deal with.

import {
  createColumnHelper,
  createSortedRowModel, // renamed from getSortedRowModel
  rowSortingFeature, // The feature APIs are no longer included by default, import to use
  sortFns, // Not all of the sortFns are included by default. Import to use all of them
  tableFeatures, // optional util to specify table features with auto-complete/type-safety
  useTable, // renamed to follow naming conventions of other TanStack libs
  type SortingState,
} from '@tanstack/react-table'

// import and define the features that our table will actually use.
// Note: this example (without the new tableHelper util) will need to reference `typeof _features` in a few places)
const _features = tableFeatures({
  rowSortingFeature,
})

const columnHelper = createColumnHelper<typeof _features, Person>()

const columns = columnHelper.columns([
  columnHelper.accessor('firstName', {}),
  //...
])

//...
const [sorting, setSorting] = React.useState<SortingState>([])

const table = useTable({
  _features,
  _rowModels: {
    // notice: core row model is no longer required, as it is included by default under the hood
    sortedRowModel: createSortedRowModel(sortFns), // only if client-side sorting (also pass in the sortFns here)
  },
  columns,
  data,
  onSortingChange: setSorting,
  state: {
    sorting,
  },
})

return // render table UI

Let's discuss what's changed here.

First of all, the resulting bundle size of this new code will be about 6kb in V9 as opposed to about 16kb that it was in V8 (Only considering code from TanStack Table). This small of a difference is not going to change the world, but it's going to make a huge difference in future versions of TanStack Table where we might envision up to 50-100kb of additional features being available from the library.

Code-wise, the most notable change is that any table options that have to do with importing and registering code that is used to create the table instance lives in table options that are prefixed with an underscore. (_features and _rowModels)

On the surface, it looks like V9 is getting more complicated than the previous version. This is somewhat true, but it is a tradeoff that we believe will be worth it. We are also introducing some other helper utilities that are discussed down below to make this just about as easy to use as V8.

Outside of how features and row models are defined, very little else is changing. We are not even showing the rendering logic in the above examples since that is expected to largely remain the same. Although you may need to swap which APIs are being called if you no longer wish to use a particular feature. The most common example of this would be swapping row.getVisibleCells with row.getAllCells if your _features does not include columnVisibilityFeature.

Revamped Helper Utilities

V9 with the New Table Helper Utility

Configuring a TanStack Table table instance can be thought of as two main things going on.

1. Loading in the appropriate code to construct the table with the features that will be used
2. Passing in columns, data, and other table option customizations

V9 is introducing a new createTableHelper method to make creating multiple tables throughout your code base easier. Use the table helper util to configure features and row models, and other common table options once, then you will be able to create multiple table instances from this table helper.

Using the createTableHelper will help you only have to think about configuring the _features and _rowModels once in your codebase, and then you can create multiple table instances from this table helper.

Create Re-usable Table Helper

Here is an example of setting up a table helper that can be re-used throughout your codebase.

import {
  createTableHelper,
  createSortedRowModel, // renamed from getSortedRowModel
  rowSortingFeature, // The feature APIs are no longer included by default, import to use
  sortFns, // Not all of the sortFns are included by default. Import to use all of them
} from '@tanstack/react-table'

// can store this as a re-usable table helper for multiple similar tables throughout a codebase
export const tableHelper = createTableHelper({
  _features: {
    rowSortingFeature,
  },
  _rowModels: {
    // notice: core row model is no longer required, as it is included by default
    sortedRowModel: createSortedRowModel(sortFns), // only if client-side sorting
  },
  // TData: {} as MyDataType // optionally set the TData generic
  sortDescFirst: true, // specify a default table option
})

Create Table with Table Helper

Now that we have a table helper, we can create multiple table instances from it.

import { type SortingState } from '@tanstack/react-table'
import { tableHelper } from '../yourTableHelperUtil'

// const { columnHelper } = tableHelper // if TData was set in the table helper options - otherwise use the createColumnHelper method below
const columnHelper = tableHelper.createColumnHelper<MyDataType>()

const columns = columnHelper.columns([
  columnHelper.accessor('firstName', {}),
  //...
])

//...
const [sorting, setSorting] = React.useState<SortingState>([])

const table = tableHelper.useTable({
  // instead of the static `useTable` hook (will include all features from the tableHelper)
  columns,
  data,
  onSortingChange: setSorting,
  state: {
    sorting,
  },
})

return //render table ui

You can continue to just use the standalone useTable hook similar to v8, but using a tableHelper can be convenient. By using the table helper here, we were able to clean up a lot of boilerplate code and put it in one place.

Note: If using tableHelper.useTable with the new React Compiler:

You will need to destructure the useTable method from the table helper statically outside of a react component.

This is because the React Compiler only works with hooks that are as static as possible.

See the official React docs or this github discussion for more info.

Table Helper in compliance with React Compiler

const tableHelper = createTableHelper({
  _features: {
    //...
  },
  _rowModels: {
    //...
  },
  //...
})

const { useTable, createColumnHelper } = tableHelper // destructure the static methods from the table helper outside of a react component

//...
export function MyComponent() {
  const table = useTable() // instead of `tableHelper.useTable` if you are using the new React Compiler
}

What if I Want All Features (Or Don't Care About Bundle Size)

For those who want to upgrade to V9, but want the easiest upgrade path, and also don't care about bundle size, you can copy and paste the following snippet:

import {
  // import whatever row models you will use
  createExpandedRowModel,
  createFilteredRowModel,
  createGroupedRowModel,
  createPaginatedRowModel,
  createSortedRowModel,
  createTableHelper,
  filterFns,
  sortingFns,
  aggregationFns,
  stockFeatures, // Import all TanStack Table Features (Just like V8 used to)
} from '@tanstack/react-table'

// name whatever. Let's use `useReactTable` to trick ourselves that this is the same as V8
export const useReactTable = createTableHelper({
  _features: stockFeatures, // all features
  _rowModels: {
    sortedRowModel: createSortedRowModel(sortFns),
    filteredRowModel: createFilteredRowModel(filterFns),
    paginatedRowModel: createPaginatedRowModel(),
    groupedRowModel: createGroupedRowModel(aggregationFns),
    expandedRowModel: createExpandedRowModel(),
  },
}).useTable // just the function reference

This creates a useReactTable hook that worked very similarly to V8. All features are included in the stockFeatures object that you can import from TanStack Table. We're also including the Row Models for whatever client-side features that all of our tables will use.

Then you will simply be able to use it throughout your application like so:

import { columnHelper, type SortingState } from '@tanstack/react-table'
import { useReactTable } from '../useReactTable'

// NOTE: `any` also works instead of `typeof stockFeatures` for the
const columns: Array<ColumnDef<typeof stockFeatures, Person>> = [
  columnHelper.accessor('firstName', {}),
  //...
]

//...
const [sorting, setSorting] = React.useState<SortingState>([])

const table = useReactTable({
  // instead of the static `useTable` hook (will include all features from the tableHelper)
  columns,
  data,
  onSortingChange: setSorting,
  state: {
    sorting,
  },
})

return //render table ui

New Plugin System

There is a vision that TanStack Table, at its core, it is going to simply be the best starting point and foundation for code organization for building data tables, and that will be its best selling point. The pre-built stock features that come with it are great, but a lot of the value will be in how easy it will be to extend TanStack Table with your own custom niche functionality. My personal goal is to make TanStack Table the easiest library to extend (or override) of just about any other library out there.

Exactly how the plugin system will work with TypeScript is still being optimized. There are 2 approaches that work, and both are better than how it worked in V8. TypeScript performance is the main factor in which approach will be chosen.

In an ideal world, we will make it very easy to extend TanStack Table with custom features for your own custom state, options, and APIs. They will live on the table instance just like any other feature.

Follow along the Custom Features Example to see how it currently works. (This is a work in progress)

Declarations Merging vs No Declarations Merging

Ideally, we don't want to require any declaration merging in order to set up plugins for TanStack Table. TanStack Table V8 currently requires declaration merging to set up plugins.

At the very least, the declaration merging will have 1st class support with dedicated plugin interfaces for you to add your own custom state, options, and APIs to.

Plugins with Declarations Merging

/**
 * Define the types for our new feature's custom state, options, and APIs
 */

export type DensityState = 'sm' | 'md' | 'lg'
export interface TableState_Density {
  density: DensityState
}

export interface TableOptions_Density {
  enableDensity?: boolean
  onDensityChange?: OnChangeFn<DensityState>
}

export interface Table_Density {
  setDensity: (updater: Updater<DensityState>) => void
  toggleDensity: (value?: DensityState) => void
}

/**
 * Use declaration merging to our the types to the internal table types
 */

declare module '@tanstack/react-table' {
  interface TableState_Plugin {
    density: DensityState
  }

  interface TableOptions_Plugin {
    enableDensity?: boolean
    onDensityChange?: OnChangeFn<DensityState>
  }

  interface Table_Plugin {
    setDensity: (updater: Updater<DensityState>) => void
    toggleDensity: (value?: DensityState) => void
  }
}

/**
 * The actual javascript code for our new feature/plugin (All type-safe!)
 */

export const densityPlugin: TableFeature = {
  getInitialState: (initialState) => {
    return {
      density: 'md',
      ...initialState, // must come last
    }
  },

  getDefaultTableOptions: (table) => {
    return {
      enableDensity: true,
      onDensityChange: makeStateUpdater('density', table),
    }
  },

  constructTableAPIs: (table) => {
    table.setDensity = (updater) => {
      const safeUpdater: Updater<DensityState> = (old) => {
        const newState = functionalUpdate(updater, old)
        return newState
      }
      return table.options.onDensityChange?.(safeUpdater)
    }
    table.toggleDensity = (value) => {
      table.setDensity((old) => {
        if (value) return value
        return old === 'lg' ? 'md' : old === 'md' ? 'sm' : 'lg'
      })
    }
  },
}

// app code
const _features = tableFeatures({
  columnFilteringFeature,
  rowSortingFeature,
  rowPaginationFeature,
  densityPlugin, // pass in our plugin just like any other stock feature
})

This is already an improvement over V8, but we want to make it even easier to use plugins with TanStack Table. Ideally, you will be able to use plugins on a per-table basis, without affecting the types on other tables in the same project.

Plugins with No Declarations Merging

A proof of concept has been done to allow the types from all features to be registered on the TableFeature type. Then the Table, Column, Row, ColumnDef, etc. types will be able to just pick up the types from every feature and plugin from there. This is way more type-safe and allows for plugins to be used on a per-table basis. However, there are currently some TypeScript performance issues with this approach that still need to be worked out.

/**
 * Define the types for our new feature's custom state, options, and APIs (same as above)
 */

export type DensityState = 'sm' | 'md' | 'lg'
export interface TableState_Density {
  density: DensityState
}

export interface TableOptions_Density {
  enableDensity?: boolean
  onDensityChange?: OnChangeFn<DensityState>
}

export interface Table_Density {
  setDensity: (updater: Updater<DensityState>) => void
  toggleDensity: (value?: DensityState) => void
}

// No declarations merging is required because of the below generic on the `TableFeature` type

/**
 * The actual javascript code for our new feature/plugin (All type-safe!)
 */

export const densityPlugin: TableFeature<{
  Table: Table_Density // register the new feature's table APIs
  TableOptions: TableOptions_Density // register the new feature's table options
  TableState: TableState_Density // register the new feature's table state
}> = {
  getInitialState: (initialState) => {
    return {
      density: 'md',
      ...initialState, // must come last
    }
  },

  getDefaultTableOptions: (table) => {
    return {
      enableDensity: true,
      onDensityChange: makeStateUpdater('density', table),
    }
  },

  constructTableAPIs: (table) => {
    table.setDensity = (updater) => {
      const safeUpdater: Updater<DensityState> = (old) => {
        const newState = functionalUpdate(updater, old)
        return newState
      }
      return table.options.onDensityChange?.(safeUpdater)
    }
    table.toggleDensity = (value) => {
      table.setDensity((old) => {
        if (value) return value
        return old === 'lg' ? 'md' : old === 'md' ? 'sm' : 'lg'
      })
    }
  },
}

// app code
const _features = tableFeatures({
  columnFilteringFeature,
  rowSortingFeature,
  rowPaginationFeature,
  densityPlugin, // pass in our plugin just like any other stock feature
})

Conclusions

Let us know what you think of the proposed changes above. We are looking for feedback on the new syntax and code organization.

We have been holding off on alpha releases for a bit, but now that things are starting to stabilize, we will be releasing alphas with all of these breaking changes in the coming weeks. This does not mean that a stable v9 release is right around the corner, but it should be on track for a stable release sometime in 2025.

Looking for Contributions

Want to help TanStack Table V9 ship faster? We are looking for more code contributors! Join the TanStack Table Table-V9 Discord Channel to help get involved.

Here are contributions that could help us speed up the release of TanStack Table V9 by a lot:

• Help with TypeScript Performance and Type-Safety improvements (TypeScript Wizards Wanted)
• Specific Framework expertise (React Compiler, Angular 19, Svelte 5, Lit, Qwik 2, etc.)
• Help with updating examples. (Most examples are mostly up to date, but some still need some work)
• Help filling missing examples in non-react frameworks. (Angular, Svelte, Vue, Solid, etc.)
• Help creating a set of new kitchen sink examples for multiple CSS frameworks. (Tailwind, Material UI, Mantine, Chakra, ShadCn, Vuetify, etc.)
• Help with writing lots of new unit tests
• Help with bug fixes
• Help writing and updating documentation (or helping us automate our docs better)