React Hook for syncing TanStack Table state with URL search parameters. Enables shareable, bookmarkable table state (sorting, filtering, pagination, etc.) across different router implementations.
This skill guides you through working with the `tanstack-table-search-params` monorepo - a React hook library that syncs TanStack Table state with URL search parameters. The library enables table state (sorting, filtering, pagination, etc.) to persist in the URL, making it shareable and bookmarkable.
- `next-pages-router/`: Next.js Pages Router example
- `next-app-router/`: Next.js App Router example
- `tanstack-router/`: TanStack Router example
- `react-router-lib/`: React Router example
- `lib/`: Shared components used across examples
The core export orchestrates multiple state-specific hooks:
1. **State-specific hooks** (e.g., `useGlobalFilter`, `useSorting`, `usePagination`):
- Each manages one TanStack Table state
- Decodes query params → state
- Encodes state → query params
- Handles debouncing via `useDebounce`
- Returns state, onChange handler, and encoder function
2. **Main hook** (`useTableSearchParams`):
- Composes all state-specific hooks
- Manages enabled/disabled states
- Provides `onStateChange` for batch updates
- Returns partial TableState + onChange handlers
Each table state has paired encoder/decoder functions in `src/encoder-decoder/`:
The library is router-agnostic via the `Router` type (`src/types.ts`):
```typescript
type Router = {
query: Query; // Current query params
navigate(url): void; // Navigation function (push or replace)
pathname: string; // Current pathname
};
```
1. User interacts with table → TanStack Table calls onChange handler
2. onChange handler in state-specific hook:
- Encodes new state to query params
- Calls `updateQuery()` to merge with existing query
3. `updateQuery()` builds new URL and calls router's navigate function
4. Router updates URL → query params change → hook re-renders with new decoded state
```bash
pnpm build
pnpm type-check
pnpm test
pnpm check-write
pnpm prettier
pnpm knip
```
```bash
pnpm tanstack-table-search-params <command>
pnpm tanstack-table-search-params build
pnpm tanstack-table-search-params test
pnpm tanstack-table-search-params type-check
pnpm examples/next-pages-router <command>
pnpm examples/next-app-router <command>
pnpm examples/tanstack-router <command>
pnpm examples/react-router-lib <command>
```
```bash
cd packages/tanstack-table-search-params
pnpm test
pnpm test src/tests/globalFilter.test.ts
```
Tests are organized in `packages/tanstack-table-search-params/src/tests/`:
When working with this codebase:
1. **Before modifying hooks**: Read the relevant state-specific hook in `src/hooks/` and its corresponding encoder/decoder in `src/encoder-decoder/`
2. **When adding new features**:
- Create state-specific hook following the existing pattern
- Add encoder/decoder pair
- Export from appropriate index files
- Add tests in `src/tests/`
- Update example implementations
3. **Testing changes**:
- Run `pnpm test` to verify unit tests pass
- Test in at least one example app
- Run `pnpm type-check` to ensure TypeScript compliance
4. **Code style**:
- Use `pnpm check-write` for Biome formatting/linting
- Use `pnpm prettier` for additional formatting
- Follow existing encoder/decoder patterns
- Maintain router abstraction
5. **Avoid**:
- Router-specific logic in main package (keep it in examples)
- Breaking changes to encoder/decoder APIs
- Adding dependencies without discussion
- Modifying example shared components without checking impact on all examples
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/tanstack-table-search-params/raw