MUISwitch
MUISwitch is a single Switch
with a boolean value, an inline label, and optional helper text or
error state.
Usage
import MUISwitch, { MUISwitchProps } from '@nish1896/mui-components/mui/switch';const [enabled, setEnabled] = useState(false);
<MUISwitch
fieldName="notifications"
value={enabled}
onValueChange={({ newValue, event }) => setEnabled(newValue)}
label="Email notifications"
/>value is a boolean, and undefined counts as off. onValueChange
receives { newValue, event }: the next checked state and the change
event. The label defaults to text generated from fieldName, so
notifications becomes "Notifications", and hideLabel removes the
visible label.
Label and placement
label accepts any ReactNode. The label sits after the switch by
default. formControlLabelProps is forwarded to the FormControlLabel
around the switch, 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.
<MUISwitch
fieldName="darkMode"
value={darkMode}
onValueChange={({ newValue }) => setDarkMode(newValue)}
label="Dark mode"
formControlLabelProps={{
labelPlacement: 'start',
sx: { justifyContent: 'space-between', ml: 0 }
}}
/>Styling the switch
The remaining SwitchProps
are passed to the Switch, for example color, size, edge and
sx. slotProps is forwarded too. name, value, checked,
defaultChecked and onChange are managed by the component, so they
can't be set.
<MUISwitch
fieldName="notifications"
value={enabled}
onValueChange={({ newValue }) => setEnabled(newValue)}
color="secondary"
size="small"
/>Helper text and errors
A switch can't be invalid by itself, so set errorMessage from your
own rule. The message replaces the helperText while it is shown.
<MUISwitch
fieldName="acceptTerms"
value={accepted}
onValueChange={({ newValue }) => setAccepted(newValue)}
label="I accept the terms"
helperText="Required to continue"
errorMessage={submitted && !accepted ? 'You must accept the terms' : undefined}
/>API
MUISwitchProps also accepts most
SwitchProps.
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. |
value | boolean | 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. |
label | ReactNode | Label displayed for the field. Defaults to a human-readable label derived from fieldName, e.g. firstName becomes "First Name". |
formControlLabelProps | FormControlLabelProps | FormControlLabelProps forwarded to the internal FormControlLabel. Multiple fields can be configured using the ConfigProvider component. |
hideLabel | boolean | When true, hides the rendered field label while preserving accessible labeling where possible. |
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 — exercises a custom label,
formControlLabelProps (label placement), pass-through SwitchProps (color /
size), helperText, and a required toggle with a custom renderError and
customIds.
Reference
Source Code
View the full implementation of this component on GitHub.