[Suggestion]: Documentation states mutation is "not recommended" when it fundamentally doesn't work, misleading beginners about how React state functions

[sam77777777777]

Summary

The React documentation states that mutating state is "not recommended" and that developers can "get away with it," when in fact mutating state doesn't trigger re-renders at all. This misleads beginners into thinking mutation is a working anti-pattern rather than fundamentally broken code that prevents React from updating components.

Page

https://react.dev/learn/updating-objects-in-state

Details

Multiple sections in the React documentation misleadingly describe state mutation as "not recommended" or something you can "get away with," when the fundamental issue is that mutating state doesn't trigger re renders. This appears in at least:

The tic tac toe tutorial's "Why immutability is important" section
The last "Deep Dive" in the "Updating Objects in State" page in the Adding Interactivity section

Both sections list various reasons why mutation is discouraged (debugging, optimizations, features, etc.) but bury or omit the primary issue: if you mutate state, React won't re render your component because it can't detect the change.
The "Updating Objects in State" page is particularly problematic as it says:

"In practice, you can often 'get away' with mutating state in React"

My experience as a beginner:
This kind of language is incredibly confusing when learning React. React detects state changes by checking if the reference to the state has changed. When you mutate an object or array, you're modifying the same reference, so React doesn't know anything changed and doesn't re-render. Yet the official documentation makes it sound like mutation is just a bad practice that technically functions. When I read "not recommended" and "you can get away with it," I thought it was like using var instead of const, discouraged but functional most of the time.
The documentation's phrasing suggests there are scenarios where mutation works, but React fundamentally requires a new reference to detect changes. Mutation will not trigger a re-render.

Why this matters:
• React.dev is the official resource for learning React
• These are fundamental concepts that beginners encounter early
• This framing suggests mutation is a working anti-pattern rather than broken code
• Beginners won't understand that immutable updates are required for React to function, not just a best practice

Suggested improvement:
All sections discussing state mutation should lead with something like this:

"Mutating state directly doesn't trigger re-renders. When you mutate an object or array in place, React cannot detect the change because the reference remains the same. Your component will not re-render update."

Then follow with the additional benefits of immutability. Remove phrases like "get away with" that suggest mutation sometimes works. It only appears to work when other factors trigger re-renders, which should be made more clear.

Scope:
This language should be audited across all documentation pages that discuss state updates to ensure consistent, accurate messaging about why immutability is required, not just recommended.