{"id":13496491,"url":"https://github.com/rudyhuynh/use-url-search-params","last_synced_at":"2025-08-21T00:32:04.327Z","repository":{"id":35007738,"uuid":"189707630","full_name":"rudyhuynh/use-url-search-params","owner":"rudyhuynh","description":"A React Hook to use URL query string as a state management","archived":false,"fork":false,"pushed_at":"2023-03-07T02:31:03.000Z","size":5843,"stargazers_count":66,"open_issues_count":3,"forks_count":5,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-29T10:05:00.895Z","etag":null,"topics":["react","react-hooks","url-query","urlsearchparams"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rudyhuynh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-06-01T08:12:51.000Z","updated_at":"2025-05-21T08:11:59.000Z","dependencies_parsed_at":"2024-01-16T09:54:34.001Z","dependency_job_id":"e04174f1-a995-431c-83b1-140aa59da03b","html_url":"https://github.com/rudyhuynh/use-url-search-params","commit_stats":{"total_commits":117,"total_committers":4,"mean_commits":29.25,"dds":"0.20512820512820518","last_synced_commit":"3be9128b6058578ae8ee364deb368f6cea5c9c7c"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"purl":"pkg:github/rudyhuynh/use-url-search-params","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudyhuynh%2Fuse-url-search-params","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudyhuynh%2Fuse-url-search-params/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudyhuynh%2Fuse-url-search-params/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudyhuynh%2Fuse-url-search-params/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rudyhuynh","download_url":"https://codeload.github.com/rudyhuynh/use-url-search-params/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rudyhuynh%2Fuse-url-search-params/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271409446,"owners_count":24754715,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-20T02:00:09.606Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["react","react-hooks","url-query","urlsearchparams"],"created_at":"2024-07-31T19:01:48.961Z","updated_at":"2025-08-21T00:32:03.979Z","avatar_url":"https://github.com/rudyhuynh.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# `useUrlSearchParams()`\n\n[![GitHub license](https://img.shields.io/github/license/Naereen/StrapDown.js.svg)](https://github.com/rudyhuynh/use-url-search-params/blob/master/License)\n\nA React Hook to use [URL query string](https://en.wikipedia.org/wiki/Query_string) as a state management\n\n[Demo](https://rudyhuynh.github.io/use-url-search-params)\n\n## Why you need this\n\n- Your app need to persist its state after user refresh the page (used for simple, non-sensitive data).\n- Some page settings (ex: table filter, sorting, paging, etc.) should be saved in the URL so that user can easily pass to others. e.g. Tester can easily send a URL of a page to developer with very least reproduce steps.\n- You want to do something (request new data, etc.) every time some URL query value changes.\n- Combine all of the above with a URL query as a single source of truth.\n\n## Installation\n\n```\nnpm install use-url-search-params\n```\n\nor\n\n```\nyarn add use-url-search-params\n```\n\n## How to use\n\nFor most of the time you will do something like this:\n\n```js\nimport React from \"react\";\nimport { useUrlSearchParams } from \"use-url-search-params\";\n\nfunction App() {\n  // Your page URL will be like this by default: http://my.page?checked=true\n  const [params, setParams] = useUrlSearchParams({ checked: true });\n\n  React.useEffect(() =\u003e {\n    // do something when `params.checked` is updated.\n  }, [params.checked]);\n\n  return (\n    \u003cdiv\u003e\n      \u003cinput type=\"checkbox\" checked={params.checked} onChange={(e) =\u003e setParams({ checked: e.target.checked })} /\u003e\n    \u003c/div\u003e\n  );\n}\n```\n\n## How to control the value parsed from URL query\n\nBy default, all values parsed from URL query are string. In case you want to get boolean or number value, pass a second argument to `useUrlSearchParams()` to specify data type you want to get from `params` object. Here is an example:\n\n```js\nconst initial = {\n  y: \"option1\",\n};\nconst types = {\n  x: Number,\n  y: Boolean,\n  z: Date,\n  t: [\"option1\", \"option2\", \"option3\"],\n};\nconst [params, setParams] = useUrlSearchParams(initial, types);\n\n// `params.x` will be number (or NaN)\n// `params.y` will be one of [undefined, true, false]\n// `params.z` will be instance of Date (can be Invalid Date)\n// `params.t` will be one of [\"option1\", \"option2\", \"option3\"] (can be `undefined` if not specified in `initial`)\n```\n\n## Complex data structure\n\nAlthough you can use `JSON.parse()` and `JSON.stringify()` to get/set arbitrary serializable data to URL query, it is not recommended. URL query is a good place to store and persist page settings as key/value pairs such as table filter, sorting, paging, etc. We should keep it that way for simplicity. **For complex data structure, you should consider using other state management for better performance, security and flexibility.**\n\n\u003e **WARNING**: Be aware of XSS attack. Be careful to validate values from URL query before using it by either using `types` - the second parameter passed to `useUrlSearchParams()` or validate them yourself if neccessary.\n\nBut if you still insist, here is an example:\n\n```js\nfunction App() {\n  const [params, setParams] = useUrlSearchParams(\n    {},\n    {\n      complexData: (dataString) =\u003e {\n        try {\n          return JSON.parse(dataString);\n        } catch (e) {\n          return {};\n        }\n      },\n    }\n  );\n\n  const onSetParams = (data) =\u003e {\n    setParams({ complexData: JSON.stringify(data) });\n  };\n\n  return \u003cdiv\u003e{/*...*/}\u003c/div\u003e;\n}\n```\n\n## React Router\n\nShould just work with React Router or any routing system. Just make sure that your component re-render whenever route changes.\n\n## API\n\n- **useUrlSearchParams([initial, types, replace])**\n  - `initial` (optional | Object): To set default values for URL query string.\n  - `types` (optional | Object): Has similar shape with `initial`, help to resolve values from URL query string. Supported types:\n    - `String` (default)\n    - `Number`\n    - `Bool`\n    - `Date` - [`Date​.prototype​.toISOString()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) is used to parse date to string, e.g date string in your URL query is zero UTC offset\n    - Array of available string values (like enum)\n    - A custom resolver function\n  - `replace` (optional | boolean | default: false): If true, will call `histor#replaceState()` instead of `history#pushState()` on url search param change.\n\n## Read more (for maintainers)\n\nThis library is built base on [URLSearchParams interface](https://developer.mozilla.org/en-US/docs/Web/API/URLSearchParams)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frudyhuynh%2Fuse-url-search-params","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frudyhuynh%2Fuse-url-search-params","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frudyhuynh%2Fuse-url-search-params/lists"}