Rating

Allows users to rate items using a set of icons.

Import

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

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

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 consists of:

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

The rating item consists of:

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

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

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

Example

Rate Us:

Usage

Default value

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

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

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

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 (
		<>
			<Rating value={value()} onChange={setValue}>
				<Rating.Control>
					<Index each={Array(5)}>
						{_ => (
							<Rating.Item>
								<Rating.ItemControl>
									<StarIcon />
								</Rating.ItemControl>
							</Rating.Item>
						)}
					</Index>
				</Rating.Control>
			</Rating>
			<p>Your rating is: {value()}/5</p>
		</>
	);
}

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

Half Ratings

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

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

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

Description

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

Rate Us:

Rate your experience with us.

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

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

Error message

The Rating.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 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 (
		<Rating
			value={value()}
			onChange={setValue}
			validationState={value() === 0 ? "invalid" : "valid"}
		>
			<Rating.Label>Rate Us:</Rating.Label>
			<Rating.Control>
				<Index each={Array(5)}>
					{_ => (
						<Rating.Item>
							<Rating.ItemControl>
								<StarIcon />
							</Rating.ItemControl>
						</Rating.Item>
					)}
				</Index>
			</Rating.Control>
			<Rating.ErrorMessage>Please select a rating between 1 and 5.</Rating.ErrorMessage>
		</Rating>
	);
}

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

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}>
			<Rating name="rate">
				<Rating.Control>
					<Index each={Array(5)}>
						{_ => (
							<Rating.Item>
								<Rating.ItemControl>
									<StarIcon />
								</Rating.ItemControl>
							</Rating.Item>
						)}
					</Index>
				</Rating.Control>
				<Rating.HiddenInput />
			</Rating>
			<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}>
			<Rating name="rate">
				<Rating.Control>
					<Index each={Array(5)}>
						{_ => (
							<Rating.Item>
								<Rating.ItemControl>
									<StarIcon />
								</Rating.ItemControl>
							</Rating.Item>
						)}
					</Index>
				</Rating.Control>
				<Rating.HiddenInput />
			</Rating>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}

API Reference

Rating

Rating is equivalent to the Root import from @kobalte/core/rating.

Prop	Description
value	`number` The current rating value.
defaultValue	`number` The initial value of the rating when it is first rendered. Use when you do not need to control the state of the rating.
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 items should align with.
name	`string` The name of the rating. Submitted with its owning form as part of a name/value pair.
validationState	`'valid' \| 'invalid'` Whether the rating 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 is disabled.
readOnly	`boolean` Whether the rating items can be selected but not changed by the user.

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

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

Rating.ErrorMessage

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

Rating.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 is valid according to the validation rules.
data-invalid	Present when the parent rating is invalid according to the validation rules.
data-required	Present when the parent rating is required.
data-disabled	Present when the parent rating is disabled.
data-readonly	Present when the parent rating 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.

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

Rendered elements

Component	Default rendered element
`Rating`	`div`
`Rating.Control`	`div`
`Rating.Label`	`span`
`Rating.HiddenInput`	`input`
`Rating.Description`	`div`
`Rating.ErrorMessage`	`div`
`Rating.Item`	`div`
`Rating.ItemControl`	`div`
`Rating.ItemLabel`	`label`
`Rating.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.
`Home`	Sets the value of the rating to 1.
`End`	Sets the value of the rating to the maximum value.