Rating

Import

import { Rating, RatingParts } from '@cerberus/react'

Usage

The Rating component is an abstracted client component that provides a way to select a value from a range of values. It is used to provide feedback on a scale. The default count is 5, and the default value is 0.

Loading example...

Readonly State

To render the Rating component in a read-only state, you can use the readOnly prop.

Loading example...

Orientation

The Rating component supports two layout orientations for label usage: horizontal, and vertical. The default orientation is vertical.

Loading example...

Sizes

The Rating component supports two sizes: sm, and md. The default size is sm.

Loading example...

Customizing

To customize the Rating component use style props or the Primitive components.

Loading example...

Primitives

You can utilize the primitive components or the css prop to customize the radio.

Component	Description
`RatingRoot`	The context provider for the Rating parts
`RatingLabel`	The label of the rating
`RatingControl`	The visual control of the rating
`RatingContext`	The context provider for the rating
`RatingItem`	The container of the rating item
`RatingItemContext`	The context provider for a rating item
`RatingHiddenInput`	The native input for the rating

API

Root

Props

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

Control

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

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

HiddenInput

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Item

Props

Prop	Type	Required	Default	Description
`index`	`number`	true	`undefined`	undefined
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`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

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	rating-group
`data-part`	label
`data-disabled`	Present when disabled
`data-required`	Present when required

RootProvider

Props

Prop	Type	Required	Default	Description
`value`	`UseRatingGroupReturn`	true	`undefined`	undefined
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Context

API:

Property	Type	Description
`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.

Import

import { Rating, RatingParts } from '@cerberus/react'

Usage

Loading example...

Readonly State

To render the Rating component in a read-only state, you can use the readOnly prop.

Loading example...

Orientation

The Rating component supports two layout orientations for label usage: horizontal, and vertical. The default orientation is vertical.

horizontal orientation

vertical orientation

Loading example...

Sizes

The Rating component supports two sizes: sm, and md. The default size is sm.

sm orientation

md orientation

Loading example...

Customizing

To customize the Rating component use style props or the Primitive components.

This is a custom rating

Loading example...

Primitives

You can utilize the primitive components or the css prop to customize the radio.

Component	Description
`RatingRoot`	The context provider for the Rating parts
`RatingLabel`	The label of the rating
`RatingControl`	The visual control of the rating
`RatingContext`	The context provider for the rating
`RatingItem`	The container of the rating item
`RatingItemContext`	The context provider for a rating item
`RatingHiddenInput`	The native input for the rating

API

Root

Props

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

Control

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

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

HiddenInput

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Item

Props

Prop	Type	Required	Default	Description
`index`	`number`	true	`undefined`	undefined
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`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

Props

Prop	Type	Required	Default	Description
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Data Attributes

Attribute	Description / Value
`data-scope`	rating-group
`data-part`	label
`data-disabled`	Present when disabled
`data-required`	Present when required

RootProvider

Props

Prop	Type	Required	Default	Description
`value`	`UseRatingGroupReturn`	true	`undefined`	undefined
`asChild`	`boolean`	false	`undefined`	Use the provided child element as the default rendered element, combining their props and behavior.

Context

API:

Property	Type	Description
`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.