Rating Group

Allows users to rate items using a set of icons.

Star IconStar IconStar IconStar IconStar Icon

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.

Examples

Learn how to use the RatingGroup component in your project. Let’s take a look at the most basic example:

import { RatingGroup } from '@ark-ui/react'

const Basic = () => (
  <RatingGroup.Root count={5} defaultValue={3}>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      {({ items }) =>
        items.map((item) => (
          <RatingGroup.Item key={item} index={item}>
            {({ isHighlighted }) => {
              if (isHighlighted) return <IconFull />
              return <IconEmpty />
            }}
          </RatingGroup.Item>
        ))
      }
    </RatingGroup.Control>
  </RatingGroup.Root>
)

Using half ratings

Allow 0.5 value steps by setting the allowHalf prop to true. Ensure to render the correct icon if the isHalf value is set in the Rating components render callback.

import { RatingGroup } from '@ark-ui/react'

const HalfRatings = () => (
  <RatingGroup.Root count={5} defaultValue={3} allowHalf>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      {({ items }) =>
        items.map((item) => (
          <RatingGroup.Item key={item} index={item}>
            {({ isHalf, isHighlighted }) => {
              if (isHalf) return <IconHalf />
              if (isHighlighted) return <IconFull />
              return <IconEmpty />
            }}
          </RatingGroup.Item>
        ))
      }
    </RatingGroup.Control>
  </RatingGroup.Root>
)

Using a default value

import { RatingGroup } from '@ark-ui/react'

const InitialValue = () => (
  <RatingGroup.Root count={5} defaultValue={2} readOnly>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      {({ items }) =>
        items.map((item) => (
          <RatingGroup.Item key={item} index={item}>
            {({ isHighlighted }) => {
              if (isHighlighted) return <IconFull />
              return <IconEmpty />
            }}
          </RatingGroup.Item>
        ))
      }
    </RatingGroup.Control>
  </RatingGroup.Root>
)

Controlled

When using the RatingGroup component, you can use the value and onValueChange props to control the state.

import { RatingGroup } from '@ark-ui/react'
import { useState } from 'react'

const Controlled = () => {
  const [value, setValue] = useState(0)

  return (
    <RatingGroup.Root
      count={5}
      value={value}
      onValueChange={(details) => setValue(details.value)}
      allowHalf
    >
      <RatingGroup.Label>Label</RatingGroup.Label>
      <RatingGroup.Control>
        {({ items }) =>
          items.map((item) => (
            <RatingGroup.Item key={item} index={item}>
              {({ isHalf, isHighlighted }) => {
                if (isHalf) return <IconHalf />
                if (isHighlighted) return <IconFull />
                return <IconEmpty />
              }}
            </RatingGroup.Item>
          ))
        }
      </RatingGroup.Control>
    </RatingGroup.Root>
  )
}

Disabling the rating group

To make the rating group disabled, set the disabled prop to true.

import { RatingGroup } from '@ark-ui/react'

const Disabled = () => (
  <RatingGroup.Root count={5} defaultValue={3} disabled>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      {({ items }) =>
        items.map((item) => (
          <RatingGroup.Item key={item} index={item}>
            {({ isHighlighted }) => {
              if (isHighlighted) return <IconFull />
              return <IconEmpty />
            }}
          </RatingGroup.Item>
        ))
      }
    </RatingGroup.Control>
  </RatingGroup.Root>
)

Readonly rating group

To make the rating group readonly, set the readOnly prop to true.

import { RatingGroup } from '@ark-ui/react'

const ReadOnly = () => (
  <RatingGroup.Root count={5} defaultValue={3} readOnly>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      {({ items }) =>
        items.map((item) => (
          <RatingGroup.Item key={item} index={item}>
            {({ isHighlighted }) => {
              if (isHighlighted) return <IconFull />
              return <IconEmpty />
            }}
          </RatingGroup.Item>
        ))
      }
    </RatingGroup.Control>
  </RatingGroup.Root>
)

Usage within forms

To use the rating group within forms, pass the prop name. It will render a hidden input and ensure the value changes get propagated to the form correctly.

import { RatingGroup } from '@ark-ui/react'

const FormUsage = () => (
  <RatingGroup.Root name="my-rating" count={5} defaultValue={3}>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      {({ items }) =>
        items.map((item) => (
          <RatingGroup.Item key={item} index={item}>
            {({ isHighlighted }) => {
              if (isHighlighted) return <IconFull />
              return <IconEmpty />
            }}
          </RatingGroup.Item>
        ))
      }
    </RatingGroup.Control>
  </RatingGroup.Root>
)

API Reference

Item

PropTypeDefault
index
number
asChild
boolean

Root

PropTypeDefault
allowHalf
boolean
asChild
boolean
autoFocus
boolean
count
number
defaultValue
number
dir
'ltr' | 'rtl'"ltr"
disabled
boolean
form
string
getRootNode
() => Node | ShadowRoot | Document
id
string
ids
Partial<{ root: string label: string hiddenInput: string control: string rating(id: string): string }>
name
string
onHoverChange
(details: HoverChangeDetails) => void
onValueChange
(details: ValueChangeDetails) => void
readOnly
boolean
translations
IntlTranslations
value
number

Label

PropTypeDefault
asChild
boolean

Control

PropTypeDefault
asChild
boolean

Previous

Range Slider

Next

Segment Group

On this page