Type Safe Search Params in React

The Problem with Search Params

Working with URL search parameters in React, especially with libraries like React Router, often involves a lot of manual parsing and string manipulation. You pull values from window.location.search, use URLSearchParams to get individual keys, and then convert them to the correct types. This is tedious and, more importantly, error-prone. What happens if you expect a number but get a string? Or a boolean that’s not true or false?

This is where type safety becomes crucial. We want to ensure that when we read a search param, we get exactly what we expect, or at least handle the cases where we don’t gracefully.

A Pattern for Type Safety

Let’s build a simple, reusable hook to manage type-safe search parameters. We’ll use TypeScript to define the expected types and ensure compile-time safety.

Step 1: Define Your Schema

First, define an interface or type that represents your expected search parameters and their types. For example, let’s say we have a product listing page with filtering options for category (string), priceLimit (number), and inStock (boolean).

1
interface ProductSearchParams {
2
  category: string;
3
  priceLimit?: number; // Optional parameter
4
  inStock?: boolean;  // Optional parameter
5
}

Step 2: Create a Generic Hook

Now, let’s create a hook, let’s call it useTypedSearchParams, that takes a generic type representing our schema and returns a function to get typed values and a function to set them.

We’ll leverage URLSearchParams under the hood, but add our type-checking logic.

1
import { useMemo, useCallback } from 'react';
2
import { useLocation, useNavigate } from 'react-router-dom';
3

4
// Helper to parse a single value with type conversion
5
function parseParam<T>(value: string | null, type: 'string' | 'number' | 'boolean'): T | undefined {
6
  if (value === null) {
7
    return undefined;
8
  }
9

10
  switch (type) {
11
    case 'string':
12
      return value as unknown as T;
13
    case 'number':
14
      const num = parseFloat(value);
15
      return isNaN(num) ? undefined : (num as unknown as T);
16
    case 'boolean':
17
      // Consider 'true', '1', 'yes' as true, anything else as false
18
      const lowerValue = value.toLowerCase();
19
      return (lowerValue === 'true' || lowerValue === '1' || lowerValue === 'yes') ? true as unknown as T : false as unknown as T;
20
    default:
21
      return undefined;
22
  }
23
}
24

25
// Helper to stringify a value for URL
26
function stringifyParam(value: unknown): string | undefined {
27
  if (value === undefined || value === null) {
28
    return undefined;
29
  }
30
  if (typeof value === 'boolean') {
31
    return value ? 'true' : 'false';
32
  }
33
  return String(value);
34
}
35

36
function useTypedSearchParams<T extends Record<string, any>>() {
37
  const location = useLocation();
38
  const navigate = useNavigate();
39

40
  const searchParams = useMemo(() => new URLSearchParams(location.search), [location.search]);
41

42
  const getParams = useCallback(<K extends keyof T>(key: K, type: 'string' | 'number' | 'boolean'): T[K] | undefined => {
43
    const value = searchParams.get(String(key));
44
    return parseParam<T[K]>(value, type);
45
  }, [searchParams]);
46

47
  const setParams = useCallback((paramsToSet: Partial<Record<keyof T, unknown>> & { [key in keyof T]?: T[key] | undefined }) => {
48
    const newSearchParams = new URLSearchParams(location.search);
49
    Object.entries(paramsToSet).forEach(([key, value]) => {
50
      const stringValue = stringifyParam(value);
51
      if (stringValue === undefined) {
52
        newSearchParams.delete(key);
53
      } else {
54
        newSearchParams.set(key, stringValue);
55
      }
56
    });
57
    navigate(`${location.pathname}?${newSearchParams.toString()}`, { replace: true });
58
  }, [navigate, location.pathname, location.search]);
59

60
  return { getParams, setParams, currentSearchParams: searchParams };
61
}
62

63
export default useTypedSearchParams;

Step 3: Use the Hook in Your Component

Now, you can use this hook in your React components. You’ll pass the expected type to the hook.

1
import React from 'react';
2
import useTypedSearchParams from './useTypedSearchParams'; // Assuming you saved the hook here
3

4
interface ProductSearchParams {
5
  category: string;
6
  priceLimit?: number;
7
  inStock?: boolean;
8
}
9

10
function ProductList() {
11
  const { getParams, setParams } = useTypedSearchParams<ProductSearchParams>();
12

13
  // Get values safely
14
  const category = getParams('category', 'string') || 'all';
15
  const priceLimit = getParams('priceLimit', 'number');
16
  const inStock = getParams('inStock', 'boolean');
17

18
  // Example of how to update params
19
  const handleFilterChange = (newCategory: string) => {
20
    setParams({ category: newCategory, priceLimit: undefined, inStock: true });
21
  };
22

23
  const handlePriceChange = (newPrice: number | undefined) => {
24
    setParams({ priceLimit: newPrice });
25
  };
26

27
  return (
28
    <div>
29
      <h1>Products</h1>
30
      <p>Current Category: {category}</p>
31
      {priceLimit !== undefined && <p>Max Price: {priceLimit}</p>}
32
      {inStock !== undefined && <p>In Stock: {inStock ? 'Yes' : 'No'}</p>}
33

34
      <button onClick={() => handleFilterChange('electronics')}>Filter Electronics</button>
35
      <button onClick={() => handlePriceChange(100)}>Set Max Price to $100</button>
36
      <button onClick={() => setParams({ priceLimit: undefined, inStock: undefined })}>Clear Filters</button>
37
    </div>
38
  );
39
}
40

41
export default ProductList;

Why This Works

Type Safety: By defining ProductSearchParams and using TypeScript generics in useTypedSearchParams, you get compile-time checks. If you try to getParams('nonExistentKey', 'string') or getParams('priceLimit', 'string'), TypeScript will flag it.
Centralized Logic: All the parsing, stringifying, and navigation logic is in one place, the useTypedSearchParams hook. This makes your components cleaner and less repetitive.
Readability: Components become more readable because the intent is clear: you’re getting a string for category, a number for priceLimit, etc.
Maintainability: If you need to change how a parameter is parsed (e.g., handle a new boolean format), you only need to update the parseParam function within the hook.

This pattern provides a robust way to handle URL search parameters in your React applications, ensuring type safety and simplifying your code.