doc: Add transitions docs

README.md

@@ -17,6 +17,7 @@ useQueryState hook for Next.js - Like React.useState, but stored in the URL quer
 - ⚡️ Built-in [parsers](#parsing) for common state types (integer, float, boolean, Date, and more)
 - ♊️ Related querystrings with [`useQueryStates`](#usequerystates)
 - 📡 [Shallow mode](#shallow) by default for URL query updates, opt-in to notify server components
+- ⌛️ **new:** Support for [`useTransition`](#transitions) to get loading states on server updates
 
 ## Installation
 
@@ -311,6 +312,36 @@ If multiple hooks set different throttle values on the same event loop tick,
 the highest value will be used. Also, values lower than 50ms will be ignored,
 to avoid rate-limiting issues. [Read more](https://francoisbest.com/posts/2023/storing-react-state-in-the-url-with-nextjs#batching--throttling).
 
+### Transitions
+
+When combined with `shallow: false`, you can use the `useTransition` hook to get
+loading states while the server is re-rendering server components with the
+updated URL.
+
+Pass in the `startTransition` function from `useTransition` to the options
+to enable this behaviour _(this will set `shallow: false` automatically for you)_:
+
+```tsx
+'use client'
+
+import React from 'react'
+import { useQueryState, parseAsString } from 'next-usequerystate'
+
+function ClientComponent({ data }) {
+  const [isLoading, startTransition] = React.useTransition()
+  const [query, setQuery] = useQueryState(
+    'query',
+    parseAsString().withOptions({ startTransition })
+  )
+
+  // Indicate loading state
+  if (isLoading) return <div>Loading...</div>
+
+  // Normal rendering with data
+  return <div>{/*...*/}</div>
+}
+```
+
 ## Configuring parsers, default value & options
 
 You can use a builder pattern to facilitate specifying all of those things: