Rating

The Rating component provides a way to select a value from a range of values, typically used for feedback on a scale.

import { Rating, RatingParts } from '@cerberus/react'

Usage

The Rating component is an abstracted client component that provides a way to select a value from a range of values. It is used to provide feedback on a scale. The default count is 5, and the default value is 0.

'use client'

import { Rating } from '@cerberus/react'
import { StarFilled } from '@carbon/icons-react'

export function BasicDemo() {
  return <Rating defaultValue={3}>{() => <StarFilled size={24} />}</Rating>
}

Readonly State

To render the Rating component in a read-only state, you can use the readOnly prop.

'use client'

import { Rating } from '@cerberus/react'
import { StarHalf, StarFilled } from '@carbon/icons-react'

function ReadOnlyHalfDemo() {
  return (
    <Rating defaultValue={4.5} allowHalf readOnly>
      {({ half, highlighted }) => {
        if (half) return <StarHalf size={24} />
        if (highlighted) return <StarFilled size={24} />
        return <Star size={24} />
      }}
    </Rating>
  )
}

Orientation

The Rating component supports two layout orientations for label usage: horizontal, and vertical. The default orientation is vertical.

'use client'

import { Rating } from '@cerberus/react'
import { StarHalf, StarFilled } from '@carbon/icons-react'

function OrientationDemo() {
  return (
    <Box w="1/2">
      <Rating
        allowHalf
        defaultValue={4.5}
        label="Average Rating"
        orientation="horizontal"
        readOnly
      >
        {({ half }) => {
          if (half) return <StarHalf size={24} />
          return <StarFilled size={24} />
        }}
      </Rating>
    </Box>
  )
}

Sizes

The Rating component supports two sizes: sm, and md. The default size is sm.

'use client'

import { Rating } from '@cerberus/react'
import { StarFilled } from '@carbon/icons-react'

function SizeDemo() {
  return (
    <Rating defaultValue={3} label="This is a medium label" size="md">
      {() => <StarFilled size={24} />}
    </Rating>
  )
}

Primitives

You can utilize the primitive components or the css prop to customize the radio.

Component	Description
RatingRoot	The context provider for the Rating parts
RatingLabel	The label of the rating
RatingControl	The visual control of the rating
RatingContext	The context provider for the rating
RatingItem	The container of the rating item
RatingItemContext	The context provider for a rating item
RatingHiddenInput	The native input for the rating

import { RatingParts, type UseRatingGroupContext } from '@cerberus/react'
import { Box } from 'styled-system/jsx'

function CustomDemo() {
  return (
    <Box w="1/2">
      <RatingParts.Root
        defaultValue={3}
        orientation="horizontal"
        css={{
          transform: 'skewX(-10deg)',
        }}
      >
        <RatingParts.Label
          css={{
            textStyle: 'heading-xs',
            textTransform: 'uppercase',
          }}
        >
          This is a custom rating
        </RatingParts.Label>

        <RatingParts.Control>
          <RatingParts.Context>
            {(context: UseRatingGroupContext) =>
              context.items.map((item) => (
                <RatingParts.Item
                  key={item}
                  index={item}
                  css={{
                    _highlighted: {
                      colorPalette: 'danger',
                      scale: '1.2',
                    },
                  }}
                >
                  <RatingParts.ItemContext>
                    {() => <StarFilled size={24} />}
                  </RatingParts.ItemContext>
                </RatingParts.Item>
              ))
            }
          </RatingParts.Context>
          <RatingParts.HiddenInput />
        </RatingParts.Control>
      </RatingParts.Root>
    </Box>
  )
}

API

Props

Rating

The Rating component is an abstraction of the primitives and accepts the following props:

Name	Default	Description
orientation	`horizontal`	This orientation of the group.
palette	`action`	The color palette of the items .
size	`sm`	The size of the label.

The Rating component also accepts all the props of the RatingRoot primitive props

Parts

The RatingParts API is an Object containing the full family of components.

Note

It is best to only use the RatingParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

Name	Description
Root	The `RatingRoot` component which is the Provider for the family.
Label	The `RatingLabel` component which displays the label.
Control	The `RatingControl` component which displays the visual rating.
Item	The `RatingItem` component which is the container to a single item.
ItemContext	The `RatingItemContext` component which is the context provider for a single item.
HiddenInput	The `RatingHiddenInput` component which displays the native radio.

On this page