Rating Group

Allows users to rate items using a set of icons.

Label

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 { StarIcon } from 'lucide-react'
import { RatingGroup } from '@ark-ui/react'

export const Basic = () => (
  <RatingGroup.Root count={5} defaultValue={3}>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      <RatingGroup.Context>
        {({ items }) =>
          items.map((item) => (
            <RatingGroup.Item key={item} index={item}>
              <RatingGroup.ItemContext>
                {({ highlighted }) => (highlighted ? <StarIcon fill="current" /> : <StarIcon />)}
              </RatingGroup.ItemContext>
            </RatingGroup.Item>
          ))
        }
      </RatingGroup.Context>
      <RatingGroup.HiddenInput />
    </RatingGroup.Control>
  </RatingGroup.Root>
)

import { StarIcon } from 'lucide-solid'
import { Index, Show } from 'solid-js'
import { RatingGroup } from '@ark-ui/solid'

export const Basic = () => (
  <RatingGroup.Root count={5} value={3}>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      <RatingGroup.Context>
        {(context) => (
          <Index each={context().items}>
            {(index) => (
              <RatingGroup.Item index={index()}>
                <RatingGroup.ItemContext>
                  {(context) => (
                    <Show when={context().highlighted} fallback={<StarIcon />}>
                      <StarIcon fill="current" />
                    </Show>
                  )}
                </RatingGroup.ItemContext>
              </RatingGroup.Item>
            )}
          </Index>
        )}
      </RatingGroup.Context>
      <RatingGroup.HiddenInput />
    </RatingGroup.Control>
  </RatingGroup.Root>
)

<script setup lang="ts">
import { RatingGroup } from '@ark-ui/vue'
import { StarIcon, StarOutlineIcon } from 'lucide-vue-next'
</script>

<template>
  <RatingGroup.Root :count="5" :model-value="3">
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      <RatingGroup.Context v-slot="{ items }">
        <RatingGroup.Item v-for="item in items" :key="item" :index="item">
          <RatingGroup.ItemContext v-slot="{ highlighted }">
            <StarIcon v-if="highlighted" />
            <StarOutlineIcon v-else />
          </RatingGroup.ItemContext>
        </RatingGroup.Item>
      </RatingGroup.Context>
      <RatingGroup.HiddenInput />
    </RatingGroup.Control>
  </RatingGroup.Root>
</template>

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.

Example not found

Example not found

Example not found

Using a default value

Example not found

Example not found

Example not found

Controlled

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

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

export 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>
        <RatingGroup.Context>
          {({ items }) =>
            items.map((item) => (
              <RatingGroup.Item key={item} index={item}>
                <RatingGroup.ItemContext>
                  {({ highlighted }) => (highlighted ? <StarIcon fill="current" /> : <StarIcon />)}
                </RatingGroup.ItemContext>
              </RatingGroup.Item>
            ))
          }
        </RatingGroup.Context>
        <RatingGroup.HiddenInput />
      </RatingGroup.Control>
    </RatingGroup.Root>
  )
}

import { StarIcon } from 'lucide-solid'
import { Index, Show, createSignal } from 'solid-js'
import { RatingGroup } from '@ark-ui/solid'

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

  return (
    <RatingGroup.Root
      count={5}
      value={value()}
      onValueChange={(details) => setValue(details.value)}
    >
      <RatingGroup.Label>Label</RatingGroup.Label>
      <RatingGroup.Control>
        <RatingGroup.Context>
          {(context) => (
            <Index each={context().items}>
              {(index) => (
                <RatingGroup.Item index={index()}>
                  <RatingGroup.ItemContext>
                    {(context) => (
                      <Show when={context().highlighted} fallback={<StarIcon />}>
                        <StarIcon fill="current" />
                      </Show>
                    )}
                  </RatingGroup.ItemContext>
                </RatingGroup.Item>
              )}
            </Index>
          )}
        </RatingGroup.Context>
        <RatingGroup.HiddenInput />
      </RatingGroup.Control>
    </RatingGroup.Root>
  )
}

