clear-react-router 1.3.0 → 1.3.1

package/README.md

@@ -272,6 +272,53 @@ const { setContext, context } = useRouterContext();
 const loginHandler = () => setContext({ ...context, user: { name: 'John' } });
 ```
 
+### `useSearchParams()`
+
+Returns an object for working with URL query parameters. Supports reading and setting both single values and arrays.
+
+```
+import { useSearchParams } from 'clear-react-router';
+
+function ProductFilter() {
+  const { searchParams, getSearchParams, setSearchParams } = useSearchParams();
+
+  // Get a single value or array
+  const brand = getSearchParams('brand'); // 'nike' | ['nike', 'reebok'] | ''
+
+  // Set a single value
+  setSearchParams('brand', 'nike'); // ?brand=nike
+
+  // Set multiple values (array)
+  setSearchParams('brand', ['nike', 'reebok']); // ?brand=nike&brand=reebok
+
+  // Functional update (preserves other params)
+  setSearchParams((prev) => {
+    prev.set('page', '2');
+    prev.append('color', 'red');
+    return prev;
+  });
+
+  // Direct access to URLSearchParams
+  const allParams = searchParams.toString(); // "brand=nike&brand=reebok&page=2"
+}
+```
+**Returns:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `searchParams` | `URLSearchParams` | Raw `URLSearchParams` object for low-level access |
+| `getSearchParams` | `(key: string) => string \| string[]` | Returns a single value or an array if multiple values exist for the key |
+| `setSearchParams` | `(param: string, value: string \| string[]) => void` `or` `(updater: (prev: URLSearchParams) => URLSearchParams) => void` | Update query parameters. Supports single values, arrays, or functional updates |
+
+**Key features:**
+
+- ✅ **Array support** — `getSearchParams` returns `string[]` when multiple values exist for the same key
+- ✅ **Functional updates** — Update parameters based on previous state without losing other params
+- ✅ **Type-safe** — Proper TypeScript support with overloads
+- ✅ **Stable reference** — `setSearchParams` reference is stable and safe to use in `useEffect`
+
+> **Note:** `getSearchParams` returns `string` for single values, `string[]` for multiple values, and `''` if the key is not found.
+
 ## Lazy Loading
 
 Clear Router supports code-splitting out of the box. Simply pass a function that returns a dynamic import:

package/dist/hooks/useSearchParams.d.ts

@@ -0,0 +1,10 @@
+type UseSearchParamsReturn = {
+    searchParams: URLSearchParams;
+    getSearchParams(arg: string): string | string[];
+    setSearchParams: {
+        (param: string, value: string | string[]): void;
+        (param: (prevState: URLSearchParams) => URLSearchParams): void;
+    };
+};
+export declare const useSearchParams: () => UseSearchParamsReturn;
+export {};

package/dist/index.d.ts

@@ -8,5 +8,6 @@ export { useLoaderState } from './hooks/useLoaderState';
 export { useBlocker } from './hooks/useBlocker';
 export { useBeforeUnload } from './hooks/useBeforeUnload';
 export { useRouterContext } from './hooks/useRouterContext';
+export { useSearchParams } from './hooks/useSearchParams';
 export { createRouter } from './utils/utils';
 export type { RouteItem, BlockerState, Location } from './types/global';

package/dist/index.js

@@ -149,8 +149,9 @@ var useHandleNavigation = ({ setLocation, routeList, context, revalidateCache, i
 	const navigation = useCallback((nextLocation) => {
 		setLocation(nextLocation);
 		prevPathname.current = nextLocation.pathname;
-		if (nextLocation.pathname === window.location.pathname) return;
-		history.pushState(null, "", nextLocation.pathname);
+		const fullPath = nextLocation.search ? `${nextLocation.pathname}${nextLocation.search}` : nextLocation.pathname;
+		if (fullPath === window.location.pathname + window.location.search) return;
+		history.pushState(null, "", fullPath);
 	}, [setLocation]);
 	const transitionedNavigation = useCallback(({ nextLocation, isFirstCall, isAnimated }) => {
 		if (isAnimated && !isFirstCall) try {
@@ -427,26 +428,15 @@ var renderElement = (Component) => {
 };
 //#endregion
 //#region hooks/useServiceContext.ts
-var useNavigationState = () => {
-	const context = useContext(NavigationContext);
-	if (!Object.keys(context).length) throw new Error("hooks and Router component must be used within RouterProvider");
-	return context;
-};
-var useRouterActions = () => {
-	const context = useContext(ActionsContext);
-	if (!Object.keys(context).length) throw new Error("hooks and Router component must be used within RouterProvider");
-	return context;
-};
-var useRouterData = () => {
-	const context = useContext(DataContext);
-	if (!Object.keys(context).length) throw new Error("hooks and Router component must be used within RouterProvider");
-	return context;
-};
-var usePropsData = () => {
-	const context = useContext(PropsContext);
+var useServiceState = (reactContext) => {
+	const context = useContext(reactContext);
 	if (!Object.keys(context).length) throw new Error("hooks and Router component must be used within RouterProvider");
 	return context;
 };
+var useNavigationState = () => useServiceState(NavigationContext);
+var useRouterActions = () => useServiceState(ActionsContext);
+var useRouterData = () => useServiceState(DataContext);
+var usePropsData = () => useServiceState(PropsContext);
 //#endregion
 //#region context/RouterViewContext.ts
 var RouterViewContext = createContext({});
@@ -501,13 +491,13 @@ var useLocation = () => {
 //#region hooks/useNavigate.ts
 var useNavigate = () => {
 	const { updateLocation } = useRouterActions();
-	const location = useLocation();
+	const locationRef = useLatest(useLocation());
 	return useCallback(async (arg) => {
 		if (typeof arg === "number") return history.go(arg);
 		if (typeof arg === "string") {
-			if (arg !== location.pathname) await updateLocation({ pathname: arg });
-		} else if (JSON.stringify(arg) !== JSON.stringify(location)) await updateLocation(arg);
-	}, [location, updateLocation]);
+			if (arg !== locationRef.current.pathname) await updateLocation({ pathname: arg });
+		} else if (JSON.stringify(arg) !== JSON.stringify(locationRef.current)) await updateLocation(arg);
+	}, [updateLocation, locationRef]);
 };
 //#endregion
 //#region components/Link.tsx
@@ -576,4 +566,38 @@ var useRouterContext = () => {
 	};
 };
 //#endregion
-export { Link, Router, RouterProvider, createRouter, useBeforeUnload, useBlocker, useLoaderState, useLocation, useNavigate, useParams, useRouterContext };
+//#region hooks/useSearchParams.ts
+var useSearchParams = () => {
+	const location = useLocation();
+	const navigate = useNavigate();
+	const locationRef = useLatest(location);
+	const searchString = useMemo(() => location.search ? location.search.replace("?", "") : location.pathname.split("?")?.[1] ?? "", [location.pathname, location.search]);
+	const searchParams = useMemo(() => new URLSearchParams(searchString), [searchString]);
+	const getSearchParams = useCallback((param) => {
+		const allValues = searchParams.getAll(param);
+		return allValues.length > 1 ? allValues : allValues[0] ?? "";
+	}, [searchParams]);
+	const navigateWithSearchParams = useCallback((params) => {
+		const newSearch = params.toString();
+		navigate({
+			pathname: locationRef.current.pathname,
+			search: newSearch ? `?${newSearch}` : ""
+		});
+	}, [locationRef, navigate]);
+	return {
+		searchParams,
+		getSearchParams,
+		setSearchParams: useCallback((param, value) => {
+			const search = locationRef.current.search || "";
+			const currentParams = new URLSearchParams(search);
+			if (typeof param === "string" && value !== void 0) {
+				currentParams.delete(param);
+				(Array.isArray(value) ? value : [value]).forEach((v) => currentParams.append(param, v));
+				navigateWithSearchParams(currentParams);
+			} else if (typeof param === "function") navigateWithSearchParams(param(currentParams));
+			else throw new Error("useSearchParams first argument must be either function or string");
+		}, [locationRef, navigateWithSearchParams])
+	};
+};
+//#endregion
+export { Link, Router, RouterProvider, createRouter, useBeforeUnload, useBlocker, useLoaderState, useLocation, useNavigate, useParams, useRouterContext, useSearchParams };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clear-react-router",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "A lightweight, type-safe routing library for React applications",
   "author": "Andrew Bubnov",
   "scripts": {