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
useStateanduseEffect.
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
Discover more from Coursity
Subscribe to get the latest posts sent to your email.