<script setup lang="ts">
import { ref } from 'vue'
import { RatingGroup } from '@ark-ui/vue'
import { StarIcon, StarOutlineIcon } from 'lucide-vue-next'

const value = ref(0)
</script>

<template>
  <RatingGroup.Root :count="5" v-model="value" allowHalf>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      <RatingGroup.Context v-slot="{ items }">
        <RatingGroup.Item v-for="item in items" :key="item" :index="item">
          <RatingGroup.ItemContext v-slot="{ highlighted }">
            <StarIcon v-if="highlighted" />
            <StarOutlineIcon v-else />
          </RatingGroup.ItemContext>
        </RatingGroup.Item>
      </RatingGroup.Context>
      <RatingGroup.HiddenInput />
    </RatingGroup.Control>
  </RatingGroup.Root>
</template>

Disabling the rating group

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

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

export const Disabled = () => (
  <RatingGroup.Root count={5} defaultValue={3} disabled>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      <RatingGroup.Context>
        {({ items }) =>
          items.map((item) => (
            <RatingGroup.Item key={item} index={item}>
              <RatingGroup.ItemContext>
                {({ highlighted }) => (highlighted ? <StarIcon fill="current" /> : <StarIcon />)}
              </RatingGroup.ItemContext>
            </RatingGroup.Item>
          ))
        }
      </RatingGroup.Context>
      <RatingGroup.HiddenInput />
    </RatingGroup.Control>
  </RatingGroup.Root>
)

import { StarIcon } from 'lucide-solid'
import { Index, Show } from 'solid-js'
import { RatingGroup } from '@ark-ui/solid'

export const Disabled = () => (
  <RatingGroup.Root count={5} value={3} disabled>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      <RatingGroup.Context>
        {(context) => (
          <Index each={context().items}>
            {(index) => (
              <RatingGroup.Item index={index()}>
                <RatingGroup.ItemContext>
                  {(context) => (
                    <Show when={context().highlighted} fallback={<StarIcon />}>
                      <StarIcon fill="current" />
                    </Show>
                  )}
                </RatingGroup.ItemContext>
              </RatingGroup.Item>
            )}
          </Index>
        )}
      </RatingGroup.Context>
      <RatingGroup.HiddenInput />
    </RatingGroup.Control>
  </RatingGroup.Root>
)

<script setup lang="ts">
import { RatingGroup } from '@ark-ui/vue'
import { StarIcon, StarOutlineIcon } from 'lucide-vue-next'
</script>

<template>
  <RatingGroup.Root :count="5" :model-value="3" disabled>
    <RatingGroup.Label>Label</RatingGroup.Label>
    <RatingGroup.Control>
      <RatingGroup.Context v-slot="{ items }">
        <RatingGroup.Item v-for="item in items" :key="item" :index="item">
          <RatingGroup.ItemContext v-slot="{ highlighted }">
            <StarIcon v-if="highlighted" />
            <StarOutlineIcon v-else />
          </RatingGroup.ItemContext>
        </RatingGroup.Item>
      </RatingGroup.Context>
      <RatingGroup.HiddenInput />
    </RatingGroup.Control>
  </RatingGroup.Root>
</template>

Readonly rating group

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

Example not found

Example not found

Example not found

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.

Example not found

Example not found

Example not found

API Reference

Root

Prop	Default	Type
`allowHalf`		`boolean` Whether to allow half stars.
`asChild`		`boolean` Render as a different element type.
`autoFocus`		`boolean` Whether to autofocus the rating.
`count`		`number` The total number of ratings.
`defaultValue`		`number` The initial value of the rating group when it is first rendered. Use when you do not need to control the state of the rating group.
`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`		`Partial<{ root: string label: string hiddenInput: string control: string rating(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.
`translations`		`IntlTranslations` Specifies the localized strings that identifies the accessibility elements and their states
`value`		`number` The current rating value.

Control

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.

HiddenInput

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.

Item

Prop	Default	Type
`index`		`number`
`asChild`		`boolean` Render as a different element type.

Label

Prop	Default	Type
`asChild`		`boolean` Render as a different element type.