MUIRating
MUIRating wraps the Material UI
Rating star input. The value is a
number (or null when cleared).
Usage
import MUIRating, { MUIRatingProps } from '@nish1896/mui-components/mui/rating';const [score, setScore] = useState<number | null>(null);
<MUIRating
fieldName="score"
value={score}
onValueChange={({ newValue, event }) => setScore(newValue)}
/>value is a number, or null when there is no rating. onValueChange
receives { newValue, event }, and newValue is null when the user
clears the rating by clicking the selected star again.
Number of stars and precision
The remaining RatingProps
are passed through. max sets how many stars are shown, which is 5
by default, precision sets the smallest step that can be chosen,
and size scales the stars. Use precision={0.5} to allow half stars.
<MUIRating
fieldName="score"
value={score}
onValueChange={({ newValue }) => setScore(newValue)}
max={10}
precision={0.5}
size="large"
/>Custom icons
icon replaces the filled icon, and emptyIcon replaces the empty one.
Give the icons fontSize="inherit" so that size still applies.
import FavoriteIcon from '@mui/icons-material/Favorite';
import FavoriteBorderIcon from '@mui/icons-material/FavoriteBorder';
<MUIRating
fieldName="love"
value={love}
onValueChange={({ newValue }) => setLove(newValue)}
icon={<FavoriteIcon fontSize="inherit" />}
emptyIcon={<FavoriteBorderIcon fontSize="inherit" />}
sx={{ color: 'error.main' }}
/>Read-only and disabled
readOnly shows a rating that the user can't change, which suits
displaying an average. disabled dims the control and blocks input.
<MUIRating
fieldName="average"
value={4.5}
onValueChange={() => undefined}
precision={0.5}
readOnly
/>Label placement
A rating has no inline label, so showLabelAboveFormField defaults to true
and the label is shown above the stars. Pass false to hide the visible label.
API
MUIRatingProps also accepts most
RatingProps.
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 | number | null | Current rating value. undefined/null are treated as no rating selected. |
onValueChange* | ({ newValue, event }) => void | Called on every rating change. newValue is null when the rating is cleared. |
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 — pass-through RatingProps (precision, max,
size), a label above the control, and required validation via errorMessage.
Reference
Source Code
View the full implementation of this component on GitHub.