Include guidance around dynamic values

mui · May 14, 2024 · 45cba1c · 45cba1c
1 parent 40492b7
commit 45cba1c
Show file tree

Hide file tree

Showing 3 changed files with 74 additions and 0 deletions.
diff --git a/docs/data/system/getting-started/the-sx-prop/DynamicValues.js b/docs/data/system/getting-started/the-sx-prop/DynamicValues.js
@@ -0,0 +1,34 @@
+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" onChange={(event) => setColor(event.target.value)} />
+      </Typography>
+      <Box
+        component="div"
+        sx={{
+          display: 'flex',
+          justifyContent: 'center',
+          alignItems: 'center',
+          width: 100,
+          height: 100,
+          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
@@ -0,0 +1,34 @@
+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" onChange={(event) => setColor(event.target.value)} />
+      </Typography>
+      <Box
+        component="div"
+        sx={{
+          display: 'flex',
+          justifyContent: 'center',
+          alignItems: 'center',
+          width: 100,
+          height: 100,
+          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
@@ -292,6 +292,12 @@ 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, preventing 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.
+
+{{"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: