React Hook for syncing TanStack Table state with URL search params
npm install tanstack-table-search-paramsReact Hook for syncing TanStack Table state with URL search params.
https://github.com/user-attachments/assets/2a4108a2-254c-4c06-b346-f5d6e4c56c12
First, install the package.
``bash`
npm i tanstack-table-search-params
For example, if you are using Next.js (Pages Router), you can use the hook like this.
`tsx
import { useReactTable } from "@tanstack/react-table";
import { useRouter } from "next/router";
import { useTableSearchParams } from "tanstack-table-search-params";
const router = useRouter();
// Get state and onChanges
const stateAndOnChanges = useTableSearchParams({
query: router.query,
pathname: router.pathname,
replace: router.replace,
// or
push: router.push,
});
const table = useReactTable({
// Set state and onChanges
...stateAndOnChanges,
data,
columns,
getCoreRowModel: getCoreRowModel(),
getFilteredRowModel: getFilteredRowModel(),
getSortedRowModel: getSortedRowModel(),
// ... other options
});
`
Here is the demo.
Of course, you can use it with other routers.
Please refer to the following how to use:
Next.js(Pages Router)
Use next/router
`tsx
import { useReactTable } from "@tanstack/react-table";
import { useTableSearchParams } from "tanstack-table-search-params";
import { useRouter } from "next/router";
const router = useRouter();
const stateAndOnChanges = useTableSearchParams(router);
const table = useReactTable({
// Set state and onChanges
...stateAndOnChanges,
data,
columns,
// ... other options
});
`
Use next/navigation
`tsx
import { useReactTable } from "@tanstack/react-table";
import { useTableSearchParams } from "tanstack-table-search-params";
import { usePathname, useRouter, useSearchParams } from "next/navigation";
const { replace } = useRouter();
const stateAndOnChanges = useTableSearchParams({
pathname: usePathname(),
query: useSearchParams(),
replace,
});
const table = useReactTable({
// Set state and onChanges
...stateAndOnChanges,
data,
columns,
// ... other options
});
`
Next.js(App Router)
`tsx
import { useReactTable } from "@tanstack/react-table";
import { useTableSearchParams } from "tanstack-table-search-params";
import { usePathname, useRouter, useSearchParams } from "next/navigation";
const { replace } = useRouter();
const stateAndOnChanges = useTableSearchParams({
pathname: usePathname(),
query: useSearchParams(),
replace,
});
const table = useReactTable({
// Set state and onChanges
...stateAndOnChanges,
data,
columns,
// ... other options
});
`
TanStack Router
`tsx
import { useReactTable } from "@tanstack/react-table";
import { useTableSearchParams } from "tanstack-table-search-params";
import { createFileRoute } from "@tanstack/react-router";
export const Route = createFileRoute("/")({
component: Page,
});
function Page() {
const navigate = Route.useNavigate();
const query = Route.useSearch();
const stateAndOnChanges = useTableSearchParams({
replace: (url) => {
const searchParams = new URLSearchParams(url.split("?")[1]);
navigate({ search: Object.fromEntries(searchParams.entries()) });
},
query,
pathname: Route.path,
});
const table = useReactTable({
// Set state and onChanges
...stateAndOnChanges,
data,
columns,
});
// ...
}
`
React Router
`tsx
import { useReactTable } from "@tanstack/react-table";
import { useTableSearchParams } from "tanstack-table-search-params";
import { useSearchParams, useNavigate, useLocation } from "react-router";
const [query] = useSearchParams();
const navigate = useNavigate();
const { pathname } = useLocation();
const stateAndOnChanges = useTableSearchParams({
query,
pathname,
replace: (url) => navigate(url, { replace: true }),
});
const table = useReactTable({
// Set state and onChanges
...stateAndOnChanges,
data,
columns,
// ... other options
});
`
The useTableSearchParams hook primarily does the following two things:
- Decode query (query parameter state) and return it as the state for Tanstack Table.onChangeGlobalFilter
- Return a function like that encodes state as a query parameter and performs replace (or push).
- 🏷️ Custom query param name
- 🪄 Custom default value
- 🔢 Custom encoder/decoder
- ⏱️ Debounce
- ☑️ Enable/Disable
You can customize a query parameter name.
`tsxuserTable-${defaultParamName}
const stateAndOnChanges = useTableSearchParams(router, {
paramNames: {
// Customize query parameter name by passing a string
globalFilter: "userTable-globalFilter",
// Add prefix by passing a function
sorting: (defaultParamName) => ,`
},
});
You can customize the default value of a query parameter.
The "default value" is the value that is used as the state when the query parameter is not present.
`tsx`
const stateAndOnChanges = useTableSearchParams(router, {
defaultValues: {
// Sort by name in descending order when query parameter is not present
sorting: [{ id: "name", desc: true }],
},
});
If you want to set initial values for query parameters, either transition with the query parameter or add the query parameter after the transition, depending on the router you are using.
`tsx
// Transition with the query parameter
Users
;
// Add the query parameter after the transition
useEffect(() => {
router.replace({ query: { globalFilter: "foo" } });
}, [router.replace]);
`
You can customize the encoder/decoder for the query parameter.
`tsx
const stateAndOnChanges = useTableSearchParams(router, {
// Use JSON.stringify/JSON.parse for encoding/decoding
encoders: {
// foo -> { "globalFilter": "foo" }
globalFilter: (globalFilter) => ({
globalFilter: JSON.stringify(globalFilter),
}),
},
decoders: {
// { "globalFilter": "foo" } -> foo
globalFilter: (query) =>
query["globalFilter"]
? JSON.parse(query["globalFilter"] as string)
: (query["globalFilter"] ?? ""),
},
});
// ...
const stateAndOnChanges = useTableSearchParams(router, {
// Encoders/decoders with different query parameter names can also be used.
encoders: {
// [{ id: "name", desc: true }] -> { "userTable-sorting": "[{ \"id\": \"name\", \"desc\": true }]" }
sorting: (sorting) => ({
"userTable-sorting": JSON.stringify(sorting),
}),
},
decoders: {
// { "userTable-sorting": "[{ \"id\": \"name\", \"desc\": true }]" } -> [{ id: "name", desc: true }]
sorting: (query) =>
query["userTable-sorting"]
? JSON.parse(query["userTable-sorting"] as string)
: query["userTable-sorting"],
},
});
// ...
const stateAndOnChanges = useTableSearchParams(router, {
// Encoders/decoders with different numbers of query parameters can also be used.
encoders: {
// [{ id: "name", value: "foo" }] -> { "columnFilters.name": "\"foo\"" }
columnFilters: (columnFilters) =>
Object.fromEntries(
columnFilters.map(({ id, value }) => [
columnFilters.${id},`
JSON.stringify(value),
]),
),
},
decoders: {
// { "columnFilters.name": "\"foo\"" } -> [{ id: "name", value: "foo" }]
columnFilters: (query) =>
Object.entries(query)
.filter(([key]) => key.startsWith("columnFilters."))
.map(([key, value]) => ({
id: key.replace("columnFilters.", ""),
value: JSON.parse(value as string),
})),
},
});
You can debounce the reflection of state changes in the query parameters.
`tsx`
const stateAndOnChanges = useTableSearchParams(router, {
debounceMilliseconds: {
// Debounce globalFilter by 500 milliseconds
globalFilter: 500,
},
});
Also, you can debounce all query parameters at once.
`tsx`
const stateAndOnChanges = useTableSearchParams(router, {
debounceMilliseconds: 500,
});
You can enable/disable the synchronization of a query parameter.
All states are enabled by default.
`tsx`
const stateAndOnChanges = useTableSearchParams(router, {
// Disable synchronization of sorting
enabled: { sorting: false },
});
If you are using Next.js (Pages Router), you can prevent page transitions by using the shallow option.
`tsx`
const router = useRouter();
const stateAndOnChanges = useTableSearchParams({
...router,
replace: (query) => router.replace(query, undefined, { shallow: true }),
});
Create an input that supports IME conversion with a uncontrolled component.
To pass initial table state via the URL, call one of the encode* helpers from tanstack-table-search-params/encoder-decoder and assign its return value to your link.
`tsx
import { encodeSorting } from "tanstack-table-search-params/encoder-decoder";
pathname: "/some-page-with-table",
query: {
sorting: encodeSorting([{ id: "name", desc: true }]),
},
}}
>
foo
;
`
List of supported TanStack table states
([x] means supported, [ ] means not supported)
- [x] globalFilter
- [x] sorting
- [x] pagination
- [x] columnFilters
- [x] columnOrder
- [ ] columnPinning
- [ ] columnSizing
- [ ] columnSizingInfo
- [x] columnVisibility
- [ ] expanded
- [ ] grouping
- [ ] rowPinning
- [x] rowSelection
- [ ] Support other table states
- [ ] Add onChangeXxxQuery optionenabled
- [ ] Change the options interface to be based on state
- [ ] Restrict the combination of with other optionsencoders
- [ ] Restrict combinations of /decoders with paramNames or defaultValues`
MIT
[1]: https://www.npmjs.com/package/tanstack-table-search-params
[2]: https://github.com/taro-28/tanstack-table-search-params
[3]: https://bundlephobia.com/package/tanstack-table-search-params