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

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

```jsx
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 ð¥

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

function Rating() {
  const service = useMachine(rating.machine, { id: "1" })

  const api = rating.connect(service, 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>
  )
}
```

### Disabling the rating group

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

```jsx {2}
const service = useMachine(rating.machine, {
  disabled: true,
})
```

### Making the rating readonly

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

```jsx {2}
const service = useMachine(rating.machine, {
  readOnly: true,
})
```

### Setting the initial value

Use the `defaultValue` property to set the rating's initial value.

```jsx {2}
const service = useMachine(rating.machine, {
  defaultValue: 2.5,
})
```

### Listening for changes

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

```jsx {2-7}
const service = 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.

```jsx {2}
const service = 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.

```css
[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.

```css
[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.

```css
[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.

```css
[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.

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

## Methods and Properties

### Machine Context

The rating group machine exposes the following context properties:

**`ids`**
Type: `Partial<{ root: string; label: string; hiddenInput: string; control: string; item: (id: string) => string; }>`
Description: The ids of the elements in the rating. Useful for composition.

**`translations`**
Type: `IntlTranslations`
Description: Specifies the localized strings that identifies the accessibility elements and their states

**`count`**
Type: `number`
Description: The total number of ratings.

**`name`**
Type: `string`
Description: The name attribute of the rating element (used in forms).

**`form`**
Type: `string`
Description: The associate form of the underlying input element.

**`value`**
Type: `number`
Description: The controlled value of the rating

**`defaultValue`**
Type: `number`
Description: The initial value of the rating when rendered.
Use when you don't need to control the value of the rating.

**`readOnly`**
Type: `boolean`
Description: Whether the rating is readonly.

**`disabled`**
Type: `boolean`
Description: Whether the rating is disabled.

**`required`**
Type: `boolean`
Description: Whether the rating is required.

**`allowHalf`**
Type: `boolean`
Description: Whether to allow half stars.

**`autoFocus`**
Type: `boolean`
Description: Whether to autofocus the rating.

**`onValueChange`**
Type: `(details: ValueChangeDetails) => void`
Description: Function to be called when the rating value changes.

**`onHoverChange`**
Type: `(details: HoverChangeDetails) => void`
Description: Function to be called when the rating value is hovered.

**`dir`**
Type: `"ltr" | "rtl"`
Description: The document's text/writing direction.

**`id`**
Type: `string`
Description: The unique identifier of the machine.

**`getRootNode`**
Type: `() => ShadowRoot | Node | Document`
Description: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

### Machine API

The rating group `api` exposes the following methods:

**`setValue`**
Type: `(value: number) => void`
Description: Sets the value of the rating group

**`clearValue`**
Type: `VoidFunction`
Description: Clears the value of the rating group

**`hovering`**
Type: `boolean`
Description: Whether the rating group is being hovered

**`value`**
Type: `number`
Description: The current value of the rating group

**`hoveredValue`**
Type: `number`
Description: The value of the currently hovered rating

**`count`**
Type: `number`
Description: The total number of ratings

**`items`**
Type: `number[]`
Description: The array of rating values. Returns an array of numbers from 1 to the max value.

**`getItemState`**
Type: `(props: ItemProps) => ItemState`
Description: Returns the state of a rating item

### Data Attributes

**`Label`**

**`data-scope`**: rating-group
**`data-part`**: label
**`data-disabled`**: Present when disabled
**`data-required`**: Present when required

**`Control`**

**`data-scope`**: rating-group
**`data-part`**: control
**`data-readonly`**: Present when read-only
**`data-disabled`**: Present when disabled

**`Item`**

**`data-scope`**: rating-group
**`data-part`**: item
**`data-disabled`**: Present when disabled
**`data-readonly`**: Present when read-only
**`data-checked`**: Present when checked
**`data-highlighted`**: Present when highlighted
**`data-half`**: 

## Accessibility

### Keyboard Interactions

**`ArrowRight`**
Description: Moves focus to the next star, increasing the rating value based on the `allowHalf` property.

**`ArrowLeft`**
Description: Moves focus to the previous star, decreasing the rating value based on the `allowHalf` property.

**`Enter`**
Description: Selects the focused star in the rating group.
A scroll area provides a scrollable viewport with customizable scrollbars for
content that exceeds the container's dimensions.

## Resources


[Latest version: v1.33.1](https://www.npmjs.com/package/@zag-js/scroll-area)
[Logic Visualizer](https://zag-visualizer.vercel.app/scroll-area)
[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/scroll-area)



**Features**

- Custom scrollbar styling and behavior
- Smooth scrolling with easing functions
- Touch and keyboard navigation support
- Automatic scrollbar hiding when not needed
- Nested scroll area support
- Programmatic scrolling to edges or coordinates

## Installation

To use the scroll area machine in your project, run the following command in
your command line:

```bash
npm install @zag-js/scroll-area @zag-js/react