docs: document useAtomContext hook for v2

Omnistac · bowheart · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025 · Jul 23, 2025
commit 2a4365c38efaf205a1a136412c6bcff0c0e98902
diff --git a/docs/docs/v2/api/classes/AtomInstance.mdx b/docs/docs/v2/api/classes/AtomInstance.mdx
@@ -104,7 +104,7 @@ function Parent() {
 }
 ```
 
-Consume provided instances with [`useAtomContext()`](/not-done?path=../hooks/useAtomContext)
+Consume provided instances with [`useAtomContext()`](../hooks/useAtomContext.mdx).
 
 ```ts
 import { useAtomContext } from '@zedux/react'

diff --git a/docs/docs/v2/api/components/AtomProvider.mdx b/docs/docs/v2/api/components/AtomProvider.mdx
@@ -11,7 +11,7 @@ import { AtomProvider } from '@zedux/react'
 
 A component that provides one or more [atom instances](../classes/AtomInstance) over React context.
 
-Use [`useAtomContext()`](/not-done?path=../hooks/useAtomContext) to consume the provided instance(s).
+Use [`useAtomContext()`](../hooks/useAtomContext.mdx) to consume the provided instance(s).
 
 ## Example
 
@@ -159,5 +159,5 @@ AtomProvider accepts **either** an `instance` prop to provide a single atom inst
 ## See Also
 
 - [The React Context walkthrough](../../../walkthrough/react-context.mdx)
-- [The `useAtomContext` hook](/not-done?path=../hooks/useAtomContext)
+- [The `useAtomContext` hook](../hooks/useAtomContext.mdx)
 - [The `useAtomInstance` hook](/not-done?path=../hooks/useAtomInstance)
diff --git a/docs/docs/v2/api/hooks/useAtomContext.mdx b/docs/docs/v2/api/hooks/useAtomContext.mdx
@@ -0,0 +1,117 @@
+---
+id: useAtomContext
+title: useAtomContext
+---
+
+import { Legend, Item, Link, Tabs, Ts, tab1, tab2 } from '@site/src/all'
+
+```ts
+import { useAtomContext } from '@zedux/react'
+```
+
+A React hook that retrieves an [atom instance](../classes/AtomInstance.mdx) provided over React context via an [`<AtomProvider>`](../components/AtomProvider.mdx).
+
+This hook only returns the atom instance itself. To make the consuming component rerender when the provided atom updates, pass the returned atom instance to [`useAtomValue`](/not-done?path=./useAtomValue.mdx) or [`useAtomState`](/not-done?path=./useAtomState.mdx).
+
+## Example
+
+```tsx live ecosystemId=useAtomContext/example resultVar=App version=2
+const themeAtom = atom('theme', (_id: number) => 'light')
+
+function ThemedComponent() {
+  const themeInstance = useAtomContext(themeAtom)
+  const theme = useAtomValue(themeInstance)
+
+  return (
+    <div
+      style={{
+        background: theme === 'light' ? 'white' : 'black',
+        color: theme === 'light' ? 'black' : 'white',
+        padding: '20px',
+      }}
+    >
+      Current theme: {theme}
+    </div>
+  )
+}
+
+function ThemeToggle() {
+  const themeInstance = useAtomContext(themeAtom)
+  const [theme, setTheme] = useAtomState(themeInstance)
+
+  return (
+    <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+      Toggle Theme
+    </button>
+  )
+}
+
+function App() {
+  const instance1 = useAtomInstance(themeAtom, [1])
+  const instance2 = useAtomInstance(themeAtom, [2])
+
+  return (
+    <>
+      <AtomProvider instance={instance1}>
+        <div>
+          <ThemedComponent />
+          <ThemeToggle />
+        </div>
+      </AtomProvider>
+      <AtomProvider instance={instance2}>
+        <div>
+          <ThemedComponent />
+          <ThemeToggle />
+        </div>
+      </AtomProvider>
+    </>
+  )
+}
+```
+
+## Signature
+
+<Tabs>
+  {tab1(`useAtomContext = (template, defaultParams?) => atomInstance
+  // or
+  useAtomContext = (template, throwIfNotProvided?) => providedAtomInstance`)}
+  {tab2(`declare const useAtomContext: {
+    <A extends AnyAtomTemplate>(template: A): NodeOf<A> | undefined;
+    <A extends AnyAtomTemplate>(template: A, defaultParams: ParamsOf<A>): NodeOf<A>;
+    <A extends AnyAtomTemplate>(template: A, throwIfNotProvided: boolean): NodeOf<A>;
+  }`)}
+</Tabs>
+
+<Legend>
+  <Item name="template">
+    Required. The atom template that identifies which atom instance to retrieve from context.
+
+  </Item>
+  <Item name="defaultParams">
+    Optional. An array.
+
+    If no atom instance was provided for the given template, Zedux will use these params to create and return a new atom instance.
+
+  </Item>
+  <Item name="throwIfNotProvided">
+    Optional. A boolean. Whether to throw an error if no atom instance was provided.
+
+    This is the recommended overload in almost all situations:
+
+    ```tsx
+    const providedInstance = useAtomContext(myTemplate, true)
+    ```
+
+  </Item>
+  <Item name="Returns">
+    The provided [atom instance](../classes/AtomInstance.mdx), or the newly-created atom instance if no atom instance was provided and `defaultParams` were passed.
+
+  </Item>
+</Legend>
+
+## See Also
+
+- [The `AtomProvider` component](../components/AtomProvider.mdx)
+- [The `useAtomValue` hook](/not-done?path=./useAtomValue.mdx)
+- [The React Context walkthrough](../../../walkthrough/react-context.mdx)
+- [The `AtomInstance` class](../classes/AtomInstance.mdx)
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -196,7 +196,7 @@ module.exports = {
         {
           type: 'category',
           label: 'Hooks',
-          items: ['v2/api/hooks/useEcosystem'],
+          items: ['v2/api/hooks/useAtomContext', 'v2/api/hooks/useEcosystem'],
         },
         {
           type: 'category',
-Original file line number
+Diff line change
@@ Expand Up / @@ -104,7 +104,7 @@ function Parent() { @@
     }
     ```
-    Consume provided instances with [`useAtomContext()`](/not-done?path=../hooks/useAtomContext)
+    Consume provided instances with [`useAtomContext()`](../hooks/useAtomContext.mdx).
     ```ts
     import { useAtomContext } from '@zedux/react'
@@ Expand Down @@