feat(useUrlSearchParams): Add a stringify option for users to provide stringify logic (#4773)

mingXta · OrbisK · antfu · web-flow · commit 6a5233450b6f · 2025-06-19T17:51:02.000+09:00
Co-authored-by: Robin &lt;robin.kehl@singular-it.de&gt;
Co-authored-by: Anthony Fu &lt;anthonyfu117@hotmail.com&gt;
diff --git a/packages/core/useUrlSearchParams/index.md b/packages/core/useUrlSearchParams/index.md
@@ -47,3 +47,22 @@ params.foo = 'bar'
 params.vueuse = 'awesome'
 // url updated to `/your/route#foo=bar&vueuse=awesome`
 ```
+
+### Custom Stringify Function
+
+You can provide a custom function to serialize URL parameters using the `stringify` option. This is useful when you need special formatting for your query string.
+
+```js
+import { useUrlSearchParams } from '@vueuse/core'
+
+// Custom stringify function that removes equal signs for empty values
+const params = useUrlSearchParams('history', {
+  stringify: (params) => {
+    return params.toString().replace(/=(&|$)/g, '$1')
+  }
+})
+
+params.foo = ''
+params.bar = 'value'
+// url updated to `?foo&bar=value` instead of `?foo=&bar=value`
+```
diff --git a/packages/core/useUrlSearchParams/index.test.ts b/packages/core/useUrlSearchParams/index.test.ts
@@ -227,6 +227,24 @@ describe('useUrlSearchParams', () => {
         await nextTick()
         expect(params).toEqual({ foo: null, bar: false })
       })
+
+      it('strips equal sign for empty params use customer stringify function', async () => {
+        const params = useUrlSearchParams(mode, { stringify: params => params.toString().replace(/=(&|$)/g, '$1') })
+        params.foo = ''
+        params.bar = ''
+        await nextTick()
+        switch (mode) {
+          case 'history':
+            expect(window.history.replaceState).toBeCalledWith(null, '', '/?foo&bar')
+            break
+          case 'hash':
+            expect(window.history.replaceState).toBeCalledWith(null, '', '/#?foo&bar')
+            break
+          case 'hash-params':
+            expect(window.history.replaceState).toBeCalledWith(null, '', '/#foo&bar')
+            break
+        }
+      })
     })
   })
 
diff --git a/packages/core/useUrlSearchParams/index.ts b/packages/core/useUrlSearchParams/index.ts
@@ -36,6 +36,14 @@ export interface UseUrlSearchParamsOptions<T> extends ConfigurableWindow {
    * @default 'replace'
    */
   writeMode?: 'replace' | 'push'
+
+  /**
+   * Custom function to serialize URL parameters
+   * When provided, this function will be used instead of the default URLSearchParams.toString()
+   * @param params The URLSearchParams object to serialize
+   * @returns The serialized query string (should not include the leading '?' or '#')
+   */
+  stringify?: (params: URLSearchParams) => string
 }
 
 /**
@@ -56,6 +64,7 @@ export function useUrlSearchParams<T extends Record<string, any> = UrlParams>(
     write: enableWrite = true,
     writeMode = 'replace',
     window = defaultWindow!,
+    stringify = params => params.toString(),
   } = options
 
   if (!window)
@@ -78,8 +87,7 @@ export function useUrlSearchParams<T extends Record<string, any> = UrlParams>(
   }
 
   function constructQuery(params: URLSearchParams) {
-    const stringified = params.toString()
-
+    const stringified = stringify(params)
     if (mode === 'history')
       return `${stringified ? `?${stringified}` : ''}${window.location.hash || ''}`
     if (mode === 'hash-params')
