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 1 commit
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
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