mergeSx
Combines several sx
values into a single sx array that you can pass to any Material UI component.
It is what the components in this package use internally to merge their own base
styles with the sx you pass in, and it is useful whenever you build a reusable
component that accepts an sx prop of its own.
function mergeSx(
...sources: (SxProps<Theme> | false | null | undefined)[]
): SxProps<Theme>;Usage
import { mergeSx } from '@nish1896/mui-components/form-helpers';Why not spread the objects?
sx accepts an object, a callback that receives the theme, or an array of
those. Spreading two values, { ...a, ...b }, only works while both are plain
objects:
- An array collapses into numeric keys, so its styles are lost.
- A callback has no own properties, so it is dropped.
mergeSx keeps every form intact by returning an array, which is the format
MUI v9 recommends for combining sx values.
Parameters
...sources - Any number of sx values, merged from left to right:
- An object, a theme callback or an array of those.
false,nullorundefined, which are skipped. This lets you pass a conditional style inline, as inisActive && { color: 'primary.main' }.
Returns
A new sx array. Later sources win over earlier ones, exactly like object
spread. The inputs are never mutated.
An array source is spread one level, and its own entries are kept as they are.
MUI accepts objects, callbacks and false inside an sx array.
The result can be passed anywhere MUI expects an sx, such as
slotProps.input.sx or slotProps.paper.sx.
Examples
Forwarding the sx prop
Put your base styles first and the sx received from props last, so the caller
can override them:
import Box from '@mui/material/Box';
import type { SxProps, Theme } from '@mui/material/styles';
import { mergeSx } from '@nish1896/mui-components/form-helpers';
type CardProps = { sx?: SxProps<Theme> };
const Card = ({ sx }: CardProps) => (
<Box
sx={mergeSx(
{ p: 2, borderRadius: 1 },
sx
)}
/>
);
<Card sx={{ p: 4 }} />; // padding is 4, the border radius staysConditional styles
<Box
sx={mergeSx(
baseSx,
isActive && { color: 'primary.main' },
sx
)}
/>Theme callbacks and arrays
const merged = mergeSx(
{ px: 2 },
theme => ({ borderColor: theme.palette.divider }),
[{ mt: 1 }, isDense && { mt: 0 }]
);