tanstack-vue-table-skilld（tanstack Vue table skilld 开发）

TanStack/table @tanstack/vue-table@8.21.3

Tags: beta: 8.0.0-beta.9, latest: 8.21.3, alpha: 9.0.0-alpha.33

References: Docs

API Changes

This section documents version-specific API changes — prioritize recent major/minor releases.

• BREAKING: useVueTable — v8 changed from useTable, must be explicitly imported from @tanstack/vue-table source
• BREAKING: FlexRender component — v8 replaced .render() methods with PascalCase FlexRender component in Vue templates source
• BREAKING: accessorKey and accessorFn — v8 renamed accessor to accessorKey (string) or accessorFn (function) source
• BREAKING: header, cell, footer — v8 renamed Header, Cell, Footer column properties to lowercase source
• BREAKING: enable* options — v8 renamed all disable* options to enable* (e.g., enableSorting, enableFiltering) source
• BREAKING: getValue() — v8 changed value prop to getValue() function in cell/header render contexts for performance source
• DEPRECATED: getHeaderProps, getCellProps, getRowProps — v8 removed automatic prop getters; keys and handlers must be manual source
• NEW: Reactive data support — v8.20.0 added support for passing Vue ref or computed directly to data option source
• NEW: sortUndefined: 'first' | 'last' — v8.16.0 added explicit 'first' and 'last' string options to sortUndefined source
• NEW: _features option — v8.14.0 introduced _features for extending table instances with custom logic source
• NEW: firstPage(), lastPage() — v8.13.0 added explicit pagination navigation APIs source
• NEW: rowCount option — v8.13.0 added rowCount to automatically calculate pageCount for manual pagination source
• NEW: rowPinning — v8.12.0 added row pinning state and getTopRows(), getBottomRows(), getCenterRows() APIs source
• BREAKING: sortingFn signature — v8 changed to return number (-1, 0, 1) and only takes 2 rows plus column ID source

Also changed: columnVisibility state new v8 · columnPinning new v8 · resetPageIndex() new v8.13.0 · resetPageSize() new v8.13.0 · shallowRef internally for Vue v8.20.0

Best Practices

• Use useVueTable with reactive data directly — pass a ref or computed to the data option to enable automatic table updates without manual triggers source
• Update data by replacing the array .value — since shallowRef is used internally for performance, the table only reacts to top-level array mutations (e.g., data.value = [...]) rather than push or splice source
• Use createColumnHelper for type-safe definitions — provides the highest level of TypeScript inference for accessor, display, and grouping columns source

const columnHelper = createColumnHelper<Person>()
const columns = [
  columnHelper.accessor('firstName', { cell: info => info.getValue() })
]

• Prefer initialState over state for simple defaults — use this when you don't need to control state externally to avoid the overhead of manual synchronization source
• Use getters in state for controlled reactivity — when hoisting state into your own refs, wrap them in getters to ensure useVueTable correctly tracks reactive changes source

const sorting = ref<SortingState>([])
const table = useVueTable({
  state: {
    get sorting() { return sorting.value }
  }
})

• Use FlexRender for all dynamic templates — essential for correctly rendering cell, header, and footer templates (strings, components, or JSX) within the Vue lifecycle source
• Import only required row models to optimize bundle size — only provide the specific models needed for your features (e.g., getSortedRowModel) to avoid including unnecessary logic source
• Set manual* options to true for server-side operations — prevents redundant client-side processing when sorting, pagination, or filtering is handled by the backend source
• Use 'first' or 'last' for undefined sorting priority — explicitly control where nullable or undefined values appear during sorting using the sortUndefined option source
• Always provide a unique id for accessorFn columns — required for stable column identification and feature state (sorting/filtering) when not using a simple accessorKey source