feat: add controlled paginationPage prop and update API documentation (jbetancur#1316)

Author: jbetancur

apps/docs/src/pages/docs/api.md

@@ -86,7 +86,8 @@ Complete reference for every prop, type, and export in `react-data-table-compone
 | `paginationPerPage` | `number` | `10` | Rows shown per page. |
 | `paginationRowsPerPageOptions` | `number[]` | `[10,15,20,25,30]` | Options in the rows-per-page dropdown. |
 | `paginationDefaultPage` | `number` | `1` | Initial active page. |
-| `paginationResetDefaultPage` | `boolean` | `false` | Toggle to reset to page 1 (e.g. after a filter change). |
+| `paginationPage` | `number` | - | Controlled active page. When provided, the table navigates to this page whenever the value changes. Use together with `onChangePage` to keep them in sync. |
+| `paginationResetDefaultPage` | `boolean` | `false` | Toggle to reset to page 1 (e.g. after a filter change). Prefer `paginationPage` for new code. |
 | `paginationTotalRows` | `number` | - | Total row count for server-side pagination. |
 | `paginationServer` | `boolean` | `false` | Delegate page changes to `onChangePage` / `onChangeRowsPerPage`. |
 | `paginationServerOptions` | `PaginationServerOptions` | - | Selection-persistence options for server-side mode. |

apps/docs/src/pages/docs/changelog.astro

@@ -11,7 +11,19 @@ import CodeBlock from '../../components/CodeBlock.astro';
     <a href="https://github.com/jbetancur/react-data-table-component/commits/master" target="_blank" rel="noreferrer">repository on GitHub</a>.
   </p>
 
-  <h2>8.1.0 (current)</h2>
+  <h2>8.2.0 (unreleased)</h2>
+
+  <h3>New features</h3>
+  <ul>
+    <li>
+      <code>paginationPage</code> — controlled active-page prop. Set it to navigate the table
+      programmatically (e.g. reset to page 1 after a filter change). Use together with
+      <code>onChangePage</code> to keep them in sync.
+      → <a href="/docs/api#pagination">API reference</a>
+    </li>
+  </ul>
+
+  <h2>8.1.0</h2>
 
   <p>
     Additive feature release. No breaking changes. See

src/__tests__/DataTable.test.tsx

@@ -1921,6 +1921,63 @@ describe('DataTable::Pagination', () => {
 		expect(getByText('Todos')).not.toBeNull();
 	});
 
+	test('should navigate to the specified page when paginationPage changes', () => {
+		const mock = dataMock();
+		const { container, rerender } = render(
+			<DataTable
+				data={mock.data}
+				columns={mock.columns}
+				paginationPerPage={1}
+				paginationRowsPerPageOptions={[1, 2]}
+				pagination
+				paginationPage={1}
+			/>,
+		);
+
+		rerender(
+			<DataTable
+				data={mock.data}
+				columns={mock.columns}
+				paginationPerPage={1}
+				paginationRowsPerPageOptions={[1, 2]}
+				pagination
+				paginationPage={2}
+			/>,
+		);
+
+		expect(container.querySelector('div[id="row-2"]')).not.toBeNull();
+	});
+
+	test('should call onChangePage when paginationPage changes', () => {
+		const mock = dataMock();
+		const onChangePage = vi.fn();
+		const { rerender } = render(
+			<DataTable
+				data={mock.data}
+				columns={mock.columns}
+				paginationPerPage={1}
+				paginationRowsPerPageOptions={[1, 2]}
+				pagination
+				paginationPage={1}
+				onChangePage={onChangePage}
+			/>,
+		);
+
+		rerender(
+			<DataTable
+				data={mock.data}
+				columns={mock.columns}
+				paginationPerPage={1}
+				paginationRowsPerPageOptions={[1, 2]}
+				pagination
+				paginationPage={2}
+				onChangePage={onChangePage}
+			/>,
+		);
+
+		expect(onChangePage).toHaveBeenCalledWith(2, mock.data.length);
+	});
+
 	test('should render correctly when paginationResetDefaultPage is toggled', () => {
 		const mock = dataMock();
 		const { container, rerender } = render(

src/components/DataTable.tsx

@@ -57,6 +57,7 @@ function DataTableInner<T>(props: TableProps<T>, ref: React.ForwardedRef<DataTab
 		paginationServerOptions = defaultProps.paginationServerOptions,
 		paginationTotalRows = defaultProps.paginationTotalRows,
 		paginationDefaultPage = defaultProps.paginationDefaultPage,
+		paginationPage,
 		paginationResetDefaultPage = defaultProps.paginationResetDefaultPage,
 		paginationPerPage = defaultProps.paginationPerPage,
 		paginationRowsPerPageOptions = defaultProps.paginationRowsPerPageOptions,
@@ -243,6 +244,7 @@ function DataTableInner<T>(props: TableProps<T>, ref: React.ForwardedRef<DataTab
 		selectableRowsVisibleOnly,
 		selectableRowSelected,
 		clearSelectedRows,
+		paginationPage,
 		paginationResetDefaultPage,
 		controlledSelectedRows,
 		onSelectedRowsChange,

src/hooks/useTableState.ts

@@ -31,6 +31,7 @@ interface UseTableStateProps<T> {
 	selectableRowsVisibleOnly: boolean;
 	selectableRowSelected: ((row: T) => boolean) | null;
 	clearSelectedRows: boolean;
+	paginationPage?: number;
 	paginationResetDefaultPage: boolean;
 	/** Controlled selection. When provided, internal selection state is overridden. */
 	controlledSelectedRows?: T[];
@@ -72,6 +73,7 @@ export default function useTableState<T>(props: UseTableStateProps<T>): UseTable
 		selectableRowsVisibleOnly,
 		selectableRowSelected,
 		clearSelectedRows,
+		paginationPage,
 		paginationResetDefaultPage,
 		controlledSelectedRows,
 		onSelectedRowsChange,
@@ -173,6 +175,13 @@ export default function useTableState<T>(props: UseTableStateProps<T>): UseTable
 		handleChangePage(paginationDefaultPage);
 	}, [paginationDefaultPage, paginationResetDefaultPage]);
 
+	// Effect: Handle controlled page prop
+	useDidUpdateEffect(() => {
+		if (paginationPage !== undefined) {
+			handleChangePage(paginationPage);
+		}
+	}, [paginationPage]);
+
 	// Effect: Recalculate page when total rows change (server pagination)
 	useDidUpdateEffect(() => {
 		if (pagination && paginationServer && paginationTotalRows > 0) {

src/types.ts

@@ -122,6 +122,7 @@ type PaginationProps = {
 	 */
 	paginationIcons?: PaginationIcons;
 	paginationPerPage?: number;
+	paginationPage?: number;
 	paginationResetDefaultPage?: boolean;
 	paginationRowsPerPageOptions?: number[];
 	paginationServer?: boolean;