Framework
Version
Menu
Getting Started
Core Guides
Feature Guides
Core APIs
Feature APIs
Enterprise
Examples

Migrating to V8 Guide

Migrating to V8

TanStack Table V8 was a major rewrite of React Table v7 from the ground up in TypeScript. The overall structure/organization of your markup and CSS will largely remain the same, but many of the APIs have been renamed or replaced.

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

Install the new Version

The new version of TanStack Table is published under the @tanstack scope. Install the new package using your favorite package manager:

bash
npm uninstall react-table @types/react-table
npm install @tanstack/react-table
npm uninstall react-table @types/react-table
npm install @tanstack/react-table

Types are now included in the base package, so you can remove the @types/react-table package.

If you want, you can keep the old react-table packages installed so that you can gradually migrate your code. You should be able to use both packages side-by-side for separate tables without any issues.

Update Table Options

  • Rename useTable to useReactTable
  • The old hook and plugin systems have been removed, but they have replaced with tree-shakable row model imports for each feature.
  • All disable* table options were renamed to enable* table options. (e.g. disableSortBy is now enableSorting, disableGroupBy is now enableGrouping, etc.)
  • ...

Update column definitions

  • accessor was renamed to either accessorKey or accessorFn (depending on whether you are using a string or function)
  • width, minWidth, maxWidth where renamed to size, minSize, maxSize
  • Optionally, you can use the new createColumnHelper function around each column definition for better TypeScript hints. (You can still just use an array of column definitions if you prefer.)
    • The first parameter is the accessor function or accessor string.
    • The second parameter is an object of column options.

Note: If defining columns inside a component, you should still try to give the column definitions a stable identity. This will help with performance and prevent unnecessary re-renders. Store the column definitions in either a useMemo or useState hook.

  • Column Option Name Changes

    • Header was renamed to header
    • Cell was renamed to cell (The cell render function has also changed. See below)
    • Footer was renamed to footer
    • All disable* column options were renamed to enable* column options. (e.g. disableSortBy is now enableSorting, disableGroupBy is now enableGrouping, etc.)
    • sortType sortingFn
    • ...
  • Changes to custom cell renderers

    • value was renamed getValue (Throughout the upgrade, instead of providing the value directly, a function getValue is exposed for evaluating the value. This change aims to improve performance by evaluating the value only when getValue() is called and then caching it.)
    • cell: { isGrouped, isPlaceholder, isAggregated } is now cell: { getIsGrouped, getIsPlaceholder, getIsAggregated }
    • column: The base level props are now RT-specific. Values that you added to the object when defining it are now one level deeper in columnDef.
    • table: Props passed into the useTable hook now appear under options.

Migrate Table Markup

  • Use flexRender() instead of cell.render('Cell') or column.render('Header'), etc.
  • getHeaderProps, getFooterProps, getCellProps, getRowProps, etc. have all been deprecated.
    • TanStack Table does not provide any default style or accessibility attributes like role anymore. These are still important for you to get right, but it had to be removed in order to support being framework-agnostic.
    • You will need to define onClick handlers manually, but there are new get*Handler helpers to keep this simple.
    • You will need to define the key props manually
    • You will need to define the colSpan prop manually if using features that require it (grouped headers, aggregation, etc.)

Other Changes

  • custom filterTypes (now called filterFns) have a new function signature as it only returns a boolean for whether the row should be included or not.
  • ...

This guide is a work in progress. Please consider contributing to it if you have time!

Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.