Rating Group

Rating group allows a user to assign rating to an item within a product.

Features

• Support for syncing disabled state of with fieldset element
• Support for form reset events

Installation

To use the rating group machine in your project, run the following command in your command line:

npm install @zag-js/rating-group @zag-js/react
# or
yarn add @zag-js/rating-group @zag-js/react

npm install @zag-js/rating-group @zag-js/solid
# or
yarn add @zag-js/rating-group @zag-js/solid

npm install @zag-js/rating-group @zag-js/vue
# or
yarn add @zag-js/rating-group @zag-js/vue

npm install @zag-js/rating-group @zag-js/svelte
# or
yarn add @zag-js/rating-group @zag-js/svelte

This command will install the framework agnostic rating logic and the reactive utilities for your framework of choice.

Anatomy

To set up the rating correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Usage

First, import the rating package into your project

import * as rating from "@zag-js/rating-group"

The rating package exports two key functions:

• machine — The state machine logic for the rating widget.
• connect — The function that translates the machine's state to JSX attributes and event handlers.

You'll also need to provide a unique id to the useMachine hook. This is used to ensure that every part has a unique identifier.

Next, import the required hooks and functions for your framework and use the rating machine in your project 🔥

import * as rating from "@zag-js/rating-group"
import { useMachine, normalizeProps } from "@zag-js/react"
import { HalfStar, Star } from "./icons"

function Rating() {
  const [state, send] = useMachine(rating.machine({ id: "1" }))

  const api = rating.connect(state, send, normalizeProps)

  return (
    <div {...api.getRootProps()}>
      <label {...api.getLabelProps()}>Rate:</label>
      <div {...api.getControlProps()}>
        {api.items.map((index) => {
          const state = api.getItemState({ index })
          return (
            <span key={index} {...api.getItemProps({ index })}>
              {state.half ? <HalfStar /> : <Star />}
            </span>
          )
        })}
      </div>
      <input {...api.getHiddenInputProps()} />
    </div>
  )
}

import * as rating from "@zag-js/rating-group"
import { useMachine, normalizeProps } from "@zag-js/solid"
import { createMemo, createUniqueId } from "solid-js"
import { HalfStar, Star } from "./icons"

function Rating() {
  const [state, send] = useMachine(rating.machine({ id: createUniqueId() }))

  const api = createMemo(() => rating.connect(state, send, normalizeProps))

  return (
    <div {...api().getRootProps()}>
      <label {...api().getLabelProps()}>Rate:</label>
      <div {...api().getControlProps()}>
        {api().items.map((index) => {
          const state = api().getItemState(index)
          return (
            <span key={index} {...api().getItemProps({ index })}>
              {state.half ? <HalfStar /> : <Star />}
            </span>
          )
        })}
      </div>
      <input {...api().getHiddenInputProps()} />
    </div>
  )
}

<script setup>
  import * as rating from "@zag-js/rating-group"
  import { normalizeProps, useMachine } from "@zag-js/vue"
  import { computed } from "vue"
  import { HalfStar, Star } from "./icons"

  const [state, send] = useMachine(rating.machine({ id: "1" }))

  const api = computed(() => rating.connect(state.value, send, normalizeProps))
</script>

<template>
  <div v-bind="api.getRootProps()">
    <label v-bind="api.getLabelProps()">Rate:</label>
    <div v-bind="api.getControlProps()">
      <span
        v-for="index in api.items"
        :key="index"
        v-bind="api.getItemProps({ index })"
      >
        <HalfStar v-if="api.getItemState({ index }).half" />
        <Star v-else />
      </span>
    </div>
    <input v-bind="api.getHiddenInputProps()" />
  </div>
</template>

<script lang="ts">
  import * as rating from "@zag-js/rating-group"
  import { normalizeProps, useMachine } from "@zag-js/svelte"

  const [snapshot, send] = useMachine(rating.machine({ id: "1", value: 2.5 }))

  const api = $derived(rating.connect(snapshot, send, normalizeProps))
</script>

