MUIRadioGroup
MUIRadioGroup wraps the Material UI
RadioGroup for a single
choice among options, storing the selected value. Supports primitive or object
options via labelKey/valueKey.
Usage
import MUIRadioGroup, { MUIRadioGroupProps } from '@nish1896/mui-components/mui/radio-group';const [plan, setPlan] = useState();
<MUIRadioGroup
fieldName="plan"
options={['Free', 'Pro', 'Enterprise']}
value={plan}
onValueChange={({ newValue, event }) => setPlan(newValue)}
/>value is the selected option's value, and undefined or null
mean nothing is selected. onValueChange receives { newValue, event }:
the selected value and the change event.
Option value types
The type of the options is preserved. A radio button's value is a
string in the DOM, but the component maps it back to the option,
so string options give a string and number options give a number.
Declare primitive options outside the JSX, as below. An array written
inline is inferred by TypeScript as a union of its literal values, such
as 10 | 25 | 50, and then a number | null state doesn't match it.
const pageSizeOptions = [10, 25, 50];
const [pageSize, setPageSize] = useState<number | null>(null);
/* newValue is a number, for example 25 */
<MUIRadioGroup
fieldName="pageSize"
options={pageSizeOptions}
value={pageSize}
onValueChange={({ newValue }) => setPageSize(newValue)}
/>With an array of objects
Options can also be objects. In this case, both labelKey and valueKey
are required. labelKey is the property used as each radio button's
label, and valueKey is the property used as its value.
value is then the valueKey property of the selected option, not the
whole object, and it keeps the type of that property: a string
property gives a string, and a number property gives a number.
const [nationality, setNationality] = useState<string | null>(null);
<MUIRadioGroup
fieldName="nationality"
options={[
{ code: 'AUS', country: 'Australia' },
{ code: 'IN', country: 'India' },
{ code: 'USA', country: 'United States of America' },
{ code: 'UAE', country: 'United Arab Emirates' }
]}
labelKey="country"
valueKey="code"
value={nationality}
onValueChange={({ newValue }) => setNationality(newValue)}
/>Customizing individual options
renderOptionLabel replaces the label of each radio button. It
receives the option and a state object with disabled, which
is true when the option or the whole group is disabled, and
selected, which is true for the current value. The label
can be any ReactNode.
getOptionDisabled receives an option and returns true to
disable that radio button. A disabled option can't be picked
but if it is the current value it stays selected. disabled
on the group disables every option at once.
const [seat, setSeat] = useState<string | null>(null);
<MUIRadioGroup
fieldName="seat"
options={[
{ id: 'window', name: 'Window', taken: false },
{ id: 'aisle', name: 'Aisle', taken: true },
{ id: 'middle', name: 'Middle', taken: false }
]}
labelKey="name"
valueKey="id"
value={seat}
onValueChange={({ newValue }) => setSeat(newValue)}
getOptionDisabled={option => option.taken}
renderOptionLabel={(option, { disabled, selected }) => (
<span
style={{
opacity: disabled ? 0.5 : 1,
fontWeight: selected ? 700 : 400
}}
>
{option.name}{disabled ? ' (taken)' : ''}
</span>
)}
/>Styling each radio button
radioProps is forwarded to every Radio, for example a color,
size or custom icon and checkedIcon. formControlLabelProps
is forwarded to every FormControlLabel that wraps a radio button
and its label, for example labelPlacement. Its sx is merged with
the default FormControlLabel styles from ConfigProvider. The
component controls the radio button's id and disabled, and the label's
control, value, label and disabled.
import RadioButtonUncheckedIcon from '@mui/icons-material/RadioButtonUnchecked';
import CheckCircleIcon from '@mui/icons-material/CheckCircle';
<MUIRadioGroup
fieldName="plan"
options={planOptions}
value={plan}
onValueChange={({ newValue }) => setPlan(newValue)}
radioProps={{
color: 'secondary',
size: 'small',
icon: <RadioButtonUncheckedIcon />,
checkedIcon: <CheckCircleIcon />
}}
formControlLabelProps={{
labelPlacement: 'start',
sx: { justifyContent: 'space-between', mx: 0 }
}}
/>API
For object options, pass labelKey and valueKey.
Props marked with * are required.
| Name | Type | Description |
|---|---|---|
fieldName* | string | Name/path of the field. Used to derive the id, the default label, and the name attribute. This prop is required for all components. |
options* | string[] | number[] | object[] | An array with string, numeric or object values. Make sure to pass labelKey and valueKey when options is an array of objects. |
labelKey | string | Property name used as the visible label for each option. Required when options is an array of objects. |
valueKey | string | Property name used to derive the exposed value for each option. Required when options is an array of objects. |
value | string | number | null | Currently selected option value, normalized with valueKey for object options. undefined/null are treated as no selection. |
onValueChange* | ({ newValue, event }) => void | Called on every selection with the normalized option value and the original change event. |
renderOptionLabel | (option) => ReactNode | Custom renderer for option labels. When not provided, the label is derived from the option value or the property specified by labelKey. |
getOptionDisabled | (option) => boolean | Function used to determine whether an option should be disabled. Return true to disable the option and prevent it from being selected. |
radioProps | RadioProps | RadioProps passed down to each Radio component — custom color, size, etc. |
formControlLabelProps | FormControlLabelProps | FormControlLabelProps forwarded to the internal FormControlLabel. Multiple fields can be configured using the ConfigProvider component. |
label | ReactNode | Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name". |
showLabelAboveFormField | boolean | Whether the field label renders above the component. Since it has no built-in inline label, the label renders above the component by default; pass false to hide the visible label (the accessible name is still applied). Takes precedence over allLabelsAboveFields from the ConfigProvider.Default: true |
formLabelProps | FormLabelProps | FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
hideLabel | boolean | When true, hides the rendered field label while preserving accessible labeling where possible. |
required | boolean | Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes. |
errorMessage | string | string[] | Validation error for the field — pass a single message string, or a string[] when the field can fail multiple rules at once (every message is shown together). A non-empty string or array puts the field in an error state; undefined/''/[] clear it.Normalize your form library's error shape to this at the call site (e.g. an RHF FieldError via its .message). Use renderError to customize how the message(s) are rendered. |
renderError | (errors: string[]) => ReactNode | Custom renderer for the resolved error message(s), called only when the field is in an error state. Always receives a string[] — use errors[0] for the common single-message case, or map over errors when a field fails several rules. By default a single message renders as text and multiple messages render on separate lines. |
hideErrorMessage | boolean | If true, hides the error message text while keeping the field in an error state. |
helperText | ReactNode | Content displayed in the FormHelperText component below the field when there is no visible validation error. |
formHelperTextProps | FormHelperTextProps | FormHelperTextProps forwarded to the internal FormHelperText. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component. |
customIds | { field, label, helperText, error } | Overrides the default field, label, helper text, and error IDs used for accessibility. |
Playground
Driven by plain React state — string and object options (labelKey /
valueKey), getOptionDisabled, radioProps, a custom renderOptionLabel,
and required validation.
Reference
Source Code
View the full implementation of this component on GitHub.