diff --git a/packages/docs/content/docs/options.mdx b/packages/docs/content/docs/options.mdx
index 8f64ce13..d6dae49e 100644
--- a/packages/docs/content/docs/options.mdx
+++ b/packages/docs/content/docs/options.mdx
@@ -79,7 +79,50 @@ For server-side renderable frameworks, you would pair `shallow: false{:ts}` with
 - In Next.js pages router: the `getServerSideProps` function
 - In Remix & React Router: a `loader` function
 
+### In React Router based frameworks
 
+While the `shallow: false` default behaviour is uncommon for Remix and React Router,
+where loaders are always supposed to run on URL changes, nuqs gives you control
+of this behaviour, by opting in to running loaders only if they do need to access
+the relevant search params.
+
+One caveat is that the stock `useSearchParams` hook from those frameworks doesn't
+reflect shallow-updated search params, so we provide you with one that does:
+
+```tsx
+import { useOptimisticSearchParams } from 'nuqs/adapters/remix' // or '…/react-router/v6' or '…/react-router/v7'
+
+function Component() {
+  // Note: this is read-only, but reactive to all URL changes
+  const searchParams = useOptimisticSearchParams()
+  return <div>{searchParams.get('foo')}</div>
+}
+```
+
+This concept of _"shallow routing"_ is done via updates to the browser's
+[History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API/Working_with_the_History_API).
+
+While the `useOptimisticSearchParams` and the adapter itself can handle shallow URL
+updates triggered from state updater functions, for them to react to URL changes
+triggered by explicit calls to the History API (either by first or third party code),
+you'd have to enable sync:
+
+```tsx
+// Export available in:
+//  'nuqs/adapters/remix'
+//  'nuqs/adapters/react-router/v6'
+//  'nuqs/adapters/react-router/v7'
+//  'nuqs/adapters/react'
+import { enableHistorySync } from 'nuqs/adapters/remix'
+
+// Somewhere top-level (like app/root.tsx)
+enableHistorySync()
+```
+
+Note that you may not need this if only using your framework's router.
+
+It is opt-in as it patches the History APIs, which can have side effects
+if third party code does it too.
 
 ## Scroll