<div {...api.getRootProps()}>
  <label {...api.getLabelProps()}>Rate:</label>
  <div {...api.getControlProps()}>
    {#each api.items as index}
      {@const snapshot = api.getItemState({ index })}
      <span {...api.getItemProps({ index })}>
        {#if snapshot.half}
          {@render HalfStar()}
        {:else}
          {@render Star()}
        {/if}
      </span>
    {/each}
  </div>
  <input {...api.getHiddenInputProps()} data-testid="hidden-input" />
</div>

Disabling the rating group

To make rating disabled, set the context's disabled property to true

const [state, send] = useMachine(
  rating.machine({
    disabled: true,
  }),
)

Making the rating readonly

To make rating readonly, set the context's readOnly property to true

const [state, send] = useMachine(
  rating.machine({
    readOnly: true,
  }),
)

Setting the initial value

To set the rating's initial value, set the context's value property.

const [state, send] = useMachine(
  rating.machine({
    value: 2.5,
  }),
)

Listening for changes

When the rating value changes, the onValueChange callback is invoked.

const [state, send] = useMachine(
  rating.machine({
    onValueChange({ value }) {
      console.log("rating value is:", value)
      // '1' | '2.5' | '4'
    },
  }),
)

Usage within forms

To use rating within forms, use the exposed inputProps from the connect function and ensure you pass name value to the machine's context. It will render a hidden input and ensure the value changes get propagated to the form correctly.

const [state, send] = useMachine(
  rating.machine({
    name: "rating",
  }),
)

Styling guide

Earlier, we mentioned that each rating part has a data-part attribute added to them to select and style them in the DOM.

Disabled State

When the rating is disabled, the data-disabled attribute is added to the rating, control and label parts.

[data-part="rating"][data-disabled] {
  /* styles for rating disabled state */
}

[data-part="label"][data-disabled] {
  /* styles for rating control disabled state */
}

[data-part="input"][data-disabled] {
  /* styles for rating label disabled state */
}

Checked State

When the rating is checked, the data-checked attribute is added to the rating part.

[data-part="rating"][data-checked] {
  /* styles for rating checked state */
}

Readonly State

When the rating is readonly, the data-readonly attribute is added to the rating part.

[data-part="rating"][data-readonly] {
  /* styles for rating readonly state */
}

Highlighted

When a rating is highlighted, the data-highlighted attribute is added to the rating part.

[data-part="rating"][data-highlighted] {
  /* styles for highlighted rating */
}

Half rating

When a rating is half, the data-half attribute is added to the rating part.

[data-part="rating"][data-half] {
  /* styles for half rating */
}

Methods and Properties

Machine Context

The rating group machine exposes the following context properties:

• idsPartial<{ root: string; label: string; hiddenInput: string; control: string; item(id: string): string; }>The ids of the elements in the rating. Useful for composition.
• translationsIntlTranslationsSpecifies the localized strings that identifies the accessibility elements and their states
• countnumberThe total number of ratings.
• namestringThe name attribute of the rating element (used in forms).
• formstringThe associate form of the underlying input element.
• valuenumberThe current rating value.
• readOnlybooleanWhether the rating is readonly.
• disabledbooleanWhether the rating is disabled.
• requiredbooleanWhether the rating is required.
• allowHalfbooleanWhether to allow half stars.
• autoFocusbooleanWhether to autofocus the rating.
• onValueChange(details: ValueChangeDetails) => voidFunction to be called when the rating value changes.
• onHoverChange(details: HoverChangeDetails) => voidFunction to be called when the rating value is hovered.
• dir"ltr" | "rtl"The document's text/writing direction.
• idstringThe unique identifier of the machine.
• getRootNode() => ShadowRoot | Node | DocumentA root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

Machine API

The rating group api exposes the following methods:

• setValue(value: number) => voidSets the value of the rating group
• clearValue() => voidClears the value of the rating group
• hoveringbooleanWhether the rating group is being hovered
• valuenumberThe current value of the rating group
• hoveredValuenumberThe value of the currently hovered rating
• countnumberThe total number of ratings
• itemsnumber[]The array of rating values. Returns an array of numbers from 1 to the max value.
• getItemState(props: ItemProps) => ItemStateReturns the state of a rating item

Data Attributes

Accessibility

Keyboard Interactions

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