Rating Group

A component for selecting a rating value, typically represented by stars or other symbols.

Anatomy

Usage

<script>
  import {RatingGroup} from 'ui-ingredients';
  import {StarIcon} from '$lib/icons';
</script>

<RatingGroup.Root>
  <RatingGroup.Label>Label</RatingGroup.Label>
  <RatingGroup.HiddenInput />

  {#each context.items as index}
    <RatingGroup.Item {index}>
      {#snippet children(state)}
        <StarIcon
          class={state.highlighted ? 'text-yellow-500' : 'text-gray-500'}
        />
      {/snippet}
    </RatingGroup.Item>
  {/each}
</RatingGroup.Root>

Usage with Field component

<script>
  import {RatingGroup, Field} from 'ui-ingredients';
  import {StarIcon} from '$lib/icons';
</script>

<Field.Root>
  <RatingGroup.Root>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.HiddenInput />

    {#each context.items as index}
      <RatingGroup.Item {index}>
        {#snippet children(state)}
          <StarIcon
            class={state.highlighted ? 'text-yellow-500' : 'text-gray-500'}
          />
        {/snippet}
      </RatingGroup.Item>
    {/each}
  </RatingGroup.Root>

  <Field.HelperText>This is a helper text</Field.HelperText>
  <Field.ErrorText>This is an error text</Field.ErrorText>
</Field.Root>

API Reference

Root

Prop	Default	Description
`allowHalf`		`boolean` Whether to allow half stars.
`autoFocus`		`boolean` Whether to autofocus the rating.
`count`	`5`	`number` The total number of ratings.
`defaultValue`		`number` The initial value of the rating when rendered. Use when you don't need to control the value of the rating.
`disabled`		`boolean` Whether the rating is disabled.
`form`		`string` The associate form of the underlying input element.
`id`		`string` The unique identifier of the machine.
`ids`		`{ root?: string; label?: string; hiddenInput?: string; control?: string; item(id: string)?: string; }` The ids of the elements in the rating. Useful for composition.
`name`		`string` The name attribute of the rating element (used in forms).
`onHoverChange`		`(details: HoverChangeDetails) => void` Function to be called when the rating value is hovered.
`onValueChange`		`(details: ValueChangeDetails) => void` Function to be called when the rating value changes.
`readOnly`		`boolean` Whether the rating is readonly.
`required`		`boolean` Whether the rating is required.
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`value`		`number` The controlled value of the rating
`asChild`		`Snippet` Render a different element.

Control

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	control
`data-readonly`	Present when read-only
`data-scope`	rating-group

HiddenInput

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Item

Prop	Default	Description
`index`		`number` The index of the item.
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-checked`	Present when checked
`data-disabled`	Present when disabled
`data-half`
`data-highlighted`	Present when highlighted
`data-part`	item
`data-readonly`	Present when read-only
`data-scope`	rating-group

Label

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-disabled`	Present when disabled
`data-part`	label
`data-scope`	rating-group

Accessibility

Keyboard Support

Key	Description
ArrowRight	Moves focus to the next star, increasing the rating value based on the `allowHalf` property.
ArrowLeft	Moves focus to the previous star, decreasing the rating value based on the `allowHalf` property.
Enter	Selects the focused star in the rating group.