useListParams

useListParams is a hook that synchronizes list page filtering, sorting, and pagination state with URL search parameters. It provides bookmarkable state management and type-safe form binding.

Core Features

URL Sync

Store search params in URLBookmarkable state

Type Safety

Zod schema basedAutomatic type inference

Auto Page Reset

Reset to page 1 on filter changeImproved UX

register Pattern

Easy form component bindingRemove boilerplate

Basic Usage

Import and Initialization

import { useListParams } from "@sonamu-kit/react-components";
import { UserService } from "@/services/services.generated";
import { UserListParams } from "@/services/sonamu.generated";

export function UserListPage() {
  // Parse and initialize parameters from URL
  const { listParams, setListParams, register } = useListParams(UserListParams, {
    num: 24,
    page: 1,
    orderBy: "id-desc" as const,
    search: "id" as const,
    keyword: "",
  });

  // API call (pass listParams directly)
  const { data, isLoading } = UserService.useUsers("A", listParams);

  // ...
}

Parameter Explanation:

UserListParams: Zod schema (auto-generated)
Default value object: Initial values when URL has no values

Why is a Zod schema needed?URL search parameters are strings, so a schema is needed to parse them into numbers or booleans. UserListParams is auto-generated in sonamu.generated.ts and always stays in sync with backend type definitions.

Using listParams

An object containing the current filtering state.

const { listParams } = useListParams(UserListParams, defaultValue);

// Pass directly to API calls
const { data } = UserService.useUsers("A", listParams);

// Or check specific values
console.log(listParams.page); // 1
console.log(listParams.keyword); // "admin"
console.log(listParams.orderBy); // "id-desc"

Type:

listParams: Partial<z.infer<UserListParams>> & DefaultValue;

Changing State with setListParams

Change filter state and update URL.

const { listParams, setListParams } = useListParams(UserListParams, defaultValue);

// Change page
setListParams({ ...listParams, page: 2 });

// Change sorting
setListParams({ ...listParams, page: 1, orderBy: "created_at-desc" });

// Change search keyword
setListParams({
  ...listParams,
  page: 1, // Always reset to page 1 on search
  keyword: "admin",
});

How it works:

Deep equal comparison between listParams and newParams
If changed, update URL with TanStack Router’s navigate
URL change → useSearch hook re-runs → listParams automatically updated

Important: Always use spread operator

// ❌ Wrong usage (existing values lost)
setListParams({ page: 2 });

// ✅ Correct usage
setListParams({ ...listParams, page: 2 });

Always use spread operator to preserve existing filter values.

Form Binding with register

The register function automatically provides value and onValueChange to form components.

import { Input, Select } from "@sonamu-kit/react-components/components";

const { register } = useListParams(UserListParams, defaultValue);

return (
  <div>
    {/* Search keyword input */}
    <Input {...register("keyword")} placeholder="Enter keyword" />

    {/* Sort selection */}
    <UserOrderBySelect {...register("orderBy")} />

    {/* Page selection */}
    <Pagination {...register("page")} total={data?.total ?? 0} />
  </div>
);

What register returns:

{
  value: listParams[name] ?? defaultValue[name] ?? (name === "page" ? 1 : ""),
  onValueChange: (value) => {
    if (name === "page") {
      // Preserve other filters on page change
      setListParams({ ...listParams, page: value });
    } else {
      // Reset page to 1 on other filter changes
      setListParams({
        ...listParams,
        page: 1,
        [name]: value === "" ? undefined : value
      });
    }
  }
}

Why auto page reset?: If a user changes the search keyword on page 3, there may be fewer results and page 3 may not exist. Therefore, all filter changes except page automatically return to page 1.

Real-world Examples

Complete List Page

import { useListParams } from "@sonamu-kit/react-components";
import { Input, Pagination } from "@sonamu-kit/react-components/components";
import { UserService } from "@/services/services.generated";
import { UserListParams } from "@/services/sonamu.generated";
import { UserOrderBySelect } from "@/components/user/UserOrderBySelect";
import { UserSearchFieldSelect } from "@/components/user/UserSearchFieldSelect";

export function UserListPage() {
  const { listParams, register } = useListParams(
    UserListParams,
    {
      num: 24,
      page: 1,
      orderBy: "id-desc" as const,
      search: "id" as const,
      keyword: "",
    }
  );

  const { data, isLoading } = UserService.useUsers("A", listParams);

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      {/* Filter section */}
      <div className="flex gap-2 mb-4">
        <UserSearchFieldSelect {...register("search")} />
        <Input {...register("keyword")} placeholder="Enter keyword" />
        <UserOrderBySelect {...register("orderBy")} />
      </div>

      {/* Table */}
      <table>
        <thead>
          <tr>
            <th>ID</th>
            <th>Name</th>
            <th>Email</th>
          </tr>
        </thead>
        <tbody>
          {data?.rows.map((user) => (
            <tr key={user.id}>
              <td>{user.id}</td>
              <td>{user.username}</td>
              <td>{user.email}</td>
            </tr>
          ))}
        </tbody>
      </table>

      {/* Pagination */}
      <Pagination {...register("page")} total={data?.total ?? 0} />
    </div>
  );
}

Adding Custom Filters

When custom filters are added in the backend:

// Backend: user.types.ts
export const UserListParams = UserBaseListParams.extend({
  role: z.enum(["admin", "normal"]).optional(),
  isVerified: z.boolean().optional(),
});

