Rating Group

Allows users to rate items using a set of icons.

Label

Anatomy

<RatingGroup.Root>
  <RatingGroup.Label />
  <RatingGroup.Control>
    <RatingGroup.Item>
      <RatingGroup.ItemContext />
    </RatingGroup.Item>
    <RatingGroup.HiddenInput />
  </RatingGroup.Control>
</RatingGroup.Root>

Examples

Controlled

When using the RatingGroup component, you can use the value and onValueChange props to control the state.

Root Provider

An alternative way to control the rating group is to use the RootProvider component and the useRatingGroup hook. This way you can access the state and methods from outside the component.

Field

The Field component helps manage form-related state and accessibility attributes of a rating group. It includes handling ARIA labels, helper text, and error text to ensure proper accessibility.

Half Rating

Allow 0.5 value steps by setting the allowHalf prop to true. Ensure to render the correct icon if the half value is set in the Rating components render callback.

Forms

To use the rating group within forms, pass the prop name. It will render a hidden input and ensure the value changes get propagated to the form correctly.

Disabled

To make the rating group disabled, set the disabled prop to true.

API Reference

Props

Root

Renders a <div> element.

Prop	Default	Type
`allowHalf`		`boolean` Whether to allow half stars.
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`autoFocus`		`boolean` Whether to autofocus the rating.
`count`	`5`	`number` The total number of ratings.
`defaultValue`		`number` The initial value of the rating when rendered. Use when you don't need to control the value of the rating.
`disabled`		`boolean` Whether the rating is disabled.
`form`		`string` The associate form of the underlying input element.
`id`		`string` The unique identifier of the machine.
`ids`		`Partial<{ root: string label: string hiddenInput: string control: string item: (id: string) => string }>` The ids of the elements in the rating. Useful for composition.
`name`		`string` The name attribute of the rating element (used in forms).
`onHoverChange`		`(details: HoverChangeDetails) => void` Function to be called when the rating value is hovered.
`onValueChange`		`(details: ValueChangeDetails) => void` Function to be called when the rating value changes.
`readOnly`		`boolean` Whether the rating is readonly.
`required`		`boolean` Whether the rating is required.
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`value`		`number` The controlled value of the rating

Control

Renders a <div> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	rating-group
`[data-part]`	control
`[data-readonly]`	Present when read-only
`[data-disabled]`	Present when disabled

HiddenInput

Renders a <input> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Item

Renders a <span> element.

Prop	Default	Type
`index`		`number`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	rating-group
`[data-part]`	item
`[data-disabled]`	Present when disabled
`[data-readonly]`	Present when read-only
`[data-checked]`	Present when checked
`[data-highlighted]`	Present when highlighted
`[data-half]`

Label

Renders a <label> element.

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Attribute	Description
`[data-scope]`	rating-group
`[data-part]`	label
`[data-disabled]`	Present when disabled
`[data-required]`	Present when required

RootProvider

Renders a <div> element.

Prop	Default	Type
`value`		`UseRatingGroupReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Context

API

Property	Type
`setValue`	`(value: number) => void` Sets the value of the rating group
`clearValue`	`VoidFunction` Clears the value of the rating group
`hovering`	`boolean` Whether the rating group is being hovered
`value`	`number` The current value of the rating group
`hoveredValue`	`number` The value of the currently hovered rating
`count`	`number` The total number of ratings
`items`	`number[]` The array of rating values. Returns an array of numbers from 1 to the max value.
`getItemState`	`(props: ItemProps) => ItemState` Returns the state of a rating item

Accessibility

Keyboard Support

Key	Description
`ArrowRight`	Moves focus to the next star, increasing the rating value based on the `allowHalf` property.
`ArrowLeft`	Moves focus to the previous star, decreasing the rating value based on the `allowHalf` property.
`Enter`	Selects the focused star in the rating group.