[docs] Explain how to pass props down to overridden components (mui#1…

…2716)

* [docs] Explain how to pass props down to overridden components

* [docs] Add a shorthand override section

docs/src/pages/customization/overrides/ClassNames.js

@@ -1,5 +1,6 @@
 import React from 'react';
 import PropTypes from 'prop-types';
+import classNames from 'classnames';
 import { withStyles } from '@material-ui/core/styles';
 import Button from '@material-ui/core/Button';
 
@@ -17,16 +18,19 @@ const styles = {
 };
 
 function ClassNames(props) {
+  const { classes, children, className, ...other } = props;
+
   return (
-    <Button className={props.classes.root}>
-      {props.children ? props.children : 'class names'}
+    <Button className={classNames(classes.root, className)} {...other}>
+      {children || 'class names'}
     </Button>
   );
 }
 
 ClassNames.propTypes = {
   children: PropTypes.node,
   classes: PropTypes.object.isRequired,
+  className: PropTypes.string,
 };
 
 export default withStyles(styles)(ClassNames);

docs/src/pages/customization/overrides/ClassesShorthand.js

@@ -0,0 +1,24 @@
+import React from 'react';
+import { withStyles } from '@material-ui/core/styles';
+import Button from '@material-ui/core/Button';
+
+// The `withStyles()` higher-order component is injecting a `classes`
+// property that is used by the `Button` component.
+const StyledButton = withStyles({
+  root: {
+    background: 'linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)',
+    borderRadius: 3,
+    border: 0,
+    color: 'white',
+    height: 48,
+    padding: '0 30px',
+    boxShadow: '0 3px 5px 2px rgba(255, 105, 135, .3)',
+  },
+  label: {
+    textTransform: 'capitalize',
+  },
+})(Button);
+
+export default function ClassesShorthand() {
+  return <StyledButton>Classes Shorthand</StyledButton>
+}

docs/src/pages/customization/overrides/overrides.md

@@ -43,6 +43,30 @@ Notice that in addition to the button styling, the button label's capitalization
 
 {{"demo": "pages/customization/overrides/ClassesNesting.js"}}
 
+#### Shorthand
+
+The above code example can be condensed by using **the same CSS API** than the child component.
+In this example, the `withStyles()` higher-order component is injecting a `classes` property that is used by the [`Button` component](/api/button#css-api).
+
+```jsx
+const StyledButton = withStyles({
+  root: {
+    background: 'linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)',
+    borderRadius: 3,
+    border: 0,
+    color: 'white',
+    height: 48,
+    padding: '0 30px',
+    boxShadow: '0 3px 5px 2px rgba(255, 105, 135, .3)',
+  },
+  label: {
+    textTransform: 'capitalize',
+  },
+})(Button);
+```
+
+{{"demo": "pages/customization/overrides/ClassesShorthand.js"}}
+
 #### Internal states
 
 Aside from accessing nested elements, the `classes` property can be used to customize the internal states of Material-UI components.

pages/customization/overrides.js

@@ -22,6 +22,13 @@ module.exports = require('fs')
           raw: preval`
 module.exports = require('fs')
   .readFileSync(require.resolve('docs/src/pages/customization/overrides/ClassesNesting'), 'utf8')
+`,
+        },
+        'pages/customization/overrides/ClassesShorthand.js': {
+          js: require('docs/src/pages/customization/overrides/ClassesShorthand').default,
+          raw: preval`
+module.exports = require('fs')
+  .readFileSync(require.resolve('docs/src/pages/customization/overrides/ClassesShorthand'), 'utf8')
 `,
         },
         'pages/customization/overrides/ClassesState.js': {