Add use-url-state Hook to Sync State with URL Query Params

[mees-van-wel]

One of the common needs in modern web applications is the ability to persist state via URL query parameters, especially for use cases like filters, configurations, or even dynamic content. In a scenario where users might want to share a particular view, configuration, or selection, having a hook like useUrlState to manage URL state seamlessly can provide a powerful and user-friendly experience.

Why useUrlState is valuable:

The addition of a useUrlState hook would offer the following advantages:

• Shareability: Users can share URLs that preserve state across sessions, enabling easy sharing of filtered data, selected configurations (e.g., filters for search, color/size choices in an e-commerce setting), and more.
• Back/Forward Navigation: It allows for native browser navigation using the back/forward buttons without needing extra state management to keep the UI in sync with the URL.
• Deep Linking: It becomes easier to build deep links where users can return to a specific state of the app.
• Aligns with Modern Apps: Many React-based applications increasingly rely on URL synchronization for a more dynamic, stateful user experience, especially in e-commerce, dashboards, or form-heavy apps.

Proposed API:

const [urlState, setUrlState] = useUrlState({
  color: 'red',
  currentId: 1,
  isActive: true
});

This API solves the issue of multiple hook instances overwriting each other by combining all state into one object. The state is fully type-safe, allowing developers to define the structure of urlState. This ensures the state is consistent and avoids conflicts when multiple query parameters need to be managed.

The hook would:

• Accept an object as the initial state, where each key represents a query parameter.
• Automatically JSON.stringify each state value when storing it in the URL and JSON.parse when retrieving it, ensuring any type (object, array, boolean, number, etc.) can be supported.
• Keep everything synchronized so that all state variables are preserved in the URL and can be shared or restored correctly.

Example Usage:

const [urlState, setUrlState] = useUrlState({
  color: 'red',
  currentId: 1,
  isActive: true
});

// Update the state
setUrlState((current) => ({ ...current, color: 'blue', isActive: false }));

By initializing the hook with a single object containing all the state variables, this approach prevents overwriting instances of useUrlState while maintaining full type safety. Each key-value pair in the object corresponds to a query parameter, allowing easy management and synchronization between the URL and component state.

[rtivital]

Everything that is related to url must be handled by a router package, it is not planned to introduce such hooks as router implementations are very different depending on the package.

[mees-van-wel]

Thank you for your feedback. I understand the concern about router packages varying across different frameworks, and the desire to keep the library unopinionated regarding routing solutions. However, I believe it's possible to implement a useUrlState hook in a framework-agnostic way by leveraging the native browser history API. This approach avoids dependencies on any specific router implementation while still providing the benefits of synchronizing state with URL query parameters.

Here's how the useUrlState hook can be implemented using native browser APIs:

import { useCallback, useEffect, useRef, useState } from "react";

const getUrlParams = () => {
  const searchParams = new URLSearchParams(window.location.search);
  const params: Record<string, any> = {};
  searchParams.forEach((value, key) => {
    try {
      // Decode the parameter value and parse it from JSON
      params[key] = JSON.parse(decodeURIComponent(value));
    } catch {
      // If parsing fails, assign the decoded value directly
      params[key] = decodeURIComponent(value);
    }
  });
  return params;
};

