Rating

An unstyled, accessible rating component with compound composition for star-based selection input.

Build fully custom rating controls with complete control over layout and styling.

Pre-styled Versions

Choose a pre-styled library to use Rating with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with four sub-components: Root, Option, On, Off
Half-star support with allowHalf prop
Horizontal and vertical orientation
Controlled and uncontrolled value management

Usage#

import { Rating } from 'primereact/rating';

<Rating.Root defaultValue={3}>
    {Array(5)
        .fill(null)
        .map((_, i) => (
            <Rating.Option key={i} index={i}>
                <Rating.On>
                    <StarFill />
                </Rating.On>
                <Rating.Off>
                    <Star />
                </Rating.Off>
            </Rating.Option>
        ))}
</Rating.Root>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element.

<Rating.Root as="div">
    <Rating.Option as="div" index={0}>
        <Rating.On as="div" />
        <Rating.Off as="div" />
    </Rating.Option>
</Rating.Root>

Default element: span for all sub-components.

Render Function Children#

Rating.On and Rating.Off accept a render function as children, providing access to the component instance.

<Rating.On>{(instance) => <span>{instance.ratingOption?.state.highlighted ? 'filled' : ''}</span>}</Rating.On>

API#

RatingRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: RatingRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: RatingRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`RatingRootInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<RatingRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: RatingRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`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.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"rating"`
`data-part`	`"root"`
`data-orientation`	`"horizontal"` or `"vertical"`
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only
`data-invalid`	Present when invalid

RatingOption#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: RatingOptionInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: RatingOptionInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`RatingOptionInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<RatingOptionPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: RatingOptionInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`index`	`number`	—
The zero-based index of this option within the rating.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"rating"`
`data-part`	`"option"`
`data-orientation`	`"horizontal"` or `"vertical"`
`data-index`	Zero-based option index
`data-highlighted`	Present when filled
`data-half`	Present when half-filled
`data-checked`	Present when active
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only

RatingOn#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: RatingOnInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: RatingOnInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`RatingOnInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<RatingOnPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: RatingOnInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"rating"`
`data-part`	`"option-on"`
`data-orientation`	`"horizontal"` or `"vertical"`
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only

RatingOff#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: RatingOffInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: RatingOffInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`RatingOffInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<RatingOffPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: RatingOffInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-scope`	`"rating"`
`data-part`	`"option-off"`
`data-orientation`	`"horizontal"` or `"vertical"`
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only

Accessibility#

Rating.Option renders hidden native <input type="radio"> elements that form a radio group. Screen readers announce each option as a radio button with its value. When allowHalf is enabled, both half and full value radios are rendered per option.

Keyboard Support#

Key	Function
`tab`	Moves focus to the star representing the value, if there is none then first star receives the focus.
`left arrow` `up arrow`	Moves focus to the previous star.
`right arrow` `down arrow`	Moves focus to the next star.
`space`	If the focused star does not represent the value, changes the value to the star value.