useRating

Hooks that manage rating state, hover interactions, and value resolution for star-based selection input.

Usage#

import { useRating } from '@primereact/headless/rating';
import { useRatingOption } from '@primereact/headless/rating';
 
const rating = useRating({ defaultValue: 3 });
const option = useRatingOption({ index: 0, context: rating });
 
return (
    <div {...rating.rootProps}>
        <div ref={option.optionRef} {...rating.optionProps} {...option.optionProps}>
            <input {...option.fullInputProps} className="sr-only" />
            <div {...rating.onProps} {...option.onIconProps}>
                filled icon
            </div>
            <div {...rating.offProps} {...option.offIconProps}>
                empty icon
            </div>
        </div>
    </div>
);

useRating manages root-level state (value, hovering) while useRatingOption manages per-option state (highlighted, half, checked) and interactions — see Primitive for a component-based API.

Features#

Returns spread-ready prop objects (rootProps, optionProps, onProps, offProps)
useRatingOption returns per-option props (optionProps, onIconProps, offIconProps, halfInputProps, fullInputProps)
Controlled and uncontrolled value state
Half-star support via allowHalf
Horizontal and vertical orientation
Hover preview with state.hovering and state.hoveringValue

Behavior#

Default Value#

Use defaultValue to set the initial value.

const rating = useRating({ defaultValue: 3.5 });

Controlled#

Use value and onValueChange for full programmatic control.

const [value, setValue] = React.useState(3);
const rating = useRating({
    value,
    onValueChange: (e) => setValue(e.value)
});

The onValueChange callback receives { originalEvent, value } where value is the new numeric rating.

Half Stars#

Set allowHalf to enable half-star selection. When enabled, useRatingOption returns halfInputProps for the half-value radio input.

const rating = useRating({ allowHalf: true });
const option = useRatingOption({ index: 0, context: rating });
 
// option.halfInputProps is non-null when allowHalf is true
// option.state.half is true when this option is half-filled

Disabled#

Set disabled to prevent interaction. All prop objects include data-disabled.

const rating = useRating({ disabled: true });

Read Only#

Set readOnly to prevent value changes while keeping the component focusable.

const rating = useRating({ readOnly: true });

Vertical Orientation#

Set orientation to "vertical" for vertical layout. Half-star detection uses the vertical axis. All prop objects include data-orientation.

const rating = useRating({ orientation: 'vertical' });

Custom Styling with Data Attributes#

Every prop object includes data-scope="rating" and a data-part attribute. State-dependent attributes are added automatically.

[data-scope='rating'][data-part='root'] {
    display: inline-flex;
}
 
[data-scope='rating'][data-part='root'][data-orientation='vertical'] {
    flex-direction: column;
}
 
[data-scope='rating'][data-part='option'][data-highlighted] {
    /* option is fully or partially filled */
}
 
[data-scope='rating'][data-part='option'][data-half] {
    /* option is half-filled */
}
 
[data-scope='rating'][data-part='option'][data-checked] {
    /* option is the active one */
}
 
[data-scope='rating'][data-part='root'][data-disabled] {
    opacity: 0.5;
    cursor: not-allowed;
}

API#

useRating#

Name	Type	Default
`value`	`number`	—
Value of the rating.
`defaultValue`	`number`	`0`
The default value of the rating.
`allowHalf`	`boolean`	`true`
Whether to allow half stars.
`name`	`string`	—
Name used for the hidden radio inputs. Auto-generated if not provided.
`orientation`	`"horizontal"` \| `"vertical"`	`'horizontal'`
The orientation of the rating.
`disabled`	`boolean`	`false`
When present, it specifies that the element should be disabled.
`readOnly`	`boolean`	`false`
When present, it specifies that component is read-only.
`invalid`	`boolean`	`false`
When present, it specifies that the component should have invalid state style.
`onValueChange`	`(event: useRatingValueChangeEvent) => void`	—
Callback fired when the value changes.

useRatingOption#

Name	Type	Default
`index`	`number`	—
The zero-based index of this option within the rating.
`context`	`useRatingInstance`	—
The parent useRating instance providing state and methods.

Accessibility#

See Rating Primitive for WAI-ARIA compliance details and keyboard support.