const useUrlState = <T extends Record<string, any>>(initialState: T) => {
  const [state, setState] = useState<T>(() => {
    // On initial render, merge initial state with URL parameters
    const urlParams = getUrlParams();
    return { ...initialState, ...urlParams };
  });

  // Ref to track if the state update is from a popstate event
  const isPopState = useRef(false);

  useEffect(() => {
    const handlePopState = () => {
      isPopState.current = true; // Set flag to prevent URL update in the next effect
      const urlParams = getUrlParams();
      // Update state with parameters from the URL when navigating back/forward
      setState((prevState) => ({ ...prevState, ...urlParams }));
    };

    // Listen for browser navigation events (back/forward)
    window.addEventListener("popstate", handlePopState);
    return () => {
      window.removeEventListener("popstate", handlePopState);
    };
  }, []);

  useEffect(() => {
    if (isPopState.current) {
      // Skip updating the URL if the state change originated from a popstate event
      isPopState.current = false;
      return;
    }

    const searchParams = new URLSearchParams();

    Object.entries(state).forEach(([key, value]) => {
      if (value !== undefined && value !== null) {
        // Stringify and encode each state value before adding it to the URL
        searchParams.set(key, encodeURIComponent(JSON.stringify(value)));
      }
    });

    // Construct the new URL with updated query parameters
    const newUrl = `${window.location.pathname}?${searchParams.toString()}${window.location.hash}`;
    // Update the browser's history without reloading the page
    window.history.pushState(null, "", newUrl);
  }, [state]);

  const updateState = useCallback((updater: (current: T) => T) => {
    // Update the state using the provided updater function
    setState((current) => updater(current));
  }, []);

  return [state, updateState] as const;
};

export default useUrlState;

Key Points:

• Framework-Agnostic:
  Utilizes native browser APIs (window.history.pushState, URLSearchParams, popstate event) without relying on routing libraries.

• URL Manipulation Without Reloads:
  Updates the URL to reflect state changes without reloading the page.

• State Synchronization:
  Keeps component state and URL query parameters in sync in both directions:
  State to URL: Updates the URL when state changes.
  URL to State: Updates the state when the URL changes (e.g., browser navigation).

• Browser Navigation Support:
  Handles popstate events to reflect browser navigation in the component state without inconsistencies.

• Type Safety and Flexibility:
  Accepts a generic initial state (T), maintaining type safety and allowing explicit state structure definition.

Advantages of Using Native Browser APIs:

• Router Independence:
  Avoids conflicts with routing implementations, suitable for any application.

• Broad Compatibility:
  Works across all modern browsers.

• Enhanced User Experience:
  Sharebility: Users can share URLs that preserve the application's state.
  Deep Linking: Enables bookmarking or direct navigation to specific app states.
  Seamless Navigation: Integrates smoothly with browser back and forward buttons.

Addressing Potential Concerns:

• Router Integration:
  Does not interfere with existing routers; only modifies query parameters.

• State Consistency:
  Uses a flag (isPopState) to prevent infinite loops, ensuring consistent state during navigation.

• Safe Encoding of Parameters:
  Handles special characters using encodeURIComponent and decodeURIComponent.

• Scroll Behavior Management:
  Leaves scroll restoration to developers, focusing solely on state synchronization.

• Complex Data Types Support:
  Serializes complex state values to JSON for inclusion in the URL.

• Performance:
  Efficiently updates the URL only when necessary, avoiding unnecessary re-renders or history entries.

Next Steps:

I welcome any feedback and are open to integrating this functionality in a way that aligns with your library's vision and standards. I'm eager to discuss how this hook can add value to your project.

[asmyshlyaev177]

Wrote a similar hook for react-router and next.js https://github.com/asmyshlyaev177/state-in-url , very simple and well tested, check it out.

import React from 'react';
//import { useUrlState } from 'state-in-url/next';
import { useUrlState } from 'state-in-url/react-router';

const form: Form = {
  name: '',
  age: undefined,
  agree_to_terms: false,
  tags: [],
};

type Form = {
  name: string;
  age?: number;
  agree_to_terms: boolean;
  tags: {id: string; value: {text: string; time: Date } }[];
};

export const useFormState = () => {
  const { urlState, setUrl: setUrlBase, reset } = useUrlState(form);

  // first navigation will push new history entry
  // all following will just replace that entry
  // this way will have history with only 2 entries - ['/url', '/url?key=param']

  const replace = React.useRef(false);
  const setUrl = React.useCallback((
      state: Parameters<typeof setUrlBase>[0],
      opts?: Parameters<typeof setUrlBase>[1]
    ) => {
      setUrlBase(state, { replace: replace.current, ...opts });
      replace.current = true;
  }, [setUrlBase]);

  return { urlState, setUrl, resetUrl: reset };
};