Skip to content

Commit

Permalink
[docs] Add API tradeoff section for the sx prop (mui#23962)
Browse files Browse the repository at this point in the history
  • Loading branch information
mnajdova authored Dec 12, 2020
1 parent d694969 commit ea0563f
Showing 1 changed file with 7 additions and 1 deletion.
8 changes: 7 additions & 1 deletion docs/src/pages/system/basics/basics.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ The system provides direct access to the value in the theme. It makes it easier

The `sx` prop, as the main part of the system, solves these problems by providing a fast & simple way of applying the correct design tokens for specific CSS properties directly to a React element. The [demo above](#demo) shows how it can be used to create a one-off design.

This prop provides a superset of CSS that maps values directly from the theme, depending on the CSS property used. Also, it allows a simple way of defining responsive values that correspond to the breakpoints defined in the theme.
This prop provides a superset of CSS (contains all CSS properties/selectors in addition to custom ones) that maps values directly from the theme, depending on the CSS property used. Also, it allows a simple way of defining responsive values that correspond to the breakpoints defined in the theme.

### When to use it?

Expand Down Expand Up @@ -186,6 +186,12 @@ Cons:

We believe that for most uses it's **fast enough**, but there are simple workarounds when performance becomes critical. For instance, when rendering a list with many items, you can use a CSS child selector to have a single "style injection" point (using d. for the wrapper and a. for each item).

### API tradeoff

In previous versions, the system properties were supported as props on the `Box` component. From v5, however, the system provides a superset of CSS (supports all CSS properties/selectors in addition to custom ones), and is available in all components, so selectors cannot be efficiently mapped to props without potential naming conflicts. Instead, all system properties are available under one prop `sx`.

Additionally, having the system under one prop helps to easily differentiate props defined for the sole purpose of CSS utilities, vs. those for component business logic.

## Usage

### Design tokens in the theme
Expand Down

0 comments on commit ea0563f

Please sign in to comment.