Rating API

API documentation for Rating component

RatingRoot#

Props#

Defines valid properties in Rating component.

Prop	Default	Type
`ref`	—	`Ref<unknown>`
The reference to the component instance.
`pIf`	`true`	`boolean`
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`	`false`	`boolean`
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`	`0`	`number`
The default value of the rating.
`allowHalf`	`true`	`boolean`
Whether to allow half stars.
`name`	—	`string`
Name used for the hidden radio inputs. Auto-generated if not provided.
`orientation`	`'horizontal'`	`"horizontal"` \| `"vertical"`
The orientation of the rating.
`disabled`	`false`	`boolean`
When present, it specifies that the element should be disabled.
`readOnly`	`false`	`boolean`
When present, it specifies that component is read-only.
`invalid`	`false`	`boolean`
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.

State#

Defines valid state in Rating component.

Prop	Type
`value`	`number`
The current value of the rating.
`hovering`	`boolean`
Whether the rating is in a hover state.
`hoveringValue`	`number`
The value currently being hovered over.

Exposes#

Defines the methods and properties exposed by Rating component.

Prop	Type
`state`	`useRatingState`
Current state of the rating.
`inputName`	`string`
The computed name used for radio inputs (from props.name or auto-generated). Named 'inputName' to avoid collision with withComponent's common.name.
`rootProps`	`useRatingRootProps`
Pre-built props for the root element (data attributes + event handlers).
`updateValue`	`(event: SyntheticEvent, value: number) => void`
Update the rating value.
`setHoveringValue`	`(value: number) => void`
Set the hover value (called by On/Off on pointer move).
`resolvePointerValue`	`(e: MouseEvent<Element, MouseEvent>` \| `PointerEvent<Element>, optionEl: Element, idx: number) => number`
Resolves the value to set from a pointer event, taking allowHalf and element position into account.
`optionProps`	`useRatingRootProps`
Pre-built data attribute props for the option element.
`onProps`	`useRatingRootProps`
Pre-built data attribute props for the on-icon element.
`offProps`	`useRatingRootProps`
Pre-built data attribute props for the off-icon element.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of Rating component.

Prop	Type
`root`	`RatingRootPassThroughType<HTMLAttributes<HTMLDivElement>>`
Used to pass attributes to the root's DOM element.
`option`	`RatingRootPassThroughType<HTMLAttributes<HTMLDivElement>>`
Used to pass attributes to each option element.
`onIcon`	`RatingRootPassThroughType<HTMLAttributes<HTMLDivElement>>`
Used to pass attributes to the on-icon (filled) overlay element.
`offIcon`	`RatingRootPassThroughType<HTMLAttributes<HTMLDivElement>>`
Used to pass attributes to the off-icon (empty) base element.
`halfInput`	`RatingRootPassThroughType<InputHTMLAttributes<HTMLInputElement>>`
Used to pass attributes to the half-value sr-only radio input.
`fullInput`	`RatingRootPassThroughType<InputHTMLAttributes<HTMLInputElement>>`
Used to pass attributes to the full-value sr-only radio input.

Types#

Instance

Instance of Rating component.

Values
`ComponentInstance<RatingRootProps, RatingRootState, RatingRootExposes>`

RatingOption#

Props#

Defines valid properties in RatingOption component.

Prop	Default	Type
`ref`	—	`Ref<unknown>`
The reference to the component instance.
`pIf`	`true`	`boolean`
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`	`false`	`boolean`
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.

Exposes#

Defines the methods and properties exposed by RatingOption component.

Prop	Type
`state`	`useRatingOptionState`
Current state of this option.
`optionRef`	`RefObject<Element>`
Ref to the option's root DOM element, used internally for pointer position calculations.
`optionProps`	`Record<string, string` \| `number>`
Pre-built data attribute props for the option element.
`onIconProps`	`{ onMouseDown: (e: MouseEvent) => void; onPointerMove: (e: PointerEvent) => void; onClick: (e: MouseEvent) => void }`
Pre-built interaction props for the on-icon element.
`offIconProps`	`{ onMouseDown: (e: MouseEvent) => void; onPointerMove: (e: PointerEvent) => void; onClick: (e: MouseEvent) => void }`
Pre-built interaction props for the off-icon element.
`onPointerMove`	`(e: PointerEvent) => void`
Handle pointer move on On/Off elements (resolves half/full value and sets hovering value).
`onClick`	`(e: MouseEvent) => void`
Handle click on On/Off elements (resolves half/full value and updates value).
`onMouseDown`	`(e: MouseEvent) => void`
Prevent default on mouse down (avoids focus shift).
`halfInputProps`	`InputHTMLAttributes<HTMLInputElement>`
Pre-built props for the half-value sr-only radio input. Null when allowHalf is false.
`fullInputProps`	`InputHTMLAttributes<HTMLInputElement>`
Pre-built props for the full-value sr-only radio input.
`rating`	`RatingRootInstance`
The parent Rating component instance.

Interfaces#

PassThroughOptions

Defines passthrough(pt) options of RatingOption component.

Prop	Type
`root`	`RatingOptionPassThroughType<HTMLAttributes<HTMLDivElement>>`
Used to pass attributes to the root's DOM element.

Types#

Instance

Instance of RatingOption component.

Values
`ComponentInstance<RatingOptionProps, RatingOptionState, RatingOptionExposes>`

useRating#

Props#

Defines valid properties in useRating.

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

State#

Defines valid state in useRating.

Prop	Type
`value`	`number`
The current value of the rating.
`hovering`	`boolean`
Whether the rating is in a hover state.
`hoveringValue`	`number`
The value currently being hovered over.

Exposes#

Defines the methods and properties exposed by useRating.

Prop	Type
`state`	`useRatingState`
Current state of the rating.
`inputName`	`string`
The computed name used for radio inputs (from props.name or auto-generated). Named 'inputName' to avoid collision with withComponent's common.name.
`rootProps`	`useRatingRootProps`
Pre-built props for the root element (data attributes + event handlers).
`updateValue`	`(event: SyntheticEvent, value: number) => void`
Update the rating value.
`setHoveringValue`	`(value: number) => void`
Set the hover value (called by On/Off on pointer move).
`resolvePointerValue`	`(e: MouseEvent<Element, MouseEvent>` \| `PointerEvent<Element>, optionEl: Element, idx: number) => number`
Resolves the value to set from a pointer event, taking allowHalf and element position into account.
`optionProps`	`useRatingRootProps`
Pre-built data attribute props for the option element.
`onProps`	`useRatingRootProps`
Pre-built data attribute props for the on-icon element.
`offProps`	`useRatingRootProps`
Pre-built data attribute props for the off-icon element.

Interfaces#

Events#

useRatingValueChangeEvent

Event fired when the rating value changes.

Prop	Type
`originalEvent`	`E`
The original event that triggered the change.
`value`	`number`
The new rating value.

Types#

Instance

Instance of useRating headless.

Values
`HeadlessInstance<useRatingProps, useRatingState, useRatingExposes>`