MUI Components
NPM

MUICheckbox

MUICheckbox is a single Checkbox with a boolean value, an inline label, and optional helper text or error state.

Usage

import MUICheckbox, { MUICheckboxProps } from '@nish1896/mui-components/mui/checkbox';
const [accepted, setAccepted] = useState(false);

<MUICheckbox
  fieldName="terms"
  value={accepted}
  onValueChange={({ newValue, event }) => setAccepted(newValue)}
  label="I accept the terms and conditions"
/>

value is a boolean, and undefined counts as unchecked. onValueChange receives { newValue, event }: the next checked state and the change event. The label defaults to text generated from fieldName, so terms becomes "Terms", and hideLabel removes the visible label.

Label and placement

label accepts any ReactNode, so it can hold a link, such as one to the terms. The label sits after the checkbox by default. formControlLabelProps is forwarded to the FormControlLabel around the checkbox, so labelPlacement can move it to the 'start', 'top' or 'bottom'. Its sx is merged with the default FormControlLabel styles from ConfigProvider. The component controls the FormControlLabel's control, label and disabled.

<MUICheckbox
  fieldName="terms"
  value={accepted}
  onValueChange={({ newValue }) => setAccepted(newValue)}
  label={<>I accept the <a href="/terms">terms and conditions</a></>}
  formControlLabelProps={{
    labelPlacement: 'start',
    sx: { justifyContent: 'space-between', ml: 0 }
  }}
/>

Styling the checkbox

The remaining CheckboxProps are passed to the Checkbox, for example color, size, sx, and custom icon and checkedIcon. slotProps is forwarded too. The checkbox's id, name, checked, disabled and onChange are managed by the component, so setting them has no effect.

import FavoriteBorderIcon from '@mui/icons-material/FavoriteBorder';
import FavoriteIcon from '@mui/icons-material/Favorite';

<MUICheckbox
  fieldName="favourite"
  value={favourite}
  onValueChange={({ newValue }) => setFavourite(newValue)}
  color="error"
  size="small"
  icon={<FavoriteBorderIcon />}
  checkedIcon={<FavoriteIcon />}
/>

The indeterminate prop shows the dash icon, which is useful for a "select all" box that controls other checkboxes. It only changes how the checkbox looks, and value still decides whether it is checked.

Required, helper text and errors

required marks the underlying input as required, so the browser's own validation blocks a form submit while it is unchecked. For your own validation, set errorMessage from a rule, such as accepting the terms. The message replaces the helperText while it is shown.

<MUICheckbox
  fieldName="terms"
  value={accepted}
  onValueChange={({ newValue }) => setAccepted(newValue)}
  label="I accept the terms and conditions"
  required
  helperText="Required to continue"
  errorMessage={submitted && !accepted
    ? 'You must accept the terms'
    : undefined
  }
/>

API

MUICheckboxProps also accepts most CheckboxProps.

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.
valueboolean
Current checked state. undefined/false are treated as unchecked.
onValueChange*({ newValue, event }) => void
Called on every toggle with the next checked state and the original change event.
labelReactNode
Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name".
formControlLabelPropsFormControlLabelProps
FormControlLabelProps forwarded to the internal FormControlLabel. Multiple fields can be configured using the ConfigProvider component.
hideLabelboolean
When true, hides the rendered field label while preserving accessible labeling where possible.
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

Driven by plain React state — a custom label, pass-through CheckboxProps (color / size), helperText, and a required checkbox with a custom renderError.

Basic checkbox with helper text

Get our monthly product newsletter

Custom label, colour & size (CheckboxProps)

Required checkbox with custom error render

Form State - Values & Errors

Reference

Source Code

View the full implementation of this component on GitHub.