docs: add how to update values inside arrays (#1193)

* docs: add how to update values inside arrays

* docs: simplify array update guide with "Why this works"

* docs: clarify usage of proxy object in array update example

Author: pooya-badiee

docs/how-tos/how-to-update-values-inside-arrays.mdx

@@ -0,0 +1,92 @@
+---
+title: 'How to update values inside arrays'
+---
+
+# How to update values inside arrays
+
+Avoid unnecessary re-renders when updating values inside arrays.
+
+## Basic approach (triggers full list re-render)
+
+In this example, iterating over the snapshot items causes the entire list to re-render whenever any item changes.
+
+```js
+import { proxy, useSnapshot } from 'valtio'
+
+const state = proxy({
+  title: 'My Counter list',
+  items: [
+    { id: 1, count: 0 },
+    { id: 2, count: 0 },
+  ],
+})
+
+function Counter({ item }) {
+  return (
+    <div>
+      <span>{item.count}</span>
+      <button onClick={() => item.count++}>+1</button>
+    </div>
+  )
+}
+
+function CounterList() {
+  const snap = useSnapshot(state)
+  return (
+    <div>
+      <h1>{snap.title}</h1>
+      {/* Touching snap.items causes the whole list to re-render when any child updates */}
+      {snap.items.map((item) => (
+        <Counter key={item.id} item={item} />
+      ))}
+    </div>
+  )
+}
+```
+
+## Optimized approach (only changed items re-render)
+
+Pass the proxy item (not snapshot) to children and let each child subscribe to its own item.
+Do not access the entire array from the snapshot in the parent component.
+
+```js
+import { proxy, useSnapshot } from 'valtio'
+
+const state = proxy({
+  title: 'My Counter list',
+  items: [
+    { id: 1, count: 0 },
+    { id: 2, count: 0 },
+  ],
+})
+
+function Counter({ item }) {
+  const snap = useSnapshot(item)
+  return (
+    <div>
+      <span>{snap.count}</span>
+      <button onClick={() => item.count++}>+1</button>
+    </div>
+  )
+}
+
+function CounterList() {
+  const snap = useSnapshot(state)
+  return (
+    <div>
+      <h1>{snap.title}</h1>
+      {/* Only the length is accessed from snap, so only updated children re-render */}
+      {Array.from({ length: snap.items.length }, (_, index) => (
+        {/* Note that we are passing the proxy object (state) instead of the snapshot (snap) to the child component */}
+        <Counter key={state.items[index].id} item={state.items[index]} />
+      ))}
+    </div>
+  )
+}
+```
+
+## Why this works
+
+Because the proxy (in this case: `state.items[index]`) is a proxy object instead of a snapshot object, accessing it does not track usage. This prevents the parent component from "subscribing" to the item's internal changes, effectively isolating updates to the child component.
+
+When you call `snap.items.map()`, you access every item in the array, causing Valtio to re-render whenever _any_ item changes. By only accessing `snap.items.length`, Valtio only re-renders when the array length changes. Using `Array.from({ length: n }, (_, i) => ...)` creates an array by index without touching snapshot items, letting you access the proxy directly.

website/lib/mdx.ts

@@ -270,6 +270,7 @@ export function getDocsNav(): NavigationTree {
       pages['how-to-avoid-rerenders-manually'],
       pages['how-to-easily-access-the-state-from-anywhere-in-the-application'],
       pages['how-to-organize-actions'],
+      pages['how-to-update-values-inside-arrays'],
       pages['how-to-persist-states'],
       pages['how-to-reset-state'],
       pages['how-to-split-and-compose-states'],