Auto-generate your docs

useQueryString

The useQueryString hook provides a convenient way to create and manipulate URL query strings. It takes the current URLSearchParams and returns a function to generate new query strings with updated parameters.

Installation

npm install @craft-ui/hooks

Import

import { useQueryString } from "@craft-ui/hooks";

Usage

import { useQueryString } from "@craft-ui/hooks";
import { useSearchParams, useRouter } from "next/navigation";

function SearchFilters() {
  const router = useRouter();
  const searchParams = useSearchParams();
  const { createQueryString } = useQueryString(searchParams);

  const updateFilter = (key: string, value: string) => {
    const newQueryString = createQueryString({ [key]: value });
    router.push(`?${newQueryString}`);
  };

  return (
    <div>
      <button onClick={() => updateFilter("category", "electronics")}>
        Electronics
      </button>
      <button onClick={() => updateFilter("sort", "price")}>
        Sort by Price
      </button>
    </div>
  );
}

Parameters

URLSearchParams

required

The current URL search parameters, typically obtained from Next.js useSearchParams() or browser’s window.location.search.

Returns

(params: QueryParams) => string

A memoized function that accepts an object of query parameters and returns a new query string. Parameters with null values are removed from the query string.

QueryParams Type

type QueryParams = Record<string, string | number | null>;

string or number values are added/updated in the query string
null values remove the parameter from the query string

Type Definition

type QueryParams = Record<string, string | number | null>;

function useQueryString(searchParams: URLSearchParams): {
  createQueryString: (params: QueryParams) => string;
};

Examples

Product Filtering

import { useQueryString } from "@craft-ui/hooks";
import { useSearchParams, useRouter } from "next/navigation";

function ProductFilters() {
  const router = useRouter();
  const searchParams = useSearchParams();
  const { createQueryString } = useQueryString(searchParams);

  const setFilter = (filters: Record<string, string | null>) => {
    router.push(`/products?${createQueryString(filters)}`);
  };

  return (
    <div>
      <select
        onChange={(e) => setFilter({ category: e.target.value || null })}
        value={searchParams.get("category") || ""}
      >
        <option value="">All Categories</option>
        <option value="electronics">Electronics</option>
        <option value="clothing">Clothing</option>
        <option value="books">Books</option>
      </select>

      <select
        onChange={(e) => setFilter({ sort: e.target.value || null })}
        value={searchParams.get("sort") || ""}
      >
        <option value="">Default Sort</option>
        <option value="price-asc">Price: Low to High</option>
        <option value="price-desc">Price: High to Low</option>
        <option value="rating">Highest Rated</option>
      </select>

      <button onClick={() => setFilter({ category: null, sort: null })}>
        Clear Filters
      </button>
    </div>
  );
}

Pagination

import { useQueryString } from "@craft-ui/hooks";
import { useSearchParams, useRouter } from "next/navigation";

function Pagination({ totalPages }: { totalPages: number }) {
  const router = useRouter();
  const searchParams = useSearchParams();
  const { createQueryString } = useQueryString(searchParams);
  const currentPage = Number(searchParams.get("page")) || 1;

  const goToPage = (page: number) => {
    router.push(`?${createQueryString({ page })}`);
  };

  return (
    <div>
      <button
        onClick={() => goToPage(currentPage - 1)}
        disabled={currentPage === 1}
      >
        Previous
      </button>
      <span>Page {currentPage} of {totalPages}</span>
      <button
        onClick={() => goToPage(currentPage + 1)}
        disabled={currentPage === totalPages}
      >
        Next
      </button>
    </div>
  );
}

Search with Filters

import { useQueryString } from "@craft-ui/hooks";
import { useSearchParams, useRouter } from "next/navigation";
import { useState } from "react";

function SearchBar() {
  const router = useRouter();
  const searchParams = useSearchParams();
  const { createQueryString } = useQueryString(searchParams);
  const [query, setQuery] = useState(searchParams.get("q") || "");

  const handleSearch = (e: React.FormEvent) => {
    e.preventDefault();
    router.push(`/search?${createQueryString({ q: query, page: 1 })}`);
  };

  const clearSearch = () => {
    setQuery("");
    router.push(`/search?${createQueryString({ q: null, page: null })}`);
  };

  return (
    <form onSubmit={handleSearch}>
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search..."
      />
      <button type="submit">Search</button>
      {query && <button type="button" onClick={clearSearch}>Clear</button>}
    </form>
  );
}

Multi-Select Filters

import { useQueryString } from "@craft-ui/hooks";
import { useSearchParams, useRouter } from "next/navigation";

