---
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 (
);
}
```
## 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 `