Custom React hook to sync state with the URL

#javascript #typescript #react #webdev

When building React applications, it's often beneficial to reflect the state in the URL. This not only makes the state sharable but also allows users to bookmark or refresh pages without losing their context. In this post, we'll create a custom React hook called useParamState in TypeScript. This hook will function like useState, but it will also sync the state with the search parameters in the URL. Importantly, it will support complex object values.

Why `useParamState`?

React Router's useSearchParams hook is excellent for managing URL search parameters, but syncing them with component state can be cumbersome. The useParamState hook addresses this by:

Providing a simple API similar to useState.
Automatically syncing state with the URL search parameters.
Supporting complex types, including objects.

Prerequisites

Basic understanding of React, TypeScript, and React Router.
Familiarity with useState and useEffect.

Implementing `useParamState`

Step 1: Setting Up the Project

( This assumes you already know how to set up a react project, if not head over to Vite)

Ensure you have react-router-dom installed:

npm install react-router-dom

Step 2: The useParamState Hook

Here’s how you can implement the useParamState hook:


import { useCallback, useState } from 'react';
import { useSearchParams } from 'react-router-dom';

/**
 * A custom hook that syncs state with a URL search parameter.
 * Supports string, number, boolean, and object values.
 * @param key The search parameter key to sync with.
 * @param defaultValue The default value for the state.
 * @returns A stateful value, and a function to update it.
 */
function useParamState<T extends string | number | boolean | object>(
  key: string,
  defaultValue: T
): [T, (newValue: Partial<T> | T) => void] {
  const [searchParams, setSearchParams] = useSearchParams();
  const paramValue = searchParams.get(key);

  const [state, setState] = useState<T>(() => {
    if (paramValue === null) {
      return defaultValue;
    }
    try {
      return JSON.parse(paramValue) as T;
    } catch {
      return paramValue as T;
    }
  });

  const setParamState = useCallback(
    (newValue: Partial<T> | T) => {
      const updatedValue = typeof newValue === 'object' && !Array.isArray(newValue)
        ? { ...state, ...newValue }
        : newValue;

      setState(updatedValue as T);
      const newSearchParams = new URLSearchParams(searchParams);
      newSearchParams.set(key, JSON.stringify(updatedValue));
      setSearchParams(newSearchParams);
    },
    [key, searchParams, setSearchParams, state]
  );

  return [state, setParamState];
}

export default useParamState;

How It Works

Initialization:

The hook starts by checking if the specified search parameter exists in the URL. If it does, the hook parses it and uses it as the initial state. Otherwise, it falls back to the provided defaultValue.

State Update:

The setParamState function updates both the internal state and the search parameter in the URL. It uses JSON.stringify to serialize the state, allowing us to store complex objects in the URL.

Type Support:

The hook supports various types (string, number, boolean, and object) by leveraging TypeScript’s generics and JSON parsing.

Step 3: Using useParamState

Let's see how you can use useParamState in a React component:


import React from 'react';
import useParamState from './useParamState';

interface FilterState {
  status: string;
  sortBy: string;
}

const MyComponent: React.FC = () => {
  const [filter, setFilter] = useParamState<FilterState>('filter', {
    status: 'all',
    sortBy: 'date',
  });

  return (
    <div>
      <h2>Current Filter: {filter.status}, Sort by: {filter.sortBy}</h2>
      <button onClick={() => setFilter({ status: 'active', sortBy: filter.sortBy })}>
        Active
      </button>
      <button onClick={() => setFilter({ status: 'completed', sortBy: filter.sortBy })}>
        Completed
      </button>
      <button onClick={() => setFilter({ ...filter, sortBy: 'priority' })}>
        Sort by Priority
      </button>
    </div>
  );
};

export default MyComponent;

Step 4: Testing the Hook

To ensure that the useParamState hook works as expected, you can write unit tests using @testing-library/react:


import { renderHook, act } from '@testing-library/react';
import { MemoryRouter } from 'react-router-dom';
import useParamState from './useParamState';

interface FilterState {
  status: string;
  sortBy: string;
}

test('should sync object state with search params', () => {
  const wrapper = ({ children }: { children: React.ReactNode }) => (
    <MemoryRouter initialEntries={['/']}>{children}</MemoryRouter>
  );

  const { result } = renderHook(() => useParamState<FilterState>('filter', { status: 'all', sortBy: 'date' }), { wrapper });

  // Initial state
  expect(result.current[0]).toEqual({ status: 'all', sortBy: 'date' });

  // Update state and URL
  act(() => {
    result.current[1]({ status: 'active', sortBy: 'priority' });
  });

  // Updated state
  expect(result.current[0]).toEqual({ status: 'active', sortBy: 'priority' });
});

Conclusion

The useParamState hook simplifies the process of syncing state with URL search parameters, making your React applications more robust and user-friendly. With support for complex types like objects, this hook is a powerful tool for managing state that needs to persist across page reloads or be shared via URLs.

You can further extend this hook to handle even more complex data structures, but for most use cases, this implementation will cover your needs.

( Do comment on the article so that I can make this better and improve any mistakes I might have made, thanks in advance. )

Feel free to follow me on other platforms as well