function TagFilters({ availableTags }: { availableTags: string[] }) {
  const router = useRouter();
  const searchParams = useSearchParams();
  const { createQueryString } = useQueryString(searchParams);
  
  const selectedTags = searchParams.get("tags")?.split(",").filter(Boolean) || [];

  const toggleTag = (tag: string) => {
    const newTags = selectedTags.includes(tag)
      ? selectedTags.filter((t) => t !== tag)
      : [...selectedTags, tag];

    router.push(
      `?${createQueryString({
        tags: newTags.length > 0 ? newTags.join(",") : null,
      })}`
    );
  };

  return (
    <div>
      {availableTags.map((tag) => (
        <button
          key={tag}
          onClick={() => toggleTag(tag)}
          style={{
            fontWeight: selectedTags.includes(tag) ? "bold" : "normal",
          }}
        >
          {tag}
        </button>
      ))}
    </div>
  );
}

Date Range Filter

import { useQueryString } from "@craft-ui/hooks";
import { useSearchParams, useRouter } from "next/navigation";

function DateRangeFilter() {
  const router = useRouter();
  const searchParams = useSearchParams();
  const { createQueryString } = useQueryString(searchParams);

  const startDate = searchParams.get("startDate") || "";
  const endDate = searchParams.get("endDate") || "";

  const updateDateRange = (start: string, end: string) => {
    router.push(
      `?${createQueryString({
        startDate: start || null,
        endDate: end || null,
      })}`
    );
  };

  return (
    <div>
      <input
        type="date"
        value={startDate}
        onChange={(e) => updateDateRange(e.target.value, endDate)}
      />
      <input
        type="date"
        value={endDate}
        onChange={(e) => updateDateRange(startDate, e.target.value)}
      />
      <button onClick={() => updateDateRange("", "")}>
        Clear Dates
      </button>
    </div>
  );
}

import { useQueryString } from "@craft-ui/hooks";
import { useSearchParams, useRouter } from "next/navigation";

function TabNavigation() {
  const router = useRouter();
  const searchParams = useSearchParams();
  const { createQueryString } = useQueryString(searchParams);
  const activeTab = searchParams.get("tab") || "overview";

  const tabs = ["overview", "details", "reviews", "specifications"];

  return (
    <div>
      {tabs.map((tab) => (
        <button
          key={tab}
          onClick={() => router.push(`?${createQueryString({ tab })}`)
          }
          style={{
            fontWeight: activeTab === tab ? "bold" : "normal",
          }}
        >
          {tab.charAt(0).toUpperCase() + tab.slice(1)}
        </button>
      ))}
    </div>
  );
}

Common Patterns

Preserving Existing Parameters

The hook automatically preserves existing parameters:

// Current URL: /products?category=electronics&page=2
const newQuery = createQueryString({ sort: "price" });
// Result: "category=electronics&page=2&sort=price"

Removing Parameters

Use null to remove parameters:

const newQuery = createQueryString({ filter: null });
// Removes the 'filter' parameter from the query string

Multiple Updates

Update multiple parameters at once:

const newQuery = createQueryString({
  category: "books",
  sort: "rating",
  page: 1,
});

Reset All Filters

const resetFilters = () => {
  const newQuery = createQueryString({
    category: null,
    sort: null,
    page: null,
    search: null,
  });
  router.push(`?${newQuery}`);
};

Use Cases

Building search and filter interfaces
Implementing pagination
Managing tab navigation with URL state
Creating shareable URLs with filter states
Handling sort options
Multi-select filters
Date range selectors
Any scenario requiring URL query parameter manipulation

Notes

The hook is designed to work with Next.js App Router’s useSearchParams
The createQueryString function is memoized and only recreates when searchParams changes
Numeric values are automatically converted to strings in the query string
Setting a parameter to null removes it from the query string
The hook preserves all existing parameters unless explicitly overridden or set to null
The returned query string does not include the leading ? character
This hook does not modify the URL directly; you need to use it with a router or navigation method

⌘I

Get Started

Base UI Components

Craft UI Components

Loaders

Hooks

Guides

useQueryString

useQueryString

Installation

Import

Usage

Parameters

Returns

QueryParams Type

Type Definition

Examples

Product Filtering

Search with Filters

Multi-Select Filters

Date Range Filter

Tab Navigation

Common Patterns

Preserving Existing Parameters

Removing Parameters

Multiple Updates

Reset All Filters

Use Cases

Notes

​useQueryString

​Installation

​Import

​Usage

​Parameters

​Returns

​QueryParams Type

​Type Definition

​Examples

​Product Filtering

​Pagination

​Search with Filters

​Multi-Select Filters

​Date Range Filter

​Tab Navigation

​Common Patterns

​Preserving Existing Parameters

​Removing Parameters

​Multiple Updates

​Reset All Filters

​Use Cases

​Notes

useQueryString

Installation

Import

Usage

Parameters

Returns

QueryParams Type

Type Definition

Examples

Product Filtering

Pagination

Search with Filters

Multi-Select Filters

Date Range Filter

Tab Navigation

Common Patterns

Preserving Existing Parameters

Removing Parameters

Multiple Updates

Reset All Filters

Use Cases

Notes