From 30ba7076f3275b95ff2a622d979ba89857346867 Mon Sep 17 00:00:00 2001 From: PUNITHKUMAR R Date: Fri, 28 Nov 2025 09:45:52 +0530 Subject: [PATCH] Docs: clarify state mutation and add example Explain why directly mutating objects in state is bad and add a short code example showing immutable updates. Fixes readability for beginners. --- src/content/learn/state-as-a-snapshot.md | 2 +- src/content/learn/updating-objects-in-state.md | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/src/content/learn/state-as-a-snapshot.md b/src/content/learn/state-as-a-snapshot.md index df4eddbd677..a1378717f64 100644 --- a/src/content/learn/state-as-a-snapshot.md +++ b/src/content/learn/state-as-a-snapshot.md @@ -305,7 +305,7 @@ label, textarea { margin-bottom: 10px; display: block; } -**React keeps the state values "fixed" within one render's event handlers.** You don't need to worry whether the state has changed while the code is running. +**React keeps the state value “fixed” within one render, meaning it won’t update until the next render cycle.** You don't need to worry whether the state has changed while the code is running. But what if you wanted to read the latest state before a re-render? You'll want to use a [state updater function](/learn/queueing-a-series-of-state-updates), covered on the next page! diff --git a/src/content/learn/updating-objects-in-state.md b/src/content/learn/updating-objects-in-state.md index ca658514507..4ac15a26dbd 100644 --- a/src/content/learn/updating-objects-in-state.md +++ b/src/content/learn/updating-objects-in-state.md @@ -4,7 +4,7 @@ title: Updating Objects in State -State can hold any kind of JavaScript value, including objects. But you shouldn't change objects that you hold in the React state directly. Instead, when you want to update an object, you need to create a new one (or make a copy of an existing one), and then set the state to use that copy. +State can hold any kind of JavaScript value, including objects. But you shouldn't change objects that you hold in the React state directly.This is because React does not detect direct mutations, so the UI will not update. Instead, when you want to update an object, you need to create a new one (or make a copy of an existing one), and then set the state to use that copy. @@ -45,7 +45,8 @@ Technically, it is possible to change the contents of _the object itself_. **Thi position.x = 5; ``` -However, although objects in React state are technically mutable, you should treat them **as if** they were immutable--like numbers, booleans, and strings. Instead of mutating them, you should always replace them. +However, although objects in React state are technically mutable, you should treat them **as if** they were immutable--like numbers, booleans, and strings.This helps React correctly detect changes and update the UI as expected. +Instead of mutating them, you should always replace them. ## Treat state as read-only {/*treat-state-as-read-only*/}