Rating Group

Allows users to rate items using a set of icons.

Import

ts
import { RatingGroup } from "@kobalte/core/rating-group";
// or
import { Root, Label, ... } from "@kobalte/core/rating-group";

ts
import { RatingGroup } from "@kobalte/core/rating-group";
// or
import { Root, Label, ... } from "@kobalte/core/rating-group";

Features

Precise ratings with half-value increments.
Syncs with form reset events.
Group and rating labeling support for assistive technology.
Can be controlled or uncontrolled.

Anatomy

The rating group consists of:

RatingGroup: The root container for the rating group.
RatingGroup.Control: The container for the rating items.
RatingGroup.Label: The label that gives the user information on the rating group.
RatingGroup.HiddenInput: The native html input that is visually hidden in the rating group.
RatingGroup.Description: The description that gives the user more information on the rating group.
RatingGroup.ErrorMessage: The error message that gives the user information about how to fix a validation error on the rating group.

The rating item consists of:

RatingGroup.Item: The root container for a rating item.
RatingGroup.ItemControl: The element that visually represents a rating item.
RatingGroup.ItemLabel: The label that gives the user information on the rating item.
RatingGroup.ItemDescription: The description that gives the user more information on the rating item.

tsx
<RatingGroup>
	<RatingGroup.Label />
	<RatingGroup.Control>
        <RatingGroup.Item>
            <RatingGroup.ItemControl />
            <RatingGroup.ItemLabel />
            <RatingGroup.ItemDescription />
        </RatingGroup.Item>
    <RatingGroup.Control>
	<RatingGroup.HiddenInput />
	<RatingGroup.Description />
	<RatingGroup.ErrorMessage />
</RatingGroup>

tsx
<RatingGroup>
	<RatingGroup.Label />
	<RatingGroup.Control>
        <RatingGroup.Item>
            <RatingGroup.ItemControl />
            <RatingGroup.ItemLabel />
            <RatingGroup.ItemDescription />
        </RatingGroup.Item>
    <RatingGroup.Control>
	<RatingGroup.HiddenInput />
	<RatingGroup.Description />
	<RatingGroup.ErrorMessage />
</RatingGroup>

Example

Rate Us:

Usage

Default value

An initial, uncontrolled value can be provided using the defaultValue prop.

tsx
<RatingGroup defaultValue={3}>
	<RatingGroup.Control>
		<Index each={Array(5)}>
			{_ => (
				<RatingGroup.Item>
					<RatingGroup.ItemControl>
						<StarIcon />
					</RatingGroup.ItemControl>
				</RatingGroup.Item>
			)}
		</Index>
	</RatingGroup.Control>
</RatingGroup>

tsx
<RatingGroup defaultValue={3}>
	<RatingGroup.Control>
		<Index each={Array(5)}>
			{_ => (
				<RatingGroup.Item>
					<RatingGroup.ItemControl>
						<StarIcon />
					</RatingGroup.ItemControl>
				</RatingGroup.Item>
			)}
		</Index>
	</RatingGroup.Control>
</RatingGroup>

Controlled value

The value prop can be used to make the value controlled. The onChange event is fired when the user selects a rating, and receives the new value.

Your rating is: 0/5

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal(0);
	return (
		<>
			<RatingGroup value={value()} onChange={setValue}>
				<RatingGroup.Control>
					<Index each={Array(5)}>
						{_ => (
							<RatingGroup.Item>
								<RatingGroup.ItemControl>
									<StarIcon />
								</RatingGroup.ItemControl>
							</RatingGroup.Item>
						)}
					</Index>
				</RatingGroup.Control>
			</RatingGroup>
			<p>Your rating is: {value()}/5</p>
		</>
	);
}

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal(0);
	return (
		<>
			<RatingGroup value={value()} onChange={setValue}>
				<RatingGroup.Control>
					<Index each={Array(5)}>
						{_ => (
							<RatingGroup.Item>
								<RatingGroup.ItemControl>
									<StarIcon />
								</RatingGroup.ItemControl>
							</RatingGroup.Item>
						)}
					</Index>
				</RatingGroup.Control>
			</RatingGroup>
			<p>Your rating is: {value()}/5</p>
		</>
	);
}

Half Ratings

Allow 0.5 value steps by setting the allowHalf prop to true.

tsx
<RatingGroup allowHalf>
	<RatingGroup.Control>
		<Index each={Array(5)}>
			{_ => (
				<RatingGroup.Item>
					<RatingGroup.ItemControl>
						{(state) => (state.half() ? <StarHalfIcon /> : <StarIcon />)}
					</RatingGroup.ItemControl>
				</RatingGroup.Item>
			)}
		</Index>
	</RatingGroup.Control>
</RatingGroup>

tsx
<RatingGroup allowHalf>
	<RatingGroup.Control>
		<Index each={Array(5)}>
			{_ => (
				<RatingGroup.Item>
					<RatingGroup.ItemControl>
						{(state) => (state.half() ? <StarHalfIcon /> : <StarIcon />)}
					</RatingGroup.ItemControl>
				</RatingGroup.Item>
			)}
		</Index>
	</RatingGroup.Control>
</RatingGroup>

Description

The RatingGroup.Description component can be used to associate additional help text with a rating group.

Rate Us:

Rate your experience with us.

tsx
<RatingGroup>
	<RatingGroup.Label>Rate Us:</RatingGroup.Label>
	<RatingGroup.Control>
		<Index each={Array(5)}>
			{_ => (
				<RatingGroup.Item>
					<RatingGroup.ItemControl>
						<StarIcon />
					</RatingGroup.ItemControl>
				</RatingGroup.Item>
			)}
		</Index>
	</RatingGroup.Control>
	<RatingGroup.Description>Rate your experience with us.</RatingGroup.Description>
</RatingGroup>

tsx
<RatingGroup>
	<RatingGroup.Label>Rate Us:</RatingGroup.Label>
	<RatingGroup.Control>
		<Index each={Array(5)}>
			{_ => (
				<RatingGroup.Item>
					<RatingGroup.ItemControl>
						<StarIcon />
					</RatingGroup.ItemControl>
				</RatingGroup.Item>
			)}
		</Index>
	</RatingGroup.Control>
	<RatingGroup.Description>Rate your experience with us.</RatingGroup.Description>
</RatingGroup>

Error message

The RatingGroup.ErrorMessage component can be used to help the user fix a validation error. It should be combined with the validationState prop to semantically mark the rating group as invalid for assistive technologies.

By default, it will render only when the validationState prop is set to invalid, use the forceMount prop to always render the error message (ex: for usage with animation libraries).

Rate Us:

Please select a rating between 1 and 5.

tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [value, setValue] = createSignal(0);
	return (
		<RatingGroup
			value={value()}
			onChange={setValue}
			validationState={value() === 0 ? "invalid" : "valid"}
		>
			<RatingGroup.Label>Rate Us:</RatingGroup.Label>
			<RatingGroup.Control>
				<Index each={Array(5)}>
					{_ => (
						<RatingGroup.Item>
							<RatingGroup.ItemControl>
								<StarIcon />
							</RatingGroup.ItemControl>
						</RatingGroup.Item>
					)}
				</Index>
			</RatingGroup.Control>
			<RatingGroup.ErrorMessage>Please select a rating between 1 and 5.</RatingGroup.ErrorMessage>
		</RatingGroup>
	);
}

tsx
import { createSignal } from "solid-js";
function ErrorMessageExample() {
	const [value, setValue] = createSignal(0);
	return (
		<RatingGroup
			value={value()}
			onChange={setValue}
			validationState={value() === 0 ? "invalid" : "valid"}
		>
			<RatingGroup.Label>Rate Us:</RatingGroup.Label>
			<RatingGroup.Control>
				<Index each={Array(5)}>
					{_ => (
						<RatingGroup.Item>
							<RatingGroup.ItemControl>
								<StarIcon />
							</RatingGroup.ItemControl>
						</RatingGroup.Item>
					)}
				</Index>
			</RatingGroup.Control>
			<RatingGroup.ErrorMessage>Please select a rating between 1 and 5.</RatingGroup.ErrorMessage>
		</RatingGroup>
	);
}

HTML forms

The name prop can be used for integration with HTML forms.

tsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};
	return (
		<form onSubmit={onSubmit}>
			<RatingGroup name="rate">
				<RatingGroup.Control>
					<Index each={Array(5)}>
						{_ => (
							<RatingGroup.Item>
								<RatingGroup.ItemControl>
									<StarIcon />
								</RatingGroup.ItemControl>
							</RatingGroup.Item>
						)}
					</Index>
				</RatingGroup.Control>
				<RatingGroup.HiddenInput />
			</RatingGroup>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}

tsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};
	return (
		<form onSubmit={onSubmit}>
			<RatingGroup name="rate">
				<RatingGroup.Control>
					<Index each={Array(5)}>
						{_ => (
							<RatingGroup.Item>
								<RatingGroup.ItemControl>
									<StarIcon />
								</RatingGroup.ItemControl>
							</RatingGroup.Item>
						)}
					</Index>
				</RatingGroup.Control>
				<RatingGroup.HiddenInput />
			</RatingGroup>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}

API Reference

RatingGroup

RatingGroup is equivalent to the Root import from @kobalte/core/rating-group.

Prop	Description
value	`number` The current rating value.
defaultValue	`number` The initial value of the rating group when it is first rendered. Use when you do not need to control the state of the rating group.
onChange	`(value: number) => void` Event handler called when the value changes.
allowHalf	`boolean` Whether to allow half ratings.
orientation	`'horizontal' \| 'vertical'` The axis the rating group items should align with.
name	`string` The name of the rating group. Submitted with its owning form as part of a name/value pair.
validationState	`'valid' \| 'invalid'` Whether the rating group should display its "valid" or "invalid" visual styling.
required	`boolean` Whether the user must select an item before the owning form can be submitted.
disabled	`boolean` Whether the rating group is disabled.
readOnly	`boolean` Whether the rating group items can be selected but not changed by the user.

Data attribute	Description
data-valid	Present when the rating group is valid according to the validation rules.
data-invalid	Present when the rating group is invalid according to the validation rules.
data-required	Present when the user must select a rating group item before the owning form can be submitted.
data-disabled	Present when the rating group is disabled.
data-readonly	Present when the rating group is read only.

RatingGroup.Label, RatingGroup.Description and RatingGroup.ErrorMesssage shares the same data-attributes.

RatingGroup.ErrorMessage

Prop	Description
forceMount	`boolean` Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries.

RatingGroup.ItemControl

Render Prop	Description
half	`Accessor<boolean>` Whether the rating item is half.
highlighted	`Accessor<boolean>` Whether the rating item is highlighted.

Data attribute	Description
data-valid	Present when the parent rating group is valid according to the validation rules.
data-invalid	Present when the parent rating group is invalid according to the validation rules.
data-required	Present when the parent rating group is required.
data-disabled	Present when the parent rating group is disabled.
data-readonly	Present when the parent rating group is read only.
data-checked	Present when the rating is checked.
data-half	Present when the rating is half.
data-highlighted	Present when the rating is highlighted.

RatingGroup.ItemLabel and RatingGroup.ItemDescription share the same data-attributes.

Rendered elements

Component	Default rendered element
`RatingGroup`	`div`
`RatingGroup.Control`	`div`
`RatingGroup.Label`	`span`
`RatingGroup.HiddenInput`	`input`
`RatingGroup.Description`	`div`
`RatingGroup.ErrorMessage`	`div`
`RatingGroup.Item`	`div`
`RatingGroup.ItemControl`	`div`
`RatingGroup.ItemLabel`	`label`
`RatingGroup.ItemDescription`	`div`

Accessibility

Keyboard Interactions

Key	Description
`ArrowDown`	Moves focus to the next item, increasing the rating value based on the `allowHalf` property.
`ArrowRight`	Moves focus to the next item, increasing the rating value based on the `allowHalf` property.
`ArrowUp`	Moves focus to the previous item, decreasing the rating value based on the `allowHalf` property.
`ArrowLeft`	Moves focus to the previous item, decreasing the rating value based on the `allowHalf` property.
`Space`	Selects the focused item in the rating group.
`Home`	Sets the value of the rating group to 1.
`End`	Sets the value of the rating group to the maximum value.