[docs] Add useRadioGroup section (#21910)

Co-authored-by: Olivier Tassinari <[email protected]>

docs/src/pages/components/radio-buttons/UseRadioGroup.js

@@ -0,0 +1,48 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { makeStyles } from '@material-ui/core/styles';
+import RadioGroup, { useRadioGroup } from '@material-ui/core/RadioGroup';
+import FormControlLabel from '@material-ui/core/FormControlLabel';
+import Radio from '@material-ui/core/Radio';
+
+const useStyles = makeStyles((theme) => ({
+  labelChecked: {
+    color: theme.palette.secondary.main,
+  },
+}));
+
+function MyFormControlLabel(props) {
+  const classes = useStyles();
+  const radioGroup = useRadioGroup();
+
+  let checked = false;
+
+  if (radioGroup) {
+    checked = radioGroup.value === props.value;
+  }
+
+  return (
+    <FormControlLabel
+      classes={{
+        label: checked ? classes.labelChecked : '',
+      }}
+      {...props}
+    />
+  );
+}
+
+MyFormControlLabel.propTypes = {
+  /**
+   * The value of the component.
+   */
+  value: PropTypes.any,
+};
+
+export default function UseRadioGroup() {
+  return (
+    <RadioGroup name="use-radio-group" defaultValue="first">
+      <MyFormControlLabel value="first" label="First" control={<Radio />} />
+      <MyFormControlLabel value="second" label="Second" control={<Radio />} />
+    </RadioGroup>
+  );
+}

docs/src/pages/components/radio-buttons/UseRadioGroup.tsx

@@ -0,0 +1,44 @@
+import React from 'react';
+import { makeStyles, createStyles } from '@material-ui/core/styles';
+import RadioGroup, { useRadioGroup } from '@material-ui/core/RadioGroup';
+import FormControlLabel, {
+  FormControlLabelProps,
+} from '@material-ui/core/FormControlLabel';
+import Radio from '@material-ui/core/Radio';
+
+const useStyles = makeStyles((theme) =>
+  createStyles({
+    labelChecked: {
+      color: theme.palette.secondary.main,
+    },
+  }),
+);
+
+function MyFormControlLabel(props: FormControlLabelProps) {
+  const classes = useStyles();
+  const radioGroup = useRadioGroup();
+
+  let checked = false;
+
+  if (radioGroup) {
+    checked = radioGroup.value === props.value;
+  }
+
+  return (
+    <FormControlLabel
+      classes={{
+        label: checked ? classes.labelChecked : '',
+      }}
+      {...props}
+    />
+  );
+}
+
+export default function UseRadioGroup() {
+  return (
+    <RadioGroup name="use-radio-group" defaultValue="first">
+      <MyFormControlLabel value="first" label="First" control={<Radio />} />
+      <MyFormControlLabel value="second" label="Second" control={<Radio />} />
+    </RadioGroup>
+  );
+}

docs/src/pages/components/radio-buttons/radio-buttons.md

@@ -45,6 +45,30 @@ Here is an example of customizing the component. You can learn more about this i
 
 {{"demo": "pages/components/radio-buttons/CustomizedRadios.js"}}
 
+## `useRadioGroup`
+
+For advanced customization use cases, a `useRadioGroup()` hook is exposed.
+It returns the context value of the parent radio group.
+The Radio component uses this hook internally.
+
+### API
+
+```jsx
+import { useRadioGroup } from '@material-ui/core/RadioGroup';
+```
+
+#### Returns
+
+`value` (_Object_):
+
+- `value.name` (_String_ [optional]): The name used to reference the value of the control.
+- `value.onChange` (_Void_ [optional]): Callback fired when a radio button is selected.
+- `value.value` (_Any_ [optional]): Value of the selected radio button.
+
+#### Example
+
+{{"demo": "pages/components/radio-buttons/UseRadioGroup.js"}}
+
 ## When to use
 
 - [Checkboxes vs. Radio Buttons](https://www.nngroup.com/articles/checkboxes-vs-radio-buttons/)