Product Filter Configuration

A reusable filtering component for an e-commerce product catalog that stores filter state in URL query parameters.

Requirements

Build a TypeScript React hook called useProductFilters that manages product filtering state using URL query parameters. The hook should handle four filter parameters:

1. Search query (key: q) - A text search string that can be empty or have a value
2. Category (key: category) - Must be one of: "electronics", "clothing", "books", "home", or "toys". Should default to "electronics" when not specified
3. Minimum price (key: minPrice) - An integer value in cents. Should default to 0 when not specified
4. In stock only (key: inStock) - A boolean flag. Should default to false when not specified

The hook must return an object with the current filter values and setter functions for each parameter.

Type Safety Requirements

• The category value must never be null or undefined in the returned state
• The minimum price must never be null or undefined in the returned state
• The in-stock flag must never be null or undefined in the returned state
• The search query can be null when not present in the URL
• All type inference should work correctly without manual type annotations

Behavior Requirements

• When a user navigates to the page without query parameters, the defaults should apply
• Setting a filter value should update the URL query string
• Setting the search query to null should remove it from the URL
• All filters should work independently and not interfere with each other

Test Cases

• When no query parameters are present, category returns "electronics", minPrice returns 0, inStock returns false, and search returns null @test
• When search parameter is set in URL, the hook returns the search value as a string @test
• When category is set to "books" in URL, the hook returns "books" @test
• When minPrice is set to 5000 in URL, the hook returns the number 5000 @test
• When inStock is set to "true" in URL, the hook returns boolean true @test

Implementation

@generates

API

type Category = "electronics" | "clothing" | "books" | "home" | "toys";

interface ProductFilters {
  search: string | null;
  category: Category;
  minPrice: number;
  inStock: boolean;
}

interface ProductFilterSetters {
  setSearch: (value: string | null) => void;
  setCategory: (value: Category) => void;
  setMinPrice: (value: number) => void;
  setInStock: (value: boolean) => void;
}

export function useProductFilters(): ProductFilters & ProductFilterSetters;

Dependencies { .dependencies }

nuqs { .dependency }

Provides type-safe URL query state management for React.

@satisfied-by