merge-sx v2.0.1

merge-sx

Combines multiple SxProps for Material UI components.

Installation

npm install merge-sx
# or
yarn add merge-sx

Usage

The utility provides a very simple and semantically clean interface, that supports conditional and optional inclusions.

import { mergeSx } from "merge-sx";

// Merge your SxProps
mergeSx(sx1, sx2 /*, ... */);
// Merge optionally
mergeSx(internalSx, props?.sx); // supports undefined
// Merge conditionally
mergeSx(commonSx, isMobile && mobileSx); // supports false

Why might you need it

MUI 5 has introduced a new way of styling React components using a Theme-aware sx property. It can be necessary to create your own styled components while still allowing for additional styling by the consumer. In this case your component will have its own sx property, most likely optional. This makes it necessary somehow to combine your own styles with the styles coming from the consumer of your component. One approach might be using a styling wrapper, an alternative way to style your component with the styled() utility. Thus, you could apply the consumer's sx to the pre-styled component. However, this approach can be inconvenient for several reasons.

I came to conclusion that merging several sx properties is better. However, the SxProps has rather complex data type. It can be an object with styling properties, can be function, can be null. It can be a challenge to perform a merge under strict typing of Typescript.

How it works

Luckily, starting version 5.1.0 of MUI SxProps can also be array. However, nested arrays are not allowed, so this utility does exactly the flat merge, also bringing support for conditional and optional inclusions, providing a very simple and semantically clean interface.

Performance

The utility has been tested to support up to 65535 arguments.

┌─────────────┬──────────┬─────────┬────────┬───────┐
│ N arguments │   10     │   100   │  1000  │ 10000 │
├─────────────┼──────────┼─────────┼────────┼───────┤
│ ops/s       │ 13615624 │ 1273083 │ 122746 │ 14686 │
└─────────────┴──────────┴─────────┴────────┴───────┘

Examples

Conditional merging

The utility supports false:

<Button sx={mergeSx(commonSx, isMobile && mobileSx)}>Click me</Button>

Optional merging

The utility supports undefined:

interface MyButtonProps {
  sx?: SxProps<Theme>; // optional prop for consumer
}

const MyButton = ({ sx: consumerSx }: MyButtonProps) => (
  <Button sx={mergeSx(internalSx, consumerSx)}>Click me</Button>
);

Inline Theme supplying

The utility is generic and accepts the type argument.

// theme is Theme
mergeSx<Theme>(sx1, (theme) => ({ mb: theme.spacing(1) }));