--- productId: material-ui title: React Radio Group component components: Radio, RadioGroup, FormControl, FormLabel, FormControlLabel githubLabel: 'scope: radio' materialDesign: https://m2.material.io/components/selection-controls#radio-buttons waiAria: https://www.w3.org/WAI/ARIA/apg/patterns/radio/ githubSource: packages/mui-material/src/RadioGroup --- # Radio Group The Radio Group allows the user to select one option from a set. Use radio buttons when the user needs to see all available options. If available options can be collapsed, consider using a [Select component](/material-ui/react-select/) because it uses less space. Radio buttons should have the most commonly used option selected by default. ## Radio group `RadioGroup` is a helpful wrapper used to group `Radio` components that provides an easier API, and proper keyboard accessibility to the group. ```tsx import * as React from 'react'; import Radio from '@mui/material/Radio'; import RadioGroup from '@mui/material/RadioGroup'; import FormControlLabel from '@mui/material/FormControlLabel'; import FormControl from '@mui/material/FormControl'; import FormLabel from '@mui/material/FormLabel'; export default function RadioButtonsGroup() { const id = React.useId(); return ( Gender } label="Female" /> } label="Male" /> } label="Other" /> ); } ``` ### Direction To lay out the buttons horizontally, set the `row` prop: ```tsx import * as React from 'react'; import Radio from '@mui/material/Radio'; import RadioGroup from '@mui/material/RadioGroup'; import FormControlLabel from '@mui/material/FormControlLabel'; import FormControl from '@mui/material/FormControl'; import FormLabel from '@mui/material/FormLabel'; export default function RowRadioButtonsGroup() { const id = React.useId(); return ( Gender } label="Female" /> } label="Male" /> } label="Other" /> } label="other" /> ); } ``` ### Controlled You can control the radio with the `value` and `onChange` props: ```tsx import * as React from 'react'; import Radio from '@mui/material/Radio'; import RadioGroup from '@mui/material/RadioGroup'; import FormControlLabel from '@mui/material/FormControlLabel'; import FormControl from '@mui/material/FormControl'; import FormLabel from '@mui/material/FormLabel'; export default function ControlledRadioButtonsGroup() { const id = React.useId(); const [value, setValue] = React.useState('female'); const handleChange = (event: React.ChangeEvent) => { setValue((event.target as HTMLInputElement).value); }; return ( Gender } label="Female" /> } label="Male" /> ); } ``` ## Standalone radio buttons `Radio` can also be used standalone, without the RadioGroup wrapper. ```tsx import * as React from 'react'; import Radio from '@mui/material/Radio'; export default function RadioButtons() { const [selectedValue, setSelectedValue] = React.useState('a'); const handleChange = (event: React.ChangeEvent) => { setSelectedValue(event.target.value); }; return (
); } ``` ## Size Use the `size` prop or customize the font size of the svg icons to change the size of the radios. ```tsx import * as React from 'react'; import Radio from '@mui/material/Radio'; export default function SizeRadioButtons() { const [selectedValue, setSelectedValue] = React.useState('a'); const handleChange = (event: React.ChangeEvent) => { setSelectedValue(event.target.value); }; const controlProps = (item: string) => ({ checked: selectedValue === item, onChange: handleChange, value: item, name: 'size-radio-button-demo', inputProps: { 'aria-label': item }, }); return (
); } ``` ## Color ```tsx import * as React from 'react'; import { pink } from '@mui/material/colors'; import Radio from '@mui/material/Radio'; export default function ColorRadioButtons() { const [selectedValue, setSelectedValue] = React.useState('a'); const handleChange = (event: React.ChangeEvent) => { setSelectedValue(event.target.value); }; const controlProps = (item: string) => ({ checked: selectedValue === item, onChange: handleChange, value: item, name: 'color-radio-button-demo', inputProps: { 'aria-label': item }, }); return (
); } ``` ## Label placement You can change the placement of the label with the `FormControlLabel` component's `labelPlacement` prop: ```tsx import * as React from 'react'; import Radio from '@mui/material/Radio'; import RadioGroup from '@mui/material/RadioGroup'; import FormControlLabel from '@mui/material/FormControlLabel'; import FormControl from '@mui/material/FormControl'; import FormLabel from '@mui/material/FormLabel'; export default function FormControlLabelPlacement() { const id = React.useId(); return ( Label placement } label="Bottom" labelPlacement="bottom" /> } label="End" /> ); } ``` ## Show error In general, radio buttons should have a value selected by default. If this is not the case, you can display an error if no value is selected when the form is submitted: ```tsx import * as React from 'react'; import Radio from '@mui/material/Radio'; import RadioGroup from '@mui/material/RadioGroup'; import FormControlLabel from '@mui/material/FormControlLabel'; import FormControl from '@mui/material/FormControl'; import FormHelperText from '@mui/material/FormHelperText'; import FormLabel from '@mui/material/FormLabel'; import Button from '@mui/material/Button'; export default function ErrorRadios() { const id = React.useId(); const [value, setValue] = React.useState(''); const [error, setError] = React.useState(false); const [helperText, setHelperText] = React.useState('Choose wisely'); const handleRadioChange = (event: React.ChangeEvent) => { setValue(event.target.value); setError(false); setHelperText('Choose wisely'); }; const handleSubmit = (event: React.FormEvent) => { event.preventDefault(); if (value === 'best') { setHelperText('You got it!'); setError(false); } else if (value === 'worst') { setHelperText('Sorry, wrong answer!'); setError(true); } else { setHelperText('Please select an option.'); setError(true); } }; return (
Pop quiz: MUI is… } label="The best!" /> } label="The worst." /> {helperText}
); } ``` ## Customization Here is an example of customizing the component. You can learn more about this in the [overrides documentation page](/material-ui/customization/how-to-customize/). ```tsx import * as React from 'react'; import { styled } from '@mui/material/styles'; import Radio, { RadioProps } from '@mui/material/Radio'; import RadioGroup from '@mui/material/RadioGroup'; import FormControlLabel from '@mui/material/FormControlLabel'; import FormControl from '@mui/material/FormControl'; import FormLabel from '@mui/material/FormLabel'; const BpIcon = styled('span')(({ theme }) => ({ borderRadius: '50%', width: 16, height: 16, boxShadow: 'inset 0 0 0 1px rgba(16,22,26,.2), inset 0 -1px 0 rgba(16,22,26,.1)', backgroundColor: '#f5f8fa', backgroundImage: 'linear-gradient(180deg,hsla(0,0%,100%,.8),hsla(0,0%,100%,0))', '.Mui-focusVisible &': { outline: '2px auto rgba(19,124,189,.6)', outlineOffset: 2, }, 'input:hover ~ &': { backgroundColor: '#ebf1f5', ...theme.applyStyles('dark', { backgroundColor: '#30404d', }), }, 'input:disabled ~ &': { boxShadow: 'none', background: 'rgba(206,217,224,.5)', ...theme.applyStyles('dark', { background: 'rgba(57,75,89,.5)', }), '@media (forced-colors: active)': { outline: '1px solid GrayText', }, }, '@media (forced-colors: active)': { outline: '1px solid ButtonText', }, ...theme.applyStyles('dark', { boxShadow: '0 0 0 1px rgb(16 22 26 / 40%)', backgroundColor: '#394b59', backgroundImage: 'linear-gradient(180deg,hsla(0,0%,100%,.05),hsla(0,0%,100%,0))', }), })); const BpCheckedIcon = styled(BpIcon)({ backgroundColor: '#137cbd', backgroundImage: 'linear-gradient(180deg,hsla(0,0%,100%,.1),hsla(0,0%,100%,0))', '&::before': { display: 'block', width: 16, height: 16, backgroundImage: 'radial-gradient(#fff,#fff 28%,transparent 32%)', content: '""', '@media (forced-colors: active)': { backgroundImage: 'none', backgroundColor: 'ButtonText', borderRadius: '50%', width: 8, height: 8, margin: 4, }, }, 'input:hover ~ &': { backgroundColor: '#106ba3', }, '@media (forced-colors: active)': { outline: '2px solid ButtonText', }, }); // Inspired by blueprintjs function BpRadio(props: RadioProps) { return ( } icon={} {...props} /> ); } export default function CustomizedRadios() { const id = React.useId(); return ( Gender } label="Female" /> } label="Male" /> } label="Other" /> } label="(Disabled option)" /> ); } ``` ## `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 '@mui/material/RadioGroup'; ``` #### Returns `value` (_object_): - `value.name` (_string_ [optional]): The name used to reference the value of the control. - `value.onChange` (_func_ [optional]): Callback fired when a radio button is selected. - `value.value` (_any_ [optional]): Value of the selected radio button. #### Example ```tsx import { styled } from '@mui/material/styles'; import RadioGroup, { useRadioGroup } from '@mui/material/RadioGroup'; import FormControlLabel, { FormControlLabelProps, } from '@mui/material/FormControlLabel'; import Radio from '@mui/material/Radio'; interface StyledFormControlLabelProps extends FormControlLabelProps { checked: boolean; } const StyledFormControlLabel = styled((props: StyledFormControlLabelProps) => ( ))(({ theme }) => ({ variants: [ { props: { checked: true }, style: { '.MuiFormControlLabel-label': { color: theme.palette.primary.main, }, }, }, ], })); function MyFormControlLabel(props: FormControlLabelProps) { const radioGroup = useRadioGroup(); let checked = false; if (radioGroup) { checked = radioGroup.value === props.value; } return ; } export default function UseRadioGroup() { return ( } /> } /> ); } ``` ## When to use - [Checkboxes vs. Radio Buttons](https://www.nngroup.com/articles/checkboxes-vs-radio-buttons/) ## Accessibility (WAI-ARIA: https://www.w3.org/WAI/ARIA/apg/patterns/radio/) - All form controls should have labels, and this includes radio buttons, checkboxes, and switches. In most cases, this is done by using the `