Skip to content

feat: add existingTable param to useReactTable #6123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat: add existingTable param to useReactTable #6123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
90eddf6
feat: add existingTable param to useReactTable
derekperkins Nov 4, 2025
e468632
feat: add existingTable param to other frameworks
derekperkins Nov 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/beige-singers-admire.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@tanstack/react-table': patch
---

feat: add existingTable param to useReactTable
5 changes: 3 additions & 2 deletions packages/angular-table/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ export {
} from './flex-render/flex-render-component'

export function createAngularTable<TData extends RowData>(
options: () => TableOptions<TData>
options: () => TableOptions<TData>,
existingTable?: Table<TData>
): Table<TData> & Signal<Table<TData>> {
Comment on lines 28 to 31
Copy link

@coderabbitai coderabbitai bot Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

Add JSDoc documentation for the new existingTable parameter.

The new existingTable parameter is a public API addition but lacks documentation explaining its purpose and intended usage pattern. Please add JSDoc comments describing when and how to use this parameter.

Apply this diff to add documentation:

+/**
+ * Creates an Angular-reactive table instance.
+ * @param options - A function returning table options
+ * @param existingTable - Optional existing table instance to reuse instead of creating a new one.
+ *                        Useful for framework-agnostic table adapters that create a table outside
+ *                        the Angular context and then wire it up with Angular's reactivity system.
+ * @returns A table instance that is also an Angular Signal
+ */
 export function createAngularTable<TData extends RowData>(
   options: () => TableOptions<TData>,
   existingTable?: Table<TData>
 ): Table<TData> & Signal<Table<TData>> {
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
export function createAngularTable<TData extends RowData>(
options: () => TableOptions<TData>
options: () => TableOptions<TData>,
existingTable?: Table<TData>
): Table<TData> & Signal<Table<TData>> {
/**
* Creates an Angular-reactive table instance.
* @param options - A function returning table options
* @param existingTable - Optional existing table instance to reuse instead of creating a new one.
* Useful for framework-agnostic table adapters that create a table outside
* the Angular context and then wire it up with Angular's reactivity system.
* @returns A table instance that is also an Angular Signal
*/
export function createAngularTable<TData extends RowData>(
options: () => TableOptions<TData>,
existingTable?: Table<TData>
): Table<TData> & Signal<Table<TData>> {
🤖 Prompt for AI Agents 
In packages/angular-table/src/index.ts around lines 28 to 31, the public API
function createAngularTable was extended with a new existingTable parameter but
lacks JSDoc; add a JSDoc block above the function documenting the existingTable
parameter: describe that it accepts an existing Table<TData> instance to reuse
or adopt into the Angular signal wrapper, explain when to pass it (e.g., to
preserve existing table state or avoid reinitialization), clarify that it is
optional, note any side-effects (ownership/immutability expectations) and the
return type behavior, and include examples/usage notes for typical scenarios.

return lazyInit(() => {
const resolvedOptions = {
Expand All @@ -36,7 +37,7 @@ export function createAngularTable<TData extends RowData>(
...options(),
}

const table = createTable(resolvedOptions)
const table = existingTable ?? createTable(resolvedOptions)

// By default, manage table state here using the table's initial state
const state = signal<TableState>(table.initialState)
Expand Down
4 changes: 2 additions & 2 deletions packages/lit-table/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ export class TableController<TData extends RowData>
;(this.host = host).addController(this)
}

public table(options: TableOptions<TData>) {
public table(options: TableOptions<TData>, existingTable?: Table<TData>) {
if (!this.tableInstance) {
const resolvedOptions: TableOptionsResolved<TData> = {
state: {},
Expand All @@ -45,7 +45,7 @@ export class TableController<TData extends RowData>
...options,
}

this.tableInstance = createTable(resolvedOptions)
this.tableInstance = existingTable ?? createTable(resolvedOptions)
this._tableState = {
...this.tableInstance.initialState,
...options.state,
Expand Down
27 changes: 17 additions & 10 deletions packages/qwik-table/src/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,8 @@ export function flexRender<TProps extends object>(
}

export function useQwikTable<TData extends RowData>(
options: TableOptions<TData>
options: TableOptions<TData>,
existingTable?: Table<TData>
) {
// Compose in the generic options to the user options
const resolvedOptions: TableOptionsResolved<TData> = {
Expand All @@ -41,32 +42,38 @@ export function useQwikTable<TData extends RowData>(
...options,
}

// Create a new table instance and store it in a Qwik store
const table = Qwik.useStore<{
instance: Qwik.NoSerialize<Table<TData>>
// Create or reuse the table instance and store it.
const tableStore = Qwik.useStore<{
instance: Qwik.NoSerialize<Table<TData>> | null
}>({
instance: Qwik.noSerialize(createTable(resolvedOptions)),
instance: null,
})

if (!tableStore.instance) {
tableStore.instance = Qwik.noSerialize(
existingTable ?? createTable(resolvedOptions)
)
}

const table = tableStore.instance!

// By default, manage table state here using the table's initial state
const state = Qwik.useSignal(table.instance!.initialState)
const state = Qwik.useSignal(table.initialState)

// Compose the default state above with any user state. This will allow the user
// to only control a subset of the state if desired.
table.instance!.setOptions(prev => ({
table.setOptions(prev => ({
...prev,
...options,
state: {
...state.value,
...options.state,
},
// Similarly, we'll maintain both our internal state and any user-provided
// state.
onStateChange: updater => {
state.value = updater instanceof Function ? updater(state.value) : updater
options.onStateChange?.(updater)
},
}))

return table.instance!
return table
}
8 changes: 5 additions & 3 deletions packages/react-table/src/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import {
TableOptionsResolved,
RowData,
createTable,
Table,
} from '@tanstack/table-core'

export type Renderable<TProps> = React.ReactNode | React.ComponentType<TProps>
Expand Down Expand Up @@ -55,7 +56,8 @@ function isExoticComponent(component: any) {
}

export function useReactTable<TData extends RowData>(
options: TableOptions<TData>
options: TableOptions<TData>,
existingTable?: Table<TData>
) {
Comment on lines 58 to 61
Copy link

@coderabbitai coderabbitai bot Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major

Add JSDoc documentation for the new parameter.

The existingTable parameter introduces a significant new usage pattern but lacks documentation explaining when and how it should be used, what happens to the existing table's state, and any constraints or gotchas.

Add JSDoc to document the parameter:

+/**
+ * Hook to create or reuse a TanStack table instance within React.
+ * @param options - Table configuration options
+ * @param existingTable - Optional pre-created table instance. When provided, this table will be used instead of creating a new one. Note: The hook will manage state internally and sync it with the table via setOptions on each render.
+ */
 export function useReactTable<TData extends RowData>(
   options: TableOptions<TData>,
   existingTable?: Table<TData>
 ) {
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
export function useReactTable<TData extends RowData>(
options: TableOptions<TData>
options: TableOptions<TData>,
existingTable?: Table<TData>
) {
/**
* Hook to create or reuse a TanStack table instance within React.
* @param options - Table configuration options
* @param existingTable - Optional pre-created table instance. When provided, this table will be used instead of creating a new one. Note: The hook will manage state internally and sync it with the table via setOptions on each render.
*/
export function useReactTable<TData extends RowData>(
options: TableOptions<TData>,
existingTable?: Table<TData>
) {
🤖 Prompt for AI Agents 
In packages/react-table/src/index.tsx around lines 58 to 61, the new
existingTable parameter of useReactTable is undocumented; add a JSDoc block
above the function that documents the parameter with: a clear description of
when to pass an existing Table instance, what parts of the existing table’s
state (e.g., selectedRows, columnOrder, sorting, pagination) are adopted or left
untouched, whether the hook will mutate or replace the provided table (and if it
clones it), lifecycle/ownership expectations (caller retains responsibility for
cleanup), accepted types/nullability (Table<TData> | undefined), and any gotchas
or constraints (concurrent use, prop mismatch, incompatible options). Keep it
concise and include @param existingTable and a short @returns note if not
already present.

// Compose in the generic options to the user options
const resolvedOptions: TableOptionsResolved<TData> = {
Expand All @@ -65,9 +67,9 @@ export function useReactTable<TData extends RowData>(
...options,
}

// Create a new table and store it in state
// Create or use the provided table instance and store it in state
const [tableRef] = React.useState(() => ({
current: createTable<TData>(resolvedOptions),
current: existingTable ?? createTable<TData>(resolvedOptions),
}))

// By default, manage table state here using the table's initial state
Expand Down
5 changes: 3 additions & 2 deletions packages/solid-table/src/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,8 @@ export function flexRender<TProps>(
}

export function createSolidTable<TData extends RowData>(
options: TableOptions<TData>
options: TableOptions<TData>,
existingTable?: import('@tanstack/table-core').Table<TData>
) {
const resolvedOptions: TableOptionsResolved<TData> = mergeProps(
{
Expand All @@ -42,7 +43,7 @@ export function createSolidTable<TData extends RowData>(
options
)

const table = createTable<TData>(resolvedOptions)
const table = existingTable ?? createTable<TData>(resolvedOptions)
const [state, setState] = createStore(table.initialState)

createComputed(() => {
Expand Down
5 changes: 3 additions & 2 deletions packages/svelte-table/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,8 @@ export function flexRender(component: any, props: any): ComponentType | null {
type ReadableOrVal<T> = T | Readable<T>

export function createSvelteTable<TData extends RowData>(
options: ReadableOrVal<TableOptions<TData>>
options: ReadableOrVal<TableOptions<TData>>,
existingTable?: import('@tanstack/table-core').Table<TData>
) {
let optionsStore: Readable<TableOptions<TData>>

Expand All @@ -86,7 +87,7 @@ export function createSvelteTable<TData extends RowData>(
...get(optionsStore),
}

let table = createTable(resolvedOptions)
let table = existingTable ?? createTable(resolvedOptions)

let stateStore = writable(/** @type {number} */ table.initialState)
// combine stores
Expand Down
9 changes: 5 additions & 4 deletions packages/vue-table/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,8 @@ function getOptionsWithReactiveData<TData extends RowData>(
}

export function useVueTable<TData extends RowData>(
initialOptions: TableOptionsWithReactiveData<TData>
initialOptions: TableOptionsWithReactiveData<TData>,
existingTable?: import('@tanstack/table-core').Table<TData>
) {
const IS_REACTIVE = isRef(initialOptions.data)

Expand All @@ -75,9 +76,9 @@ export function useVueTable<TData extends RowData>(
IS_REACTIVE ? getOptionsWithReactiveData(initialOptions) : initialOptions
)

const table = createTable<TData>(
resolvedOptions as TableOptionsResolved<TData>
)
const table =
existingTable ??
createTable<TData>(resolvedOptions as TableOptionsResolved<TData>)

// Add reactivity support
if (IS_REACTIVE) {
Expand Down