[Suggestion]: Adding an Explanation Text to Optimizing Re-renders in useContext Section

Summary

Add an explanation text to prevent missunderstanding of usage useContext with useMemo.

Page

https://react.dev/reference/react/useContext#optimizing-re-renders-when-passing-objects-and-functions

Details

I think it would be helpful to have an explanation text in the section below.

Optimizing re-renders when passing objects and functions
https://react.dev/reference/react/useContext#optimizing-re-renders-when-passing-objects-and-functions

import { useCallback, useMemo } from 'react';

function MyApp() {
  const [currentUser, setCurrentUser] = useState(null);

  const login = useCallback((response) => {
    storeCredentials(response.credentials);
    setCurrentUser(response.user);
  }, []);

  const contextValue = useMemo(() => ({
    currentUser,
    login
  }), [currentUser, login]);

  return (
    <AuthContext.Provider value={contextValue}>
      <Page />
    </AuthContext.Provider>
  );
}

In this section, the currentUser type is not certain. But, the user type is an object in general usages. So, when using useMemo with an object dependency, it relies on object reference changes rather than the equality of object values. If the object reference remains the same, even if the internal values are the same, useMemo may not provide the expected optimization.

Even though the currentUser object has the same values, the reference remains the same, and useMemo will recalculate the memoized value because it's based on the change in reference.

Note: Avoid using complex data types, especially objects, directly in the dependency array of useMemo.
When using objects, JavaScript relies on object reference changes, not values.
If the object reference remains the same, useMemo might not optimize as expected.
To ensure proper memoization, consider using primitive values or ensuring object immutability.
For example, prefer setCurrentUser({ ...currentUser, updatedProperty: "newValue" }) over modifying the existing object directly using login function.

Maybe adding text like above would be helpful.

Start at the useContext reference page's “Optimizing re-renders when passing objects and functions” section and review the surrounding explanation of useMemo dependencies. Verify the proposed clarification against JavaScript object-reference behavior, then update the documentation so the example's memoization behavior and immutable updates are unambiguous.