PettyUI/.firecrawl/kobalte-rating.md

Rating Group

Allows users to rate items using a set of icons.

Import

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

Copyts
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.

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

Copytsx
<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:

Star Icon

Star Icon

Star Icon

Star Icon

Star Icon

index.tsxstyle.css

Copytsx
import { RatingGroup } from "@kobalte/core/rating-group";
import "./style.css";

function App() {
  return (
    <RatingGroup class="rating-group">
		<RatingGroup.Label class="rating-group__label">Rate Us:</RatingGroup.Label>
		<RatingGroup.Control class="rating-group__control">
			<Index each={Array(5)}>
				{_ => (
					<RatingGroup.Item class="rating-group-item">
						<RatingGroup.ItemControl>
							<StarIcon />
						</RatingGroup.ItemControl>
					</RatingGroup.Item>
				)}
			</Index>
		</RatingGroup.Control>
	</RatingGroup>
  );
}

Copytsx
import { RatingGroup } from "@kobalte/core/rating-group";
import "./style.css";

function App() {
  return (
    <RatingGroup class="rating-group">
		<RatingGroup.Label class="rating-group__label">Rate Us:</RatingGroup.Label>
		<RatingGroup.Control class="rating-group__control">
			<Index each={Array(5)}>
				{_ => (
					<RatingGroup.Item class="rating-group-item">
						<RatingGroup.ItemControl>
							<StarIcon />
						</RatingGroup.ItemControl>
					</RatingGroup.Item>
				)}
			</Index>
		</RatingGroup.Control>
	</RatingGroup>
  );
}

Usage

Default value

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

Star Icon

Star Icon

Star Icon

Star Icon

Star Icon

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

Copytsx
<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.

Star Icon

Star Icon

Star Icon

Star Icon

Star Icon

Your rating is: 0/5

Copytsx
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>
		</>
	);
}

Copytsx
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.

Star Icon

Star Icon

Star Icon

Star Icon

Star Icon

Copytsx
<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>

Copytsx
<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:

Star Icon

Star Icon

Star Icon

Star Icon

Star Icon

Rate your experience with us.

Copytsx
<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>

Copytsx
<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:

Star Icon

Star Icon

Star Icon

Star Icon

Star Icon

Please select a rating between 1 and 5.

Copytsx
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>
	);
}

Copytsx
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.

Star Icon

Star Icon

Star Icon

Star Icon

Star Icon

ResetSubmit

Copytsx
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>
	);
}

Copytsx
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'
name	string The name of the rating group. Submitted with its owning form as part of a name/value pair.
validationState	`'valid'
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.

Previous←Radio GroupNextSearch→