Rating

Rating lets users select a score on a visual scale. It supports product reviews, satisfaction scores, quality indicators, and read-only summaries.

Basic usageCopy Anchor Link

import { Rating } from '@mosmox/ui';

<Rating aria-label="Product rating" defaultValue={4} />

The default scale contains five stars. Change the number of options with max.

<Rating max={10} defaultValue={8} aria-label="Score out of ten" />

Controlled valueCopy Anchor Link

Use value and onChange when the parent owns the score. The callback receives a number or null when the value is cleared.

const [rating, setRating] = useState<number | null>(null);

<Rating value={rating} onChange={setRating} aria-label="Rate this answer" />

Use defaultValue for an uncontrolled component. When allowClear is enabled, clicking the selected value again clears it.

Half values and hover previewCopy Anchor Link

Set allowHalf to allow values such as 3.5. Pointer position inside a star chooses the lower or upper half. onHover can be used to show a live preview or helper text.

<Rating allowHalf defaultValue={3.5} onHover={(value) => console.log('Preview:', value)} showValue />

Labels and formattingCopy Anchor Link

Use label for visible context and showValue to display the current score. valueFormatter customizes the displayed text.

<Rating defaultValue={4} label="Customer satisfaction" showValue valueFormatter={(value, max) => `${value} of ${max}`} />

Sizes, tones, and iconsCopy Anchor Link

size accepts xs (extra small), sm (small), and default. tone accepts primary, warning, success, danger, and inherit.

The filled star color is controlled by tone: warning is orange, success is green, primary uses the primary theme color, and danger is red. Use inherit with a custom class or CSS variable (--mm-rating-color) when a custom color is needed; there is no separate color prop.

<Rating size="xs" tone="primary" defaultValue={4} />
<Rating size="sm" tone="success" defaultValue={5} />
<Rating icon="◆" emptyIcon="◇" max={10} defaultValue={8} />

icon and emptyIcon accept any React node, including custom SVG icons, emojis, and branded shapes.

Read-only and statesCopy Anchor Link

Use readOnly for a score that should be visible but not changed. disabled prevents interaction and applies muted styling. loading disables the control and shows a status spinner while a save operation is in progress.

<Rating defaultValue={4.5} allowHalf readOnly showValue />
<Rating defaultValue={2} disabled />
<Rating defaultValue={3} loading label="Saving rating" />

These states are mutually readable from the rendered control: readOnly keeps the score visible without interaction, while disabled and loading disable the star buttons. A controlled value={null} or an uncontrolled defaultValue={0} displays no selected stars.

Keyboard and accessibilityCopy Anchor Link

The control is exposed as a radio group. Each star has an accessible position label. After focusing a star, Arrow Right/Up increases the value, Arrow Left/Down decreases it, Home sets zero, End sets the maximum, and Space selects the focused value.

Always provide a meaningful aria-label when the visible label does not describe what is being rated.

APICopy Anchor Link