618 lines
15 KiB
Markdown
618 lines
15 KiB
Markdown
# 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) |