Rating

import Rating from 'frui/field/Rating';

Copy

Props

The Rating component wraps visually hidden radio inputs for accessibility and form integration. It accepts the following specific props:

Name	Type	Required	Notes
name	string	No	Name attribute for the radio inputs (form submission). Auto-generated if not provided.
value	number \| null	No	The rating value for controlled mode.
defaultValue	number \| null	No (Defaults to null)	The initial rating value for uncontrolled mode.
max	number	No (Defaults to 5)	The maximum rating value (number of icons).
onChange	Function	No	Callback fired when the value changes. `(event, value) => void`
onChangeActive	Function	No	Callback fired when the mouse hovers over a rating icon. `(event, value) => void`
readOnly	boolean	No (Defaults to false)	If true, the rating cannot be changed.
disabled	boolean	No (Defaults to false)	If true, the rating is disabled (visual state and interaction).
size	'small' \| 'medium' \| 'large'	No (Defaults to medium)	The size of the rating icons.
icon	ReactNode	No	The icon to display as the filled state.
emptyIcon	ReactNode	No	The icon to display as the empty state (defaults to faded filled icon).
getLabelText	Function	No	Generates aria-label text for accessibility. `(value) => string`
highlightSelectedOnly	boolean	No (Defaults to false)	If true, only the selected icon will be highlighted, not the preceding ones.
className	string	No	Standard HTML class names for the root span element.
style	CSS Object	No	Standard CSS object for inline styles on the root span element.

Basics

By default, the Rating component is uncontrolled. Use defaultValue to set an initial value. It renders 5 stars.

Controlled

For a controlled component, use the value, and onChange props, typically with React state.

function ControlledRatingExample() {
  const [controlledValue, setControlledValue] = useState<number | null>(2);

  return (
    <Rating
      name="controlled-rating"
      value={controlledValue}
      onChange={(event, newValue) => {
        setControlledValue(newValue);
        console.log('Controlled Change:', newValue);
      }}
    />
  );
}

Copy

Sizes

Use the size prop to adjust the icon size. The sizes correspond to CSS classes .frui-rating-sizeSmall, .frui-rating-sizeMedium, and .frui-rating-sizeLarge.

Custom Icons

Provide custom React nodes to the icon (filled) and emptyIcon props. If emptyIcon is not provided, a faded version of the icon is used. Styles target .frui-rating-icon-filled, and .frui-rating-icon-empty.

// Define custom icons (examples)
const HeartIcon = (props) => (/* SVG code */);
const CircleIcon = (props) => (/* SVG code */);

// Use in Rating
<Rating
  defaultValue={3}
  icon={<HeartIcon />}
  emptyIcon={<HeartIcon style={{ opacity: 0.3 }} />}
  max={5}
/>

<Rating
  defaultValue={4}
  icon={<CircleIcon />}
  emptyIcon={<CircleIcon style={{ opacity: 0.3 }} />}
  max={6}
/>

Copy

Highlighting

By default, all icons up to the selected/hovered value are filled. Use highlightSelectedOnly to only fill the single selected/hovered icon.

{/* Default: Icons 1, 2, 3 are filled */}
<Rating defaultValue={3} />

{/* highlightSelectedOnly: Only icon 3 is filled */}
<Rating defaultValue={3} highlightSelectedOnly />

Copy

Read Only & Disabled

Use readOnly to display a rating that cannot be changed by the user ( .frui-rating-readOnly class). Use disabled to prevent interaction and apply disabled styling ( .frui-rating-disabled class).

Events

The onChange callback fires when a rating is selected. The onChangeActive callback fires when the mouse enters or leaves an icon, providing the hovered value (or null). Hover styles are mainly handled via CSS ( .frui-rating-icon-hover).

<Rating
  name="event-rating"
  defaultValue={1}
  onChange={(event, value) => alert(`onChange: Value ${value} selected!`)}
  onChangeActive={(event, value) => console.log(`onChangeActive: Hovered ${value}`)}
/>

Copy

onChange

The onChange event is triggered when the user clicks an icon to change the rating. The following arguments are passed to the event handler:

Name	Type	Description
`event`	`ChangeEvent<HTMLInputElement>`	The change event on the underlying radio input.
`value`	`number \| null`	The newly selected rating value.

onChangeActive

The onChangeActive event is triggered when the mouse pointer enters or leaves an icon. The following arguments are passed to the event handler:

Name	Type	Description
`event`	`MouseEvent`	The native mouse event.
`value`	`number \| null`	The value of the icon being hovered, or null if the mouse leaves the component.

You can add custom CSS classes via the className prop or inline styles via the style prop to the root .frui-rating-root element. Component-specific classes like .frui-rating-icon, .frui-rating-icon-filled, .frui-rating-icon-empty, .frui-rating-icon-hover, .frui-rating-icon-active, and size/state classes are available for more targeted styling.

Radio

Select