bring-shrubbery / use-search-params-state

Use search params as a state in your web application.

Search Params Hooks

Features

• 😌 Sync state to the URL Search Params and back again.
• 💪 Use your own state manager.
• 🤓 Keeps URL clean by automatically removing default values.
• 😳 React Server Components ready.
• 🚀 Next.js integration.
• 🤯 Full TypeScript support.
• 😇 Integrations for SvelteKit/Solid.js coming soon.
• ⚡️ Accepts Zod schema for validation and parsing (WIP).

Packages

Package	Latest Version
@sp-hooks/react
@sp-hooks/next

Getting Started

Step 1 ⭐️

Before we start, don't forget to star this repo and follow @bring-shrubbery, thanks!

Next.js

pnpm add @sp-hooks/next

React.js

pnpm add @sp-hooks/react

Examples

Simple Next.js usage

Following example will render a button, which when clicked will toggle the button text between "hello" and "world". It will also update the search params to include the value, which means that after refreshing the page, the state will be preserved.

import { useState } from "react";

import { useObserveAndStore } from "@sp-hooks/next";

const Component = () => {
  const [darkMode, setDarkMode] = useState(false);

  useObserveAndStore({ darkMode });

  return (
    <button onClick={() => setDarkMode(!darkMode)}>
      {darkMode ? "🌚" : "☀️"}
    </button>
  );
};

Roadmap

• Store React state in URL Search Params.
• Next.js integration.
• Default values (remove default values from URL).
• Remove falsy values.
• Preserve initial keys - keys are preserved in search params, if they were initially set.
• Array values.
• Zod validation.
  • Coercing into typed values.
  • Zod default values.
  • Zod optional values.
• Type-safe state from default values or when validation schema is provided.
• More validation tools (yup, etc.).
• Svelte/SvelteKit
• Solid

Credits

This project is built and maintained by Antoni

If you need help building anything that has a frontend, check out Quassum

License

Apache 2.0 License

use-search-params-state's Issues

feat: Array values

Describe the feature you'd like to request

Developers should be able to store multiple values for a single key, without needing to handle array serialisation themselves.

Describe the solution you'd like to see

Developers should be allowed to use string[] as a value type.

Additional information

URLSearchParams API lets you have multiple values for the same key, by using .append and .getAll functions for setting / reading respectively.

feat: Key sorting

Describe the feature you'd like to request

Should be able to sort keys that are saved in the url.

Describe the solution you'd like to see

There should be an option available to enable/disable sorting, with the default set to true, to automatically sort keys by default.

Additional information

No response