The sx prop
The sx prop is a shortcut for defining custom styles that has access to the theme.
The sx
prop lets you work with a superset of CSS that packages all of the style functions exposed in @mui/system
.
You can specify any valid CSS using this prop, as well as many theme-aware properties that are unique to MUI System.
Basic example
The following demo illustrates how to work with the sx
prop.
Note that not all of the values are valid CSS properties—that's because the sx
keys are mapped to specific properties of the theme.
The rest of this document explores this concept in more detail.
Theme-aware properties
Borders
The border
property can only receive a number as a value.
It creates a solid black border using the number to define the width in pixels:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">border</span><span class="token operator">:</span> <span class="token number">1</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to border: '1px solid black'</span>
The borderColor
property can receive a string, which represents the path in theme.palette
:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">borderColor</span><span class="token operator">:</span> <span class="token string">'primary.main'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to borderColor: theme => theme.palette.primary.main</span>
The borderRadius
property multiplies the value it receives by the theme.shape.borderRadius
value (the default for this value is 4px
).
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">borderRadius</span><span class="token operator">:</span> <span class="token number">2</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to borderRadius: theme => 2 * theme.shape.borderRadius</span>
Read more on the Borders page.
Display
The displayPrint
property allows you to specify a CSS display
value that will only be applied when printing:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">displayPrint</span><span class="token operator">:</span> <span class="token string">'none'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span> <span class="token comment">// equivalent to '@media print': { display: 'none' }</span>
Read more on the Display page.
Grid
The CSS Grid properties gap
, rowGap
and columnGap
multiply the values they receive by the theme.spacing
value (the default for the value is 8px
).
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">gap</span><span class="token operator">:</span> <span class="token number">2</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to gap: theme => theme.spacing(2)</span>
Read more on the Grid page.
Palette
The color
and backgroundColor
properties can receive a string, which represents the path in theme.palette
:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">color</span><span class="token operator">:</span> <span class="token string">'primary.main'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to color: theme => theme.palette.primary.main</span>
The backgroundColor
property is also available through its alias bgcolor
:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">bgcolor</span><span class="token operator">:</span> <span class="token string">'primary.main'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to backgroundColor: theme => theme.palette.primary.main</span>
Read more on the Palette page.
Positions
The zIndex
property maps its value to the theme.zIndex
value:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">zIndex</span><span class="token operator">:</span> <span class="token string">'tooltip'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to zIndex: theme => theme.zIndex.tooltip</span>
Read more on the Positions page.
Shadows
The boxShadow
property maps its value to the theme.shadows
value:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">boxShadow</span><span class="token operator">:</span> <span class="token number">1</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to boxShadow: theme => theme.shadows[1]</span>
Read more on the Shadows page.
Sizing
The sizing properties width
, height
, minHeight
, maxHeight
, minWidth
, and maxWidth
use the following custom transform function for the value:
<span class="token keyword">function</span> <span class="token function">transform</span><span class="token punctuation">(</span><span class="token parameter">value</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">return</span> value <span class="token operator"><=</span> <span class="token number">1</span> <span class="token operator">&&</span> value <span class="token operator">!==</span> <span class="token number">0</span> <span class="token operator">?</span> <span class="token template-string"><span class="token template-punctuation string">`</span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>value <span class="token operator">*</span> <span class="token number">100</span><span class="token interpolation-punctuation punctuation">}</span></span><span class="token string">%</span><span class="token template-punctuation string">`</span></span> <span class="token operator">:</span> value<span class="token punctuation">;</span>
<span class="token punctuation">}</span>
If the value is between [0, 1], it's converted to a percentage. Otherwise, it is directly set on the CSS property:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">width</span><span class="token operator">:</span> <span class="token number">1</span><span class="token operator">/</span><span class="token number">2</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span> <span class="token comment">// equivalent to width: '50%'</span>
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">width</span><span class="token operator">:</span> <span class="token number">20</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span> <span class="token comment">// equivalent to width: '20px'</span>
Read more on the Sizing page.
Spacing
The spacing properties margin
, padding
, and the corresponding longhand properties multiply the values they receive by the theme.spacing
value (the default for the value is 8px
):
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">margin</span><span class="token operator">:</span> <span class="token number">2</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to margin: theme => theme.spacing(2)</span>
The following aliases are available for the spacing properties:
Prop | CSS property |
---|---|
m |
margin |
mt |
margin-top |
mr |
margin-right |
mb |
margin-bottom |
ml |
margin-left |
mx |
margin-left , margin-right |
my |
margin-top , margin-bottom |
p |
padding |
pt |
padding-top |
pr |
padding-right |
pb |
padding-bottom |
pl |
padding-left |
px |
padding-left , padding-right |
py |
padding-top , padding-bottom |
Read more on the Spacing page.
Typography
The fontFamily
, fontSize
, fontStyle
, fontWeight
properties map their value to the theme.typography
value:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">fontWeight</span><span class="token operator">:</span> <span class="token string">'fontWeightLight'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to fontWeight: theme.typography.fontWeightLight</span>
The same can be achieved by omitting the CSS property prefix fontWeight
:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">fontWeight</span><span class="token operator">:</span> <span class="token string">'light'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to fontWeight: theme.typography.fontWeightLight</span>
There is an additional typography
prop available, which sets all values defined in the specific theme.typography
variant:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token literal-property property">typography</span><span class="token operator">:</span> <span class="token string">'body1'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
<span class="token comment">// equivalent to { ...theme.typography.body1 }</span>
Read more on the Typography page.
Responsive values
All properties associated with the sx
prop also support responsive values for specific breakpoints.
Read more on the Usage page—Responsive values.
Callback values
Each property in the sx
prop can receive a function callback as a value.
This is useful when you want to use the theme
for calculating a value:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> <span class="token function-variable function">height</span><span class="token operator">:</span> <span class="token punctuation">(</span><span class="token parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> theme<span class="token punctuation">.</span><span class="token function">spacing</span><span class="token punctuation">(</span><span class="token number">10</span><span class="token punctuation">)</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span> <span class="token punctuation">/></span></span>
The sx
prop can also receive a callback when you need to get theme values that are objects:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span>
<span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">(</span><span class="token parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
<span class="token operator">...</span>theme<span class="token punctuation">.</span>typography<span class="token punctuation">.</span>body<span class="token punctuation">,</span>
<span class="token literal-property property">color</span><span class="token operator">:</span> theme<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>primary<span class="token punctuation">.</span>main<span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">}</span></span>
<span class="token punctuation">/></span></span>
Array values
Array types are useful when you want to partially override some styles in the former index:
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span>
<span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span>
<span class="token punctuation">{</span>
<span class="token string-property property">'&:hover'</span><span class="token operator">:</span> <span class="token punctuation">{</span>
<span class="token literal-property property">color</span><span class="token operator">:</span> <span class="token string">'red'</span><span class="token punctuation">,</span>
<span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'white'</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
foo <span class="token operator">&&</span> <span class="token punctuation">{</span>
<span class="token string-property property">'&:hover'</span><span class="token operator">:</span> <span class="token punctuation">{</span> <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'grey'</span> <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
bar <span class="token operator">&&</span> <span class="token punctuation">{</span>
<span class="token string-property property">'&:hover'</span><span class="token operator">:</span> <span class="token punctuation">{</span> <span class="token literal-property property">backgroundColor</span><span class="token operator">:</span> <span class="token string">'yellow'</span> <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">]</span><span class="token punctuation">}</span></span>
<span class="token punctuation">/></span></span>
When you hover on this element, color: red; backgroundColor: white;
is applied.
If foo: true
, then color: red; backgroundColor: grey;
is applied when hovering.
If bar: true
, then color: red; backgroundColor: yellow;
is applied when hovering regardless of foo
value, because the higher index of the array has higher specificity.
<span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Box</span></span>
<span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">[</span>
<span class="token punctuation">{</span> <span class="token literal-property property">mr</span><span class="token operator">:</span> <span class="token number">2</span><span class="token punctuation">,</span> <span class="token literal-property property">color</span><span class="token operator">:</span> <span class="token string">'red'</span> <span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">(</span><span class="token parameter">theme</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">(</span><span class="token punctuation">{</span>
<span class="token string-property property">'&:hover'</span><span class="token operator">:</span> <span class="token punctuation">{</span>
<span class="token literal-property property">color</span><span class="token operator">:</span> theme<span class="token punctuation">.</span>palette<span class="token punctuation">.</span>primary<span class="token punctuation">.</span>main<span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
<span class="token punctuation">]</span><span class="token punctuation">}</span></span>
<span class="token punctuation">/></span></span>
Passing the sx prop
If you want to receive the sx
prop from a custom component and pass it down to an MUI component, we recommend this approach:
TypeScript usage
A frequent source of confusion with the sx
prop is TypeScript's type widening, which causes this example not to work as expected:
<span class="token keyword">const</span> style <span class="token operator">=</span> <span class="token punctuation">{</span>
flexDirection<span class="token operator">:</span> <span class="token string">'column'</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span><span class="token punctuation">;</span>
<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">return</span> <span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Button</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>style<span class="token punctuation">}</span></span><span class="token punctuation">></span></span>Example<span class="token tag"><span class="token tag"><span class="token punctuation"></</span><span class="token class-name">Button</span></span><span class="token punctuation">></span></span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
<span class="token comment">// Type '{ flexDirection: string; }' is not assignable to type 'SxProps<Theme> | undefined'</span>
<span class="token comment">// Type '{ flexDirection: string; }' is not assignable to type 'CSSSelectorObject<Theme>'</span>
<span class="token comment">// Property 'flexDirection' is incompatible with index signature</span>
<span class="token comment">// Type 'string' is not assignable to type 'SystemStyleObject<Theme>'</span>
The problem is that the type of the flexDirection
prop is inferred as string
, which is too wide.
To fix this, you can cast the object/function passed to the sx
prop to const
:
<span class="token keyword">const</span> style <span class="token operator">=</span> <span class="token punctuation">{</span>
flexDirection<span class="token operator">:</span> <span class="token string">'column'</span><span class="token punctuation">,</span>
<span class="token punctuation">}</span> <span class="token keyword">as</span> <span class="token keyword">const</span><span class="token punctuation">;</span>
<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">return</span> <span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Button</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span>style<span class="token punctuation">}</span></span><span class="token punctuation">></span></span>Example<span class="token tag"><span class="token tag"><span class="token punctuation"></</span><span class="token class-name">Button</span></span><span class="token punctuation">></span></span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
Alternatively, you can pass the style object directly to the sx
prop:
<span class="token keyword">export</span> <span class="token keyword">default</span> <span class="token keyword">function</span> <span class="token function">App</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
<span class="token keyword">return</span> <span class="token tag"><span class="token tag"><span class="token punctuation"><</span><span class="token class-name">Button</span></span> <span class="token attr-name">sx</span><span class="token script language-javascript"><span class="token script-punctuation punctuation">=</span><span class="token punctuation">{</span><span class="token punctuation">{</span> flexDirection<span class="token operator">:</span> <span class="token string">'column'</span> <span class="token punctuation">}</span><span class="token punctuation">}</span></span><span class="token punctuation">></span></span>Example<span class="token tag"><span class="token tag"><span class="token punctuation"></</span><span class="token class-name">Button</span></span><span class="token punctuation">></span></span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>
Performance
To learn more about the performance tradeoffs of the sx
prop, check out Usage–Performance tradeoffs.