diff --git a/docs/src/pages/css-in-js/advanced/advanced-pt.md b/docs/src/pages/css-in-js/advanced/advanced-pt.md new file mode 100644 index 00000000000000..98d0a3d9619888 --- /dev/null +++ b/docs/src/pages/css-in-js/advanced/advanced-pt.md @@ -0,0 +1,311 @@ +# Advanced + +

Advanced Usage.

+ +## Theming + +Add a `ThemeProvider` to the top level of your app to access the theme down the React's component tree. Then, you can access the theme object in the style functions. + +{{"demo": "pages/css-in-js/advanced/Theming.js", "react": "next"}} + +## Accessing the theme in a component + +You might need to access the theme variables inside your React components. + +### `useTheme` hook + +{{"demo": "pages/css-in-js/advanced/UseTheme.js", "react": "next"}} + +### `withTheme` HOC + +{{"demo": "pages/css-in-js/advanced/WithTheme.js", "react": "next"}} + +## Theme nesting + +You can nest multiple theme providers. This can be really useful when dealing with different area of your application that have distinct appearance from each other. + +```jsx + + + + + + +``` + +{{"demo": "pages/css-in-js/advanced/ThemeNesting.js", "react": "next"}} + +The inner theme will **override** the outer theme. You can extend the outer theme by providing a function: + +```jsx + + + ({ darkMode: true, ...outerTheme })}> + + + +``` + +## JSS plugins + +JSS uses the concept of plugins to extend its core, allowing people to cherry-pick the features they need. You pay the performance overhead for only what's you are using. All the plugins aren't available by default. We have added the following list: + +- [jss-plugin-rule-value-function](https://cssinjs.org/jss-plugin-rule-value-function/) +- [jss-plugin-global](https://cssinjs.org/jss-plugin-global/) +- [jss-plugin-nested](https://cssinjs.org/jss-plugin-nested/) +- [jss-plugin-camel-case](https://cssinjs.org/jss-plugin-camel-case/) +- [jss-plugin-default-unit](https://cssinjs.org/jss-plugin-default-unit/) +- [jss-plugin-vendor-prefixer](https://cssinjs.org/jss-plugin-vendor-prefixer/) +- [jss-plugin-props-sort](https://cssinjs.org/jss-plugin-props-sort/) + +It's a subset of [jss-preset-default](https://cssinjs.org/jss-preset-default/). Of course, you are free to add a new plugin. Here is an example with the [jss-rtl](https://github.com/alitaheri/jss-rtl) plugin. + +```jsx +import { create } from 'jss'; +import { StylesProvider, jssPreset } from '@material-ui/styles'; +import rtl from 'jss-rtl' + +const jss = create({ + plugins: [...jssPreset().plugins, rtl()], +}); + +function App() { + return ( + + ... + + ); +} + +export default App; +``` + +## String templates + +If you prefer using the CSS syntax, you can use the [jss-plugin-template](https://cssinjs.org/jss-plugin-template) plugin. + +```jsx +const useStyles = makeStyles({ + root: ` + background: linear-gradient(45deg, #fe6b8b 30%, #ff8e53 90%); + border-radius: 3; + border: 0; + color: white; + height: 48px; + padding: 0 30px; + box-shadow: 0 3px 5px 2px rgba(255, 105, 135, 0.3); + `, +}); +``` + +{{"demo": "pages/css-in-js/advanced/StringTemplates.js", "react": "next"}} + +## CSS injection order + +The CSS injected by Material-UI to style a component has the highest specificity possible as the `` is injected at the bottom of the `` to ensure the components always render correctly. + +You might, however, also want to override these styles, for example with styled-components. If you are experiencing a CSS injection order issue, JSS [provides a mechanism](https://github.com/cssinjs/jss/blob/master/docs/setup.md#specify-the-dom-insertion-point) to handle this situation. By adjusting the placement of the `insertionPoint` within your HTML head you can [control the order](https://cssinjs.org/jss-api#attach-style-sheets-in-a-specific-order) that the CSS rules are applied to your components. + +### HTML comment + +The simplest approach is to add an HTML comment that determines where JSS will inject the styles: + +```jsx + + + + +``` + +```jsx +import { create } from 'jss'; +import { StylesProvider, jssPreset } from '@material-ui/styles'; + +const jss = create({ + ...jssPreset(), + // We define a custom insertion point that JSS will look for injecting the styles in the DOM. + insertionPoint: 'jss-insertion-point', +}); + +function App() { + return ...; +} + +export default App; +``` + +### Other HTML element + +[Create React App](https://github.com/facebook/create-react-app) strips HTML comments when creating the production build. To get around the issue, you can provide a DOM element (other than a comment) as the JSS insertion point. + +For example, a `