feat: Allow passing transition options

Closes #209, #209.

README.md

@@ -144,6 +144,22 @@ const MultipleQueriesDemo = () => {
 
 _Note: support to synchronously update multiple related queries at the same time will come in a future update. See #277._
 
+## Transition Options
+
+By default Next.js will scroll to the top of the page when changing things in the URL.
+
+To prevent this, `router.push()` and `router.replace()` have a third optional
+parameter to control transitions, which can be passed on the state setter here:
+
+```ts
+const [name, setName] = useQueryState('name')
+
+setName('Foo', {
+  scroll: false,
+  shallow: true // Don't run getStaticProps / getServerSideProps / getInitialProps
+})
+```
+
 ## Caveats
 
 Because the Next.js router is not available in an SSR context, this

src/useQueryState.ts

@@ -1,3 +1,4 @@
+import type { Router } from 'next/router'
 import { useRouter } from 'next/router'
 import React from 'react'
 import { HistoryOptions, Serializers } from './defs'
@@ -10,9 +11,16 @@ export interface UseQueryStateOptions<T> extends Serializers<T> {
   defaultValue: T
 }
 
+// Next.js does not export the TransitionsOption interface,
+// but we can get it from where it's used:
+type TransitionOptions = Parameters<Router['push']>[2]
+
 export type UseQueryStateReturn<T> = [
   T,
-  (value: React.SetStateAction<T>) => Promise<boolean>
+  (
+    value: React.SetStateAction<T>,
+    transitionOptions?: TransitionOptions
+  ) => Promise<boolean>
 ]
 
 export type UseQueryStateOptionsWithDefault<T> = Pick<
@@ -126,7 +134,10 @@ export function useQueryState<T = string>(
   const value = React.useMemo(getValue, [router.query[key]])
 
   const update = React.useCallback(
-    (stateUpdater: React.SetStateAction<T | null>) => {
+    (
+      stateUpdater: React.SetStateAction<T | null>,
+      transitionOptions?: TransitionOptions
+    ) => {
       const isUpdaterFunction = (
         input: any
       ): input is (prevState: T | null) => T | null => {
@@ -166,7 +177,8 @@ export function useQueryState<T = string>(
           pathname: asPath,
           hash,
           search
-        }
+        },
+        transitionOptions
       )
     },
     [key, updateUrl]