MUI Components
NPM

MUICheckboxGroup

MUICheckboxGroup renders a group of checkboxes from options and stores an array of the selected values. Supports primitive or object options via labelKey/valueKey.

Usage

import MUICheckboxGroup, {
  MUICheckboxGroupProps
} from '@nish1896/mui-components/mui/checkbox-group';
const permissionOptions = ['Read', 'Write', 'Delete'];
const [permissions, setPermissions] = useState<string[]>([]);

<MUICheckboxGroup
  fieldName="permissions"
  options={permissionOptions}
  value={permissions}
  onValueChange={({ newValue, toggledValue, checked, event }) => setPermissions(newValue)}
/>

value is an array of the checked options' values, in the order they were checked, and undefined or [] mean nothing is checked. onValueChange receives { newValue, toggledValue, checked, event }: the next array, the value of the checkbox that was toggled, its new checked state, and the change event.

Option value types

The type of the options is preserved. A checkbox's value is a string in the DOM, but the component converts it back to the type of 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 1 | 2 | 3 | 4, and then a number[] state doesn't match it.

const roomOptions = [1, 2, 3, 4];
const [rooms, setRooms] = useState<number[]>([]);

/* newValue is a number[], for example [1, 3] */
<MUICheckboxGroup
  fieldName="rooms"
  options={roomOptions}
  value={rooms}
  onValueChange={({ newValue }) => setRooms(newValue)}
/>

With an array of objects

Options can also be objects. Both labelKey and valueKey are required in this case. labelKey is the property used as each checkbox's label, and valueKey is the property used as its value.

value is then an array of the valueKey properties of the checked options, not the whole objects, and it keeps the type of that property: a string property gives a string[], and a number property gives a number[].

const [roleIds, setRoleIds] = useState<number[]>([]);

<MUICheckboxGroup
  fieldName="roles"
  options={[
    { id: 1, name: 'Admin' },
    { id: 2, name: 'Editor' },
    { id: 3, name: 'Viewer' }
  ]}
  labelKey="name"
  valueKey="id"
  value={roleIds}
  onValueChange={({ newValue }) => setRoleIds(newValue)}
/>

Customizing individual options

renderOptionLabel replaces the label of each checkbox. 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 while the checkbox is checked. The label can be any ReactNode.

getOptionDisabled receives an option and returns true to disable that checkbox. A disabled checkbox keeps its current state and can't be toggled, so a disabled option that is already checked stays in value. disabled on the group disables every option at once.

const [addons, setAddons] = useState<string[]>([]);

<MUICheckboxGroup
  fieldName="addons"
  options={[
    { id: 'wifi', name: 'Wi-Fi', soldOut: false },
    { id: 'parking', name: 'Parking', soldOut: true },
    { id: 'breakfast', name: 'Breakfast', soldOut: false }
  ]}
  labelKey="name"
  valueKey="id"
  value={addons}
  onValueChange={({ newValue }) => setAddons(newValue)}
  getOptionDisabled={option => option.soldOut}
  renderOptionLabel={(option, { disabled, selected }) => (
    <span
      style={{
        opacity: disabled ? 0.5 : 1,
        fontWeight: selected ? 700 : 400
      }}
    >
      {option.name}{disabled ? ' (unavailable)' : ''}
    </span>
  )}
/>

Styling each checkbox

checkboxProps is forwarded to every Checkbox, for example a color, size or custom icon and checkedIcon. formControlLabelProps is forwarded to every FormControlLabel that wraps a checkbox and its label, for example labelPlacement. Its sx is merged with the default FormControlLabel styles from ConfigProvider. The component controls the checkbox's id, name, value, checked, disabled and onChange, and the label's control, label and disabled.

import CircleOutlinedIcon from '@mui/icons-material/CircleOutlined';
import CheckCircleIcon from '@mui/icons-material/CheckCircle';

<MUICheckboxGroup
  fieldName="permissions"
  options={permissionOptions}
  value={permissions}
  onValueChange={({ newValue }) => setPermissions(newValue)}
  checkboxProps={{
    color: 'secondary',
    size: 'small',
    icon: <CircleOutlinedIcon />,
    checkedIcon: <CheckCircleIcon />
  }}
  formControlLabelProps={{
    labelPlacement: 'start',
    sx: { justifyContent: 'space-between', mx: 0 }
  }}
/>

API

For object options, pass labelKey and valueKey.

Props marked with * are required.

NameTypeDescription
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.
labelKeystring
Property name used as the visible label for each option. Required when options is an array of objects.
valueKeystring
Property name used to derive the exposed value for each option. Required when options is an array of objects.
valuestring[] | number[]
Currently checked option values. undefined/[] is treated as an empty selection.
onValueChange*({ newValue, toggledValue, checked, event }) => void
Called on every toggle with the next array of checked option values, the toggled option, its next checked state, 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.
checkboxPropsCheckboxProps
CheckboxProps passed down to each Checkbox component — custom color, size, etc.
formControlLabelPropsFormControlLabelProps
FormControlLabelProps forwarded to the internal FormControlLabel. Multiple fields can be configured using the ConfigProvider component.
labelReactNode
Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name".
showLabelAboveFormFieldboolean
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
hideLabelboolean
When true, hides the rendered field label while preserving accessible labeling where possible.
formLabelPropsFormLabelProps
FormLabelProps forwarded to the internal FormLabel. The id is managed by the component. Multiple fields can be configured using the ConfigProvider component.
requiredboolean
Indicates that the field is mandatory by adding an asterisk symbol (*) to the form label and setting the relevant accessibility attributes.
errorMessagestring | 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.
hideErrorMessageboolean
If true, hides the error message text while keeping the field in an error state.
helperTextReactNode
Content displayed in the FormHelperText component below the field when there is no visible validation error.
formHelperTextPropsFormHelperTextProps
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

Integrated with Formik — string options with a minimum-selected rule, and object options (labelKey / valueKey) with getOptionDisabled and pass-through checkboxProps.

String options — minimum two required

Hobbies
Pick at least two

Object options, getOptionDisabled & custom checkbox colour and icons

Permissions
'Read' is always granted

Numeric options — value stored as number[]

Scores
Each checked value is stored as a number

Form State - Values & Errors

Reference

Source Code

View the full implementation of this component on GitHub.