# 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`<br> The current rating value. |
| defaultValue | `number`<br> 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`<br> Event handler called when the value changes. |
| allowHalf | `boolean`<br> Whether to allow half ratings. |
| orientation | `'horizontal' | 'vertical'`<br> The axis the rating group items should align with. |
| name | `string`<br> The name of the rating group. Submitted with its owning form as part of a name/value pair. |
| validationState | `'valid' | 'invalid'`<br> Whether the rating group should display its "valid" or "invalid" visual styling. |
| required | `boolean`<br> Whether the user must select an item before the owning form can be submitted. |
| disabled | `boolean`<br> Whether the rating group is disabled. |
| readOnly | `boolean`<br> 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`<br> 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>`<br> Whether the rating item is half. |
| highlighted | `Accessor<boolean>`<br> 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 Group](https://kobalte.dev/docs/core/components/radio-group)Next[Search→](https://kobalte.dev/docs/core/components/search)