Stable useSearchParams for specified keys

[Noyabronok]

Problem

When a component updates the query string, all instances of useSearchParams return a new searchParams object, triggering dependency array hooks like 'useEffect'. This is good when the code cares about the changed parameters, but it's undesirable when the code doesn't. Considering that multiple components can maintain their state in the query string, developers must remember to add additional logic to each one to check if the keys they care about have actually changed, thereby avoiding any negative side effects downstream.

Proposed solutions

Option A - update useSearchParams

Update the useSearchParams function to

1. Accept a list of keys to filter for ( let's call the parameter filterKeys).
2. When filterKeys are provided - filter the searchParameters for those keys. Let's call that internal variable filteredParams
3. Memoize the filteredParams based on a sorted deep comparison.
   1. Note: sorting can be made optional by introducing another parameter, in case a change of order matters.
4. Return the memoized filteredParams either instead of searchParams or as a 3rd tuple element.

Option B - add useFilterSearchParams

If messing around with the useSearchParams is too much, introduce a new hook useFilterSearchParams. It would have the same features as described above, but without the baggage of backwards support for useSearchParams api.

Example implementation for option B

import { useMemo, useRef } from 'react'
import { useSearchParams, type URLSearchParamsInit } from 'react-router-dom'

export interface UseFilterSearchParamsProps {
  defaultInit?: URLSearchParamsInit | undefined
  filterKeys: string[]
}

/**
 * Returns a stable subset of URL search params filtered by the specified keys.
 * The setter function updates the entire query string as usual.
 * @param filterKeys The keys of the search params to include in the returned subset.
 * @param defaultInit Optional default initialization for the search params.
 * @returns
 */
export const useFilterSearchParams = ({
  defaultInit,
  filterKeys
}: UseFilterSearchParamsProps) => {
  const [searchParams, setSearchParams] = useSearchParams(defaultInit)

  const filteredParamsRef = useRef(new URLSearchParams())

  // Only update the ref (and trigger a new memo) when the filtered params actually change
  const filteredParams = useMemo(() => {
    const newFilteredParams = new URLSearchParams(
      Array.from(searchParams.entries()).filter(([key]) => filterKeys.includes(key))
    )

    // Only update ref if the filtered params actually changed
    if (!areSearchParamsEqual(filteredParamsRef.current, newFilteredParams)) {
      filteredParamsRef.current = newFilteredParams
    }

    // Always return the ref value for stability
    return filteredParamsRef.current
  }, [searchParams, filterKeys])

  return [filteredParams, setSearchParams] as const
}

export const areSearchParamsEqual = (params1: URLSearchParams, params2: URLSearchParams) => {
  const entries1 = Array.from(params1.entries()).sort()
  const entries2 = Array.from(params2.entries()).sort()

  if (entries1.length !== entries2.length) {
    return false
  }

  for (let i = 0; i < entries1.length; i++) {
    const [key1, value1] = entries1[i]
    const [key2, value2] = entries2[i]
    if (key1 !== key2 || value1 !== value2) {
      return false
    }
  }

  return true
}