From 998a319518e71f1b41ff0ea7f767863c19d9aa83 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 30 May 2024 18:59:45 +0200
Subject: [PATCH] [system][docs] Add "dynamic values" section to sx prop page
 (#42239)

---
 .../the-sx-prop/DynamicValues.js              | 38 +++++++++++++++++++
 .../the-sx-prop/DynamicValues.tsx             | 38 +++++++++++++++++++
 .../the-sx-prop/the-sx-prop.md                | 12 ++++++
 3 files changed, 88 insertions(+)
 create mode 100644 docs/data/system/getting-started/the-sx-prop/DynamicValues.js
 create mode 100644 docs/data/system/getting-started/the-sx-prop/DynamicValues.tsx

diff --git a/docs/data/system/getting-started/the-sx-prop/DynamicValues.js b/docs/data/system/getting-started/the-sx-prop/DynamicValues.js
new file mode 100644
index 00000000000000..fcbf42eea415da
--- /dev/null
+++ b/docs/data/system/getting-started/the-sx-prop/DynamicValues.js
@@ -0,0 +1,38 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+
+export default function DynamicValues() {
+  const [color, setColor] = React.useState('#007fff');
+
+  return (
+    <Stack spacing={1} alignItems="center">
+      <Typography
+        component="label"
+        variant="body2"
+        sx={{ display: 'inline-flex', alignItems: 'center', gap: 1 }}
+      >
+        Pick a color to see a live preview
+        <input
+          type="color"
+          value={color}
+          onChange={(event) => setColor(event.target.value)}
+        />
+      </Typography>
+      <Box
+        component="div"
+        sx={{
+          display: 'flex',
+          justifyContent: 'center',
+          alignItems: 'center',
+          width: 75,
+          height: 75,
+          borderRadius: 2,
+          backgroundColor: 'var(--bg)',
+        }}
+        style={{ '--bg': color }}
+      />
+    </Stack>
+  );
+}
diff --git a/docs/data/system/getting-started/the-sx-prop/DynamicValues.tsx b/docs/data/system/getting-started/the-sx-prop/DynamicValues.tsx
new file mode 100644
index 00000000000000..58021dcdd096eb
--- /dev/null
+++ b/docs/data/system/getting-started/the-sx-prop/DynamicValues.tsx
@@ -0,0 +1,38 @@
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import Stack from '@mui/material/Stack';
+import Typography from '@mui/material/Typography';
+
+export default function DynamicValues() {
+  const [color, setColor] = React.useState('#007fff');
+
+  return (
+    <Stack spacing={1} alignItems="center">
+      <Typography
+        component="label"
+        variant="body2"
+        sx={{ display: 'inline-flex', alignItems: 'center', gap: 1 }}
+      >
+        Pick a color to see a live preview
+        <input
+          type="color"
+          value={color}
+          onChange={(event) => setColor(event.target.value)}
+        />
+      </Typography>
+      <Box
+        component="div"
+        sx={{
+          display: 'flex',
+          justifyContent: 'center',
+          alignItems: 'center',
+          width: 75,
+          height: 75,
+          borderRadius: 2,
+          backgroundColor: 'var(--bg)',
+        }}
+        style={{ '--bg': color } as React.CSSProperties}
+      />
+    </Stack>
+  );
+}
diff --git a/docs/data/system/getting-started/the-sx-prop/the-sx-prop.md b/docs/data/system/getting-started/the-sx-prop/the-sx-prop.md
index 35f66b1cdd2878..853f4e768711a6 100644
--- a/docs/data/system/getting-started/the-sx-prop/the-sx-prop.md
+++ b/docs/data/system/getting-started/the-sx-prop/the-sx-prop.md
@@ -292,6 +292,18 @@ If you want to receive the `sx` prop from a custom component and pass it down to
 
 {{"demo": "PassingSxProp.js", "bg": true, "defaultCodeOpen": true}}
 
+## Dynamic values
+
+For highly dynamic CSS values, we recommend using inline CSS variables instead of passing an object with varying values to the `sx` prop on each render.
+This approach avoids inserting unnecessary `style` tags into the DOM, which prevents potential performance issues when dealing with CSS properties that can hold a wide range of values that change frequently—for example, a color picker with live preview.
+
+:::info
+If you're having problems with your Content Security Policy while using inline styles with the `style` attribute, make sure you've enabled the [`style-src-attr` directive](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/style-src-attr).
+Visit the [Content Security Policy guide](/material-ui/guides/content-security-policy/) for configuration details.
+:::
+
+{{"demo": "DynamicValues.js", "bg": true}}
+
 ## TypeScript usage
 
 A frequent source of confusion with the `sx` prop is TypeScript's [type widening](https://mariusschulz.com/blog/literal-type-widening-in-typescript), which causes this example not to work as expected: