Data

Rating

Star rating that works as both a fractional display and an interactive input. Fractional values (e.g. 3.75) render partial stars with no rounding. Provide onValueChange or defaultValue to switch to interactive input mode.

Source

Preview

GitHub

import { Rating } from '@brika/clay/components/rating';

/** Default five-star rating at 3.75: the fourth star is 75% filled, no rounding. */
export default function RatingDefaultDemo() {
  return <Rating value={3.75} aria-label="3.75 out of 5 stars" />;
}

01 Installation

Install

Pull Rating from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line

import { Rating } from "@brika/clay";

tsxGranular1 line

import { Rating } from "@brika/clay/components/rating";

02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxRating.tsx6 lines

import { Rating } from '@brika/clay/components/rating';

/** Default five-star rating at 3.75: the fourth star is 75% filled, no rounding. */
export default function RatingDefaultDemo() {
  return <Rating value={3.75} aria-label="3.75 out of 5 stars" />;
}

03 Examples

Rating, every way

Colors

Four ratings side by side each using a different `color` prop value, from the default `--warning` token to a custom hex.

GitHub

import { Rating } from '@brika/clay/components/rating';

/**
 * Four ratings side by side each using a different `color` prop value, from the default `--warning` token to a custom hex.
 */
export default function RatingColorsDemo() {
  return (
    <div className="flex flex-col items-start gap-3">
      <div className="flex items-center gap-3">
        <span className="w-28 text-xs text-muted-foreground">default (--warning)</span>
        <Rating value={4} aria-label="4 out of 5, default color" />
      </div>
      <div className="flex items-center gap-3">
        <span className="w-28 text-xs text-muted-foreground">var(--primary)</span>
        <Rating value={4} color="var(--primary)" aria-label="4 out of 5, primary color" />
      </div>
      <div className="flex items-center gap-3">
        <span className="w-28 text-xs text-muted-foreground">var(--destructive)</span>
        <Rating value={4} color="var(--destructive)" aria-label="4 out of 5, destructive color" />
      </div>
      <div className="flex items-center gap-3">
        <span className="w-28 text-xs text-muted-foreground">#10b981</span>
        <Rating value={4} color="#10b981" aria-label="4 out of 5, emerald color" />
      </div>
    </div>
  );
}

Fractional

Three read-only ratings at different fractional values (3.75, 2.3, 0.5) shown across all three size variants, demonstrating sub-star fill with no rounding.

GitHub

import { Rating } from '@brika/clay/components/rating';

/**
 * Three read-only ratings at different fractional values (3.75, 2.3, 0.5) shown across all three size variants, demonstrating sub-star fill with no rounding.
 */
export default function RatingFractionalDemo() {
  return (
    <div className="flex flex-col items-start gap-3">
      <Rating value={3.75} aria-label="3.75 out of 5 stars" size="lg" />
      <Rating value={2.3} aria-label="2.3 out of 5 stars" />
      <Rating value={0.5} aria-label="0.5 out of 5 stars" size="sm" />
    </div>
  );
}

Interactive

Whole-star selection via hover and click, shown in uncontrolled, controlled, and disabled modes with Arrow-key keyboard support.

GitHub

'use client';

import { useState } from 'react';
import { Rating } from '@brika/clay/components/rating';

/**
 * Whole-star selection via hover and click, shown in uncontrolled, controlled, and disabled modes with Arrow-key keyboard support.
 */
export default function RatingInteractiveDemo() {
  const [controlled, setControlled] = useState(3);
  const [observed, setObserved] = useState<number | null>(null);
  return (
    <div className="flex flex-col items-start gap-5">
      <div className="flex flex-col gap-1">
        <span className="text-xs text-muted-foreground">
          Uncontrolled (defaultValue=3)
        </span>
        <Rating
          defaultValue={3}
          size="lg"
          onValueChange={setObserved}
          aria-label="Rate this item"
        />
        <span className="text-xs tabular-nums text-muted-foreground">
          Last committed: {observed ?? '(not yet changed)'}
        </span>
      </div>

      <div className="flex flex-col gap-1">
        <span className="text-xs text-muted-foreground">
          Controlled (value={controlled})
        </span>
        <Rating
          value={controlled}
          onValueChange={setControlled}
          size="lg"
          aria-label="Rate this item"
        />
        <span className="text-xs tabular-nums text-muted-foreground">value={controlled}</span>
      </div>

      <div className="flex flex-col gap-1">
        <span className="text-xs text-muted-foreground">Disabled</span>
        <Rating
          value={controlled}
          disabled
          aria-label="Rating disabled"
        />
      </div>
    </div>
  );
}

Sizes

All three size variants (`sm`, `default`, `lg`) shown at the same 3.75 value for easy comparison.

GitHub

import { Rating } from '@brika/clay/components/rating';

/**
 * All three size variants (`sm`, `default`, `lg`) shown at the same 3.75 value for easy comparison.
 */
export default function RatingSizesDemo() {
  return (
    <div className="flex flex-col items-start gap-3">
      <div className="flex items-center gap-3">
        <span className="w-14 text-xs text-muted-foreground">sm</span>
        <Rating value={3.75} size="sm" aria-label="3.75 out of 5 (small)" />
      </div>
      <div className="flex items-center gap-3">
        <span className="w-14 text-xs text-muted-foreground">default</span>
        <Rating value={3.75} aria-label="3.75 out of 5 (default)" />
      </div>
      <div className="flex items-center gap-3">
        <span className="w-14 text-xs text-muted-foreground">lg</span>
        <Rating value={3.75} size="lg" aria-label="3.75 out of 5 (large)" />
      </div>
    </div>
  );
}

04 Accessibility

Accessibility

Display mode (no handler / readOnly set): uses role="img" with an aria-label defaulting to "Rated {value} out of {max}". Override with the aria-label prop.
Interactive mode: uses role="radiogroup" on the row; each star is a <button role="radio"> with aria-checked and aria-label ("N out of max"). The committed star (or star 1 when unset) is the roving tab stop.
Keyboard in interactive mode: ArrowRight/ArrowUp moves to the next star and commits it; ArrowLeft/ArrowDown moves to the previous star and commits it.
Each <FractionalStar> is aria-hidden; only the button label carries the accessible name.
Pass disabled to render the visual without interaction; buttons are absent and opacity is reduced.

05 Tokens 5 theme-overridable

Theme tokens

Every CSS variable Rating reads, with its default and the dotted path you'd write in a ThemeConfig JSON to override it. Set any of these in your theme to retune Rating without touching component code.

Rating tokens

5 tokens

ColorFill, border, and text colors.2

--rating-filled-colorcolorvar(--warning)
components.rating.filledColor
Fill and stroke color for stars at or below the rounded value. Defaults to `--warning` (amber) so the hue follows the theme without a hard-coded color.
--rating-empty-colorcolorcolor-mix(in oklch, var(--muted-foreground) 30%, transparent)
components.rating.emptyColor
Stroke color for stars above the rounded value. A 30% mix of `--muted-foreground` against transparent gives a faint ghost that reads on both light and dark surfaces.

GeometrySizes, lengths, and corner radii.3

--rating-star-size-smsize0.75rem
components.rating.starSizeSm
Star icon diameter at the `sm` size variant.
--rating-star-sizesize0.875rem
components.rating.starSize
Star icon diameter at the `default` size variant.
--rating-star-size-lgsize1.25rem
components.rating.starSizeLg
Star icon diameter at the `lg` size variant.

Override in a theme

Authoring a theme is plain JSON. Drop overrides under components.rating, the names are camelCase versions of the variable suffix.

jsonmy-theme.json12 lines

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "...",
  "accentSwatches": ["#000"],

  "components": {
    "rating": {
      "filledColor": "var(--warning)"
    }
  }
}

Then apply with applyTheme(myTheme) (see the theming guide), scope it to a subtree with themeToCssVars(myTheme, mode), or consume any token directly in your own JSX with the matching Tailwind utility (e.g. bg-rating-…) — see the chips on each token row.

06 API reference

API reference

Props specific to Rating. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.

<Rating />

passthrough

No wrapper-specific props, all attributes pass through to the underlying primitive.

<FractionalStar />

1 prop

fill*
number
No description.