From bce191d7d50ce75e9d261efe9abe7cb79fd7beb2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Dudak?= <michal@mui.com>
Date: Fri, 1 Sep 2023 08:37:46 +0200
Subject: [PATCH] [docs][Autocomplete] Require referentially stable value
 (#38734)

---
 .../components/autocomplete/autocomplete.md   | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/data/material/components/autocomplete/autocomplete.md b/docs/data/material/components/autocomplete/autocomplete.md
index 9ff7e6a9447ee9..55086bdf720aec 100644
--- a/docs/data/material/components/autocomplete/autocomplete.md
+++ b/docs/data/material/components/autocomplete/autocomplete.md
@@ -81,6 +81,27 @@ Learn more about controlled and uncontrolled components in the [React documentat
 
 {{"demo": "ControllableStates.js"}}
 
+:::warning
+
+If you control the `value`, make sure it's referentially stable between renders.
+In other words, the reference to the value shouldn't change if the value itself doesn't change.
+
+```tsx
+// ⚠️ BAD
+return <Autocomplete multiple value={allValues.filter((v) => v.selected)} />;
+
+// 👍 GOOD
+const selectedValues = React.useMemo(
+  () => allValues.filter((v) => v.selected),
+  [allValues],
+);
+return <Autocomplete multiple value={selectedValues} />;
+```
+
+In the first example, `allValues.filter` is called and returns **a new array** every render.
+The fix includes memoizing the value, so it changes only when needed.
+:::
+
 ## Free solo
 
 Set `freeSolo` to true so the textbox can contain any arbitrary value.