From 21326503cfeaca7689ac90c40b2e627ece5ed1a7 Mon Sep 17 00:00:00 2001
From: David Maskasky <dmaskasky@gmail.com>
Date: Sun, 8 Oct 2023 22:44:00 -0700
Subject: [PATCH] docs(jotai-valtio): add  API section to README (#2163)

Introduce a new section in the  documentation
to describe the functionality, use-cases, and examples
for the new  API in the jotai-valtio integration library.

Co-authored-by: David Maskasky <dmaskasky@otter.ai>
---
 docs/integrations/valtio.mdx | 48 ++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/docs/integrations/valtio.mdx b/docs/integrations/valtio.mdx
index 67f81fc27e..31dc927fe5 100644
--- a/docs/integrations/valtio.mdx
+++ b/docs/integrations/valtio.mdx
@@ -70,3 +70,51 @@ atomWithProxy(proxyObject, { sync: true })
 ### Examples
 
 <CodeSandbox id="ew98ll" />
+
+## mutableAtom
+
+`mutableAtom` wraps a value in a self-aware Valtio proxy. You can make changes to it in the same way you would to a normal js-object.
+
+Count value is stored under the `value` property.
+
+```jsx
+const countProxyAtom = mutableAtom(0)
+
+function IncrementButton() {
+  const countProxy = useAtomValue(countProxyAtom)
+  return <button onClick={() => countProxy.value++}>+</button>
+}
+```
+
+### Parameters
+
+```js
+mutableAtom(value, options?)
+```
+
+**value** (required): the value to proxy.
+
+**options.proxyFn** (optional): allows customization with `proxyFn` for custom proxy functions. Can be `proxy` (default) or a custom function.
+
+### Examples
+
+<CodeSandbox id="f84sk5" />
+
+### Caution on Mutating Proxies
+
+Be careful to not mutate the proxy directly in the atom's read function or during render. Doing so could cause an infinite render loop.
+
+```ts
+const countProxyAtom = mutableAtom(0)
+
+atom(
+  (get) => {
+    const countProxy = get(countProxyAtom)
+    countProxy.value++ // This will cause an infinite loop
+  },
+  (get, set) => {
+    const countProxy = get(countProxyAtom)
+    countProxy.value++ // This is fine
+  }
+)
+```