Rating Group
Allows users to rate items using a set of icons.
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-partattribute 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.
Story not foundStory not foundStory not foundUsing a default value
Story not foundStory not foundStory not foundControlled
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.
Story not foundStory not foundStory not foundUsage 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.
Story not foundStory not foundStory not foundAPI Reference
Root
| Prop | Type | Default |
|---|---|---|
allowHalfWhether to allow half stars. | boolean | |
asChildRender as a different element type. | boolean | |
autoFocusWhether to autofocus the rating. | boolean | |
countThe total number of ratings. | number | |
defaultValueThe 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. | number | |
disabledWhether the rating is disabled. | boolean | |
formThe associate form of the underlying input element. | string | |
idThe unique identifier of the machine. | string | |
idsThe ids of the elements in the rating. Useful for composition. | Partial<{
root: string
label: string
hiddenInput: string
control: string
rating(id: string): string
}> | |
nameThe name attribute of the rating element (used in forms). | string | |
onHoverChangeFunction to be called when the rating value is hovered. | (details: HoverChangeDetails) => void | |
onValueChangeFunction to be called when the rating value changes. | (details: ValueChangeDetails) => void | |
readOnlyWhether the rating is readonly. | boolean | |
translationsSpecifies the localized strings that identifies the accessibility elements and their states | IntlTranslations | |
valueThe current rating value. | number |
Control
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
HiddenInput
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Item
| Prop | Type | Default |
|---|---|---|
index | number | |
asChildRender as a different element type. | boolean |
Label
| Prop | Type | Default |
|---|---|---|
asChildRender as a different element type. | boolean |
Previous
Radio GroupNext
Segment Group