{"slug":"rating-group","title":"Rating Group","description":"Using the rating machine in your project.","contentType":"component","framework":"react","content":"Rating group lets users assign a rating value to an item.\n\n## Resources\n\n\n[Latest version: v1.35.3](https://www.npmjs.com/package/@zag-js/rating-group)\n[Logic Visualizer](https://zag-visualizer.vercel.app/rating-group)\n[Source Code](https://github.com/chakra-ui/zag/tree/main/packages/machines/rating-group)\n\n\n\n**Features**\n\n- Syncs with `disabled` state of `fieldset`\n- Supports form `reset` events\n\n## Installation\n\nInstall the rating group package:\n\n```bash\nnpm install @zag-js/rating-group @zag-js/react\n# or\nyarn add @zag-js/rating-group @zag-js/react\n```\n\n## Anatomy\n\nCheck the rating anatomy and part names.\n\n> Each part includes a `data-part` attribute to help identify them in the DOM.\n\n\n\n## Usage\n\nImport the rating package:\n\n```jsx\nimport * as rating from \"@zag-js/rating-group\"\n```\n\nThe rating package exports two key functions:\n\n- `machine` - State machine logic.\n- `connect` - Maps machine state to JSX props and event handlers.\n\nThen use the framework integration helpers:\n\n```jsx\nimport * as rating from \"@zag-js/rating-group\"\nimport { useMachine, normalizeProps } from \"@zag-js/react\"\nimport { HalfStar, Star } from \"./icons\"\n\nfunction Rating() {\n  const service = useMachine(rating.machine, { id: \"1\" })\n\n  const api = rating.connect(service, normalizeProps)\n\n  return (\n    <div {...api.getRootProps()}>\n      <label {...api.getLabelProps()}>Rate:</label>\n      <div {...api.getControlProps()}>\n        {api.items.map((index) => {\n          const state = api.getItemState({ index })\n          return (\n            <span key={index} {...api.getItemProps({ index })}>\n              {state.half ? <HalfStar /> : <Star />}\n            </span>\n          )\n        })}\n      </div>\n      <input {...api.getHiddenInputProps()} />\n    </div>\n  )\n}\n```\n\n### Setting the initial value\n\nUse the `defaultValue` property to set the rating's initial value.\n\n```jsx {2}\nconst service = useMachine(rating.machine, {\n  defaultValue: 2.5,\n})\n```\n\n### Controlled rating value\n\nUse `value` and `onValueChange` to control the rating externally.\n\n```jsx\nconst service = useMachine(rating.machine, {\n  value,\n  onValueChange(details) {\n    setValue(details.value)\n  },\n})\n```\n\n### Setting and clearing value programmatically\n\nUse `api.setValue` or `api.clearValue` when you need imperative control.\n\n```jsx\napi.setValue(4)\napi.clearValue()\n```\n\n### Allowing half ratings\n\nEnable `allowHalf` when your UX needs fractional ratings.\n\n```jsx\nconst service = useMachine(rating.machine, {\n  allowHalf: true,\n})\n```\n\n### Listening for changes\n\nWhen the rating value changes, the `onValueChange` callback is invoked.\n\n```jsx {2-7}\nconst service = useMachine(rating.machine, {\n  onValueChange({ value }) {\n    console.log(\"rating value is:\", value)\n    // 1 | 2.5 | 4\n  },\n})\n```\n\n### Listening for hover changes\n\nUse `onHoverChange` to react to hover previews before selection.\n\n```jsx\nconst service = useMachine(rating.machine, {\n  onHoverChange(details) {\n    console.log(\"hovered rating:\", details.hoveredValue)\n  },\n})\n```\n\n### Customizing screen reader value text\n\nUse `translations.ratingValueText` to customize how each rating item is\nannounced.\n\n```jsx\nconst service = useMachine(rating.machine, {\n  translations: {\n    ratingValueText: (index) => `${index} out of 5`,\n  },\n})\n```\n\n### Usage within forms\n\nTo use rating in forms, set `name` and render `api.getHiddenInputProps()`.\n\n```jsx {2}\nconst service = useMachine(rating.machine, {\n  name: \"rating\",\n})\n```\n\n## Styling guide\n\nEach rating part includes a `data-part` attribute you can target in CSS.\n\n### Disabled State\n\nWhen the rating is disabled, the `data-disabled` attribute is added to the\nrating, control and label parts.\n\n```css\n[data-part=\"rating\"][data-disabled] {\n  /* styles for rating disabled state */\n}\n\n[data-part=\"label\"][data-disabled] {\n  /* styles for rating control disabled state */\n}\n\n[data-part=\"input\"][data-disabled] {\n  /* styles for rating label disabled state */\n}\n```\n\n### Checked State\n\nWhen the rating is checked, the `data-checked` attribute is added to the rating\npart.\n\n```css\n[data-part=\"rating\"][data-checked] {\n  /* styles for rating checked state */\n}\n```\n\n### Readonly State\n\nWhen the rating is readonly, the `data-readonly` attribute is added to the\nrating part.\n\n```css\n[data-part=\"rating\"][data-readonly] {\n  /* styles for rating readonly state */\n}\n```\n\n### Highlighted\n\nWhen a rating is highlighted, the `data-highlighted` attribute is added to the\nrating part.\n\n```css\n[data-part=\"rating\"][data-highlighted] {\n  /* styles for highlighted rating */\n}\n```\n\n### Half rating\n\nWhen a rating is half, the `data-half` attribute is added to the rating part.\n\n```css\n[data-part=\"rating\"][data-half] {\n  /* styles for half rating */\n}\n```\n\n## Methods and Properties\n\n### Machine Context\n\nThe rating group machine exposes the following context properties:\n\n**`ids`**\nType: `Partial<{ root: string; label: string; hiddenInput: string; control: string; item: (id: string) => string; }>`\nDescription: The ids of the elements in the rating. Useful for composition.\n\n**`translations`**\nType: `IntlTranslations`\nDescription: Specifies the localized strings that identifies the accessibility elements and their states\n\n**`count`**\nType: `number`\nDescription: The total number of ratings.\n\n**`name`**\nType: `string`\nDescription: The name attribute of the rating element (used in forms).\n\n**`form`**\nType: `string`\nDescription: The associate form of the underlying input element.\n\n**`value`**\nType: `number`\nDescription: The controlled value of the rating\n\n**`defaultValue`**\nType: `number`\nDescription: The initial value of the rating when rendered.\nUse when you don't need to control the value of the rating.\n\n**`readOnly`**\nType: `boolean`\nDescription: Whether the rating is readonly.\n\n**`disabled`**\nType: `boolean`\nDescription: Whether the rating is disabled.\n\n**`required`**\nType: `boolean`\nDescription: Whether the rating is required.\n\n**`allowHalf`**\nType: `boolean`\nDescription: Whether to allow half stars.\n\n**`autoFocus`**\nType: `boolean`\nDescription: Whether to autofocus the rating.\n\n**`onValueChange`**\nType: `(details: ValueChangeDetails) => void`\nDescription: Function to be called when the rating value changes.\n\n**`onHoverChange`**\nType: `(details: HoverChangeDetails) => void`\nDescription: Function to be called when the rating value is hovered.\n\n**`dir`**\nType: `\"ltr\" | \"rtl\"`\nDescription: The document's text/writing direction.\n\n**`id`**\nType: `string`\nDescription: The unique identifier of the machine.\n\n**`getRootNode`**\nType: `() => ShadowRoot | Node | Document`\nDescription: A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.\n\n### Machine API\n\nThe rating group `api` exposes the following methods:\n\n**`setValue`**\nType: `(value: number) => void`\nDescription: Sets the value of the rating group\n\n**`clearValue`**\nType: `VoidFunction`\nDescription: Clears the value of the rating group\n\n**`hovering`**\nType: `boolean`\nDescription: Whether the rating group is being hovered\n\n**`value`**\nType: `number`\nDescription: The current value of the rating group\n\n**`hoveredValue`**\nType: `number`\nDescription: The value of the currently hovered rating\n\n**`count`**\nType: `number`\nDescription: The total number of ratings\n\n**`items`**\nType: `number[]`\nDescription: The array of rating values. Returns an array of numbers from 1 to the max value.\n\n**`getItemState`**\nType: `(props: ItemProps) => ItemState`\nDescription: Returns the state of a rating item\n\n### Data Attributes\n\n**`Label`**\n\n**`data-scope`**: rating-group\n**`data-part`**: label\n**`data-disabled`**: Present when disabled\n**`data-required`**: Present when required\n\n**`Control`**\n\n**`data-scope`**: rating-group\n**`data-part`**: control\n**`data-readonly`**: Present when read-only\n**`data-disabled`**: Present when disabled\n\n**`Item`**\n\n**`data-scope`**: rating-group\n**`data-part`**: item\n**`data-disabled`**: Present when disabled\n**`data-readonly`**: Present when read-only\n**`data-checked`**: Present when checked\n**`data-highlighted`**: Present when highlighted\n**`data-half`**: \n\n## Accessibility\n\n### Keyboard Interactions\n\n**`ArrowRight`**\nDescription: Moves focus to the next star, increasing the rating value based on the `allowHalf` property.\n\n**`ArrowLeft`**\nDescription: Moves focus to the previous star, decreasing the rating value based on the `allowHalf` property.\n\n**`Enter`**\nDescription: Selects the focused star in the rating group.","package":"@zag-js/rating-group","editUrl":"https://github.com/chakra-ui/zag/edit/main/website/data/components/rating-group.mdx"}