https://github.com/jokull/next-use-search-params

Type-safe search param handling for Next.js using zod.
https://github.com/jokull/next-use-search-params

Last synced: 13 days ago
JSON representation

Type-safe search param handling for Next.js using zod.

• Host: GitHub
• URL: https://github.com/jokull/next-use-search-params
• Owner: jokull
• Created: 2022-12-16T12:56:21.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2022-12-16T12:58:38.000Z (about 2 years ago)
• Last Synced: 2024-12-17T03:58:31.559Z (15 days ago)
• Language: TypeScript
• Homepage:
• Size: 65.4 KB
• Stars: 7
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# `useSearchParams()`

Type-safe search param handling for [Next.js](https://nextjs.org/) using zod.

## Install

```

npm install @jokullsolberg/next-use-search-params

```

## Example usage

```tsx

function Signup() {

  const [{ foo, bar, date }, setSearchParam] = useSearchParams({

    foo: z.string().default(''),

    bar: z.coerce.number().default(1),

    date: z.coerce.date().default(new Date()),

    screen: z.enum(['login', 'signup']).default('login'),

  });

  return (

    


      
Signup

       setSearchParam('foo', event.target.value)}

      />

       setSearchParam('bar', event.target.valueAsNumber)}

      />

      

          setSearchParam('date', event.target.valueAsDate ?? new Date())

        }

      />

      
{date.toISOString()}

       setSearchParam('screen', 'login')}>Login

    

  );

}


export default function Page() {

  const [{ screen }, setSearchParam] = useSearchParams({

    screen: z.enum(['login', 'signup']).default('login'),

  });

  return screen === 'login' ? (

    


      Login{' '}

       setSearchParam('screen', 'signup')}>Signup

    

  ) : (

    

  );

}

```


These components can affect the state by simply routing with `Link` or `router.push` — instead of

prop drilling `onSuccess` handlers into each component to orchestrate transitions.

Default values are required. Let me know if this is annoying.

## Benefits

Keeping state in search params is user friendly and has DX benefits

- State lives in search params, like a poor man's global `Context`.

- Browser back button works and updates state.

- zod is a powerful tool to validate data and type values.

- Default values are not displayed in the URL to keep it clean.

- Because state is global multiple components can bind simultaneously to the same param. This helps

  avoid prop drilling `onSuccess` handlers.

## FAQ

- **URLSearchParams support multiple values for the same key, does this tool too?** No.

- **Values of URLSearchParams are always strings, do I need to zod `preprocess` them?** No. Use the

  new `z.coerce` stuff instead. Internally we call `JSON.stringify` or `Date.toISOString()` to

  marshal back to URL.

- **What happens to unexpected or illegal values?** They are ignored and default values are used

  instead.

## Next.js 13 and SSR

This does not work inside `/app` client components since router is imported from `next/navigation`

now.

SSR will reach for the default values.