Frontend usage:

import { UserRoleSelect } from "@/components/user/UserRoleSelect";
import { Switch } from "@sonamu-kit/react-components/components";

const { register } = useListParams(UserListParams, {
  num: 24,
  page: 1,
  role: undefined,
  isVerified: undefined,
});

return (
  <div>
    <UserRoleSelect {...register("role")} clearable />

    <div className="flex items-center gap-2">
      <label>Verified users only</label>
      <Switch {...register("isVerified")} />
    </div>
  </div>
);

The biggest advantage of useListParams is that filter state is stored in the URL.

# URL after user sets filters
https://example.com/users?page=2&keyword=admin&orderBy=created_at-desc&role=admin

# If you copy and share this URL or bookmark it
# The same filters will be applied when accessed later

Benefits of bookmarkable state:

Users can bookmark frequently used filter combinations
Share URL to show colleagues the same view
Navigate through filter history with browser back/forward

Options

disableSearchParams

Disable URL synchronization and manage state locally only.

const { listParams, setListParams, register } = useListParams(UserListParams, defaultValue, {
  disableSearchParams: true,
});

Use cases:

List inside a modal (when you don’t want to change URL)
Embedded widget (when independent state management is needed)
Test environment

Using disableSearchParams: true will disable bookmark and URL sharing functionality.

Type Safety

Compile-time Validation

const { register } = useListParams(UserListParams, defaultValue);

// ✅ OK: Fields defined in UserListParams
register("keyword");
register("orderBy");
register("page");

// ❌ Compile error: Non-existent field
register("invalidField");

Auto-completion

When typing register(" in IDE, all available fields are auto-completed.

register("
        ↓
        keyword
        orderBy
        page
        search
        num
        role          // Custom field
        isVerified    // Custom field

TanStack Router Integration

useListParams internally uses TanStack Router hooks:

useSearch: Read URL search parameters
useNavigate: Update URL

// useListParams internal structure (simplified)
export function useListParams<U, T>(zType: U, defaultValue: T) {
  const search = useSearch({ strict: false });
  const navigate = useNavigate();

  const listParams = zType.safeParse(search).success
    ? { ...defaultValue, ...zType.parse(search) }
    : defaultValue;

  const setListParams = (newParams: T) => {
    navigate({ search: newParams });
  };

  // ...
}

Meaning of strict: falseuseSearch({ strict: false }) allows reading search parameters not defined in the current route. This enables flexible handling of dynamically added filters.

Cautions

1. Setting Initial Values

// ❌ Wrong initial value (missing num, page)
const { listParams } = useListParams(UserListParams, {});

// ✅ Correct initial value (including required fields)
const { listParams } = useListParams(UserListParams, {
  num: 24,
  page: 1,
  orderBy: "id-desc" as const,
  search: "id" as const,
});

Required fields:

num: Items per page
page: Current page (starts from 1)

2. Type Assertion for Enum Fields

// ❌ Compile error: Cannot assign string to enum
const defaultValue = {
  orderBy: "id-desc",
};

// ✅ OK: Create literal type with as const
const defaultValue = {
  orderBy: "id-desc" as const,
};

3. Using register with Custom onChange

// ❌ register's onValueChange is ignored
<Input
  {...register("keyword")}
  onChange={(e) => console.log(e.target.value)}
/>

// ✅ OK: Call register's onValueChange directly
<Input
  {...register("keyword")}
  onValueChange={(value) => {
    console.log(value);
    register("keyword").onValueChange(value);
  }}
/>

// Or better: Separate event handler
const handleKeywordChange = (value: string) => {
  console.log(value);
  setListParams({ ...listParams, page: 1, keyword: value });
};

Using Services - API call methods
TanStack Query Integration - Caching and refetching
auto-generated-overview - Auto-generated components
useSelection - Multi-select management

Get Started

Core Concepts

Database

API Development

Frontend Integration

Testing

Advanced Features

Tools & CLI

Configuration

API Reference

Troubleshooting

FAQ

Core Features

URL Sync

Type Safety

Auto Page Reset

register Pattern

Basic Usage

Import and Initialization

Using listParams

Changing State with setListParams

Form Binding with register

Real-world Examples

Complete List Page

Adding Custom Filters

Options

disableSearchParams

Type Safety

Compile-time Validation

Auto-completion

TanStack Router Integration

Cautions

1. Setting Initial Values

2. Type Assertion for Enum Fields

3. Using register with Custom onChange

​Core Features

URL Sync

Type Safety

Auto Page Reset

register Pattern

​Basic Usage

​Import and Initialization

​Using listParams

​Changing State with setListParams

​Form Binding with register

​Real-world Examples

​Complete List Page

​Adding Custom Filters

​URL Sharing and Bookmarking

​Options

​disableSearchParams

​Type Safety

​Compile-time Validation

​Auto-completion

​TanStack Router Integration

​Cautions

​1. Setting Initial Values

​2. Type Assertion for Enum Fields

​3. Using register with Custom onChange

​Related Documentation

Core Features

Basic Usage

Import and Initialization

Using listParams

Changing State with setListParams

Form Binding with register

Real-world Examples

Complete List Page

Adding Custom Filters

URL Sharing and Bookmarking

Options

disableSearchParams

Type Safety

Compile-time Validation

Auto-completion

TanStack Router Integration

Cautions

1. Setting Initial Values

2. Type Assertion for Enum Fields

3. Using register with Custom onChange

Related Documentation