docs: document useAtomSelector hook for v2

Omnistac · bowheart · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025
commit 09f51371632dcfec98b8958327212b11282745c8
diff --git a/docs/docs/v2/api/hooks/useAtomInstance.mdx b/docs/docs/v2/api/hooks/useAtomInstance.mdx
@@ -17,7 +17,7 @@ Unlike [`useAtomValue`](/not-done?path=./useAtomValue.mdx) and [`useAtomState`](
 
 Some primary uses for this hook are when:
 
-- you only need to acces the atom to update its state, e.g. via [`.set`](../classes/AtomInstance.mdx#set), [`.mutate`](../classes/AtomInstance.mdx#mutate), or by using any custom [`.exports`](../classes/AtomInstance.mdx#exports).
+- you only need to access the atom to update its state, e.g. via [`.set`](../classes/AtomInstance.mdx#set), [`.mutate`](../classes/AtomInstance.mdx#mutate), or by using any custom [`.exports`](../classes/AtomInstance.mdx#exports).
 - you need to provide an atom to a component subtree via [`<AtomProvider>`](../components/AtomProvider.mdx).
 
 This hook has an equivalent injector: [`injectAtomInstance`](/not-done?path=../injectors/injectAtomInstance.mdx), though it's more common to use [`ecosystem.getNode`](../classes/Ecosystem.mdx#getnode) to create/retrieve atom instances inside other atoms.
@@ -153,7 +153,7 @@ function ExampleComponent() {
 
   </Item>
   <Item name="Returns">
-    The [atom instance](../classes/AtomInstance.mdx) object.
+    The resolved [atom instance](../classes/AtomInstance.mdx) for the passed template + params combo.
 
   </Item>
 </Legend>

diff --git a/docs/docs/v2/api/hooks/useAtomSelector.mdx b/docs/docs/v2/api/hooks/useAtomSelector.mdx
@@ -0,0 +1,71 @@
+---
+id: useAtomSelector
+title: useAtomSelector
+---
+
+import { Legend, Item, Link, Tabs, Ts, tab1, tab2 } from '@site/src/all'
+
+:::warning Deprecated
+As of v2, this hook is deprecated. Use [`useAtomValue`](/not-done?path=./useAtomValue.mdx) instead - it now handles all Zedux's reactive primitives, making refactoring between them easier.
+:::
+
+```ts
+import { useAtomSelector } from '@zedux/react'
+```
+
+A React hook that retrieves a cached [atom selector](/not-done?path=../types/SelectorTemplate.mdx) value. If the selector is not cached yet, `useAtomSelector` caches it by creating a new [selector instance](../classes/SelectorInstance.mdx) and returns the value.
+
+If the selector takes params, TypeScript will enforce that those are passed correctly.
+
+## Examples
+
+```tsx live ecosystemId=useAtomSelector/example resultVar=Count version=2
+const countAtom = atom('count', 0)
+const getDoubledCount = ({ get }) => get(countAtom) * 2
+
+function Count() {
+  const [count, setCount] = useAtomState(countAtom)
+  const doubledCount = useAtomSelector(getDoubledCount)
+
+  return (
+    <div>
+      <div>Count: {count}</div>
+      <div>Doubled count: {doubledCount}</div>
+      <button onClick={() => setCount(count + 1)}>+</button>
+      <button onClick={() => setCount(count - 1)}>-</button>
+    </div>
+  )
+}
+```
+
+## Signature
+
+<Tabs>
+  {tab1(`useAtomSelector = (template, params?) => selectedValue`)}
+  {tab2(
+    `declare const useAtomSelector: <S extends Selectable>(template: S, ...args: ParamsOf<S>) => StateOf<S>`
+  )}
+</Tabs>
+
+<Legend>
+  <Item name="template">
+    Required. Either a [selector function](/not-done?path=../types/SelectorTemplate.mdx#atomselector) or an [atom selector config object](/not-done?path=../types/SelectorTemplate.mdx#atomselectorconfig).
+
+    See [the `SelectorTemplate` type](/not-done?path=../types/SelectorTemplate.mdx) for more details.
+
+  </Item>
+  <Item name="params">
+    The selector's [params](../classes/SelectorInstance.mdx#params) spread into the rest of the arguments to `useAtomSelector`. Note that this is different from [`useAtomValue`](/not-done?path=./useAtomValue.mdx) (and all Zedux APIs in v2) where params are passed via the second argument as an array.
+
+    Required if the selector has required parameters.
+
+  </Item>
+  <Item name="Returns">
+    The cached value of the resolved [selector instance](../classes/SelectorInstance.mdx) for the passed [selector template](/not-done?path=../types/SelectorTemplate.mdx) + [params](../classes/SelectorInstance.mdx#params) combo.
+  </Item> 
+</Legend>
+
+## See Also
+
+- [The `useAtomValue` hook](/not-done?path=./useAtomValue.mdx)
+- [The Selectors walkthrough](../../../walkthrough/selectors.mdx)
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -199,6 +199,7 @@ module.exports = {
           items: [
             'v2/api/hooks/useAtomContext',
             'v2/api/hooks/useAtomInstance',
+            'v2/api/hooks/useAtomSelector',
             'v2/api/hooks/useEcosystem',
           ],
         },