Brickv0.1.12
Rating
Forms & choicesBrick 0.1.12

Rating

Rating is Brick's styled score input and aggregate display. Root and Item expose one accessible Atom-backed slider for choosing a score. Display presents repeated-star aggregate artwork; Summary presents one star beside a visible numeric value.

Live example

Built from the published package

Interactive
Choose with confidence

Know when Rating is the right part

Use it when

Use Root and Item when a person chooses a score on a short ordered scale, such as one to five stars. Use Display for a familiar repeated-star average and Summary for a compact one-star numeric aggregate. Fractional values are supported in every mode.

Choose another path when

Use Slider for a general numeric setting and Radio Group when choices have distinct meanings. Do not use a read-only Root for an aggregate score: it remains a focusable slider. Use Display instead.

Installation and imports

tsx
import { Rating } from "@flowstack-ui/brick/rating";
import { Field } from "@flowstack-ui/brick/field";
import "@flowstack-ui/brick/styles.css";

The complete stylesheet above is the recommended default. For a measured route-aware build, replace it with the shared foundation and this component's stylesheet:

tsx
import "@flowstack-ui/brick/styles/core.css"; // once at the application root
import "@flowstack-ui/brick/styles/rating.css";

Add the modular stylesheet for every other Brick component the route renders. Do not combine modular styles with styles.css or tokens.css.

Quick start

tsx
<Field.Root>
  <Field.Label>Product rating</Field.Label>
  <Rating.Root defaultValue={3} name="rating">
    {[1, 2, 3, 4, 5].map(value => <Rating.Item key={value} value={value} />)}
  </Rating.Root>
  <Field.Error>Choose a rating.</Field.Error>
</Field.Root>

<Rating.Display value={4.5} label="4.5 out of 5 stars" size="sm" />

<Rating.Summary
  value={4.8}
  valueText="4.8"
  label="4.8 out of 5 stars"
  size="sm"
/>

Visual recipes and states

Recipes change paint and artwork geometry only. Atom state attributes drive disabled, read-only, invalid, required, value, and direction presentation. Repeated activation keeps the selected value stable by default; enable allowClear only when the product intentionally supports clearing to the minimum.

Examples

tsx
<Rating.Root aria-label="Service rating" defaultValue={3.5} step={0.5} allowClear>
  {[1, 2, 3, 4, 5].map(value => <Rating.Item key={value} value={value} />)}
</Rating.Root>
Public contract

API

Start with the public parts and root options below. Components with multiple parts separate each area into its own named subsection.

PropValuesDefault
sizesm, md, lgmd
toneaccent, neutralaccent
variantsolid, outlinesolid
allowClearbooleanfalse

Root forwards Atom's controlled and uncontrolled value, min, max, step, largeStep, direction, form, validation, and value-label APIs. Item accepts optional decorative artwork. Named exports are Rating, RatingRoot, and RatingItem with RatingRootProps, RatingItemProps, RatingSize, RatingTone, and RatingVariant types.

Display requires numeric value and a localized label. It accepts max, defaulting to 5, plus the same size, tone, and variant recipes. Named exports also include RatingDisplay and RatingDisplayProps.

Summary requires numeric value and a localized label. It accepts max, size, tone, and optional localized valueText. Named exports also include RatingSummary and RatingSummaryProps.

Shared responsibility

Accessibility

Atom owns the slider role, current/range/value text, keyboard and pointer input, fractional selection, direction, validation, Field relationships, submission, reset, and cancellation. Items and artwork stay hidden from assistive technology. Disabled Rating leaves tab order; read-only Root remains focusable. Display and Summary expose one localized image label and no control semantics or tab stop. True pointer cancellation rolls back, while capture loss finalizes the live value.

Responsive behavior

Brick preserves 44px item targets, narrow containment, proportional RTL clipping, forced colors, reduced motion, zoom, and coarse-pointer input. A drag can cross gaps and the complete item scale while vertical page scrolling remains available.

Stable visual contract

Styling and tokens

Customization

Prefer recipes, then scope public variables: <Rating.Root style={{ "--brick-rating-fill-color": "rebeccapurple" }} />. Item children replace the default star artwork and remain decorative.

Tokens and CSS hooks

Stable classes include .brick-rating, .brick-rating--display, .brick-rating-summary, .brick-rating__item, .brick-rating__artwork, and .brick-rating__star. Public variables are --brick-rating-item-size, --brick-rating-gap, --brick-rating-empty-color, and --brick-rating-fill-color. Root exposes data-size, data-tone, data-variant, and the stable data-slot value rating; Item uses rating-item, Display uses rating-display, and Summary uses rating-summary.

Advanced reference

Open these details only when you need to inspect DOM ownership, native forwarding, or lower-level composition.

Maintainer resources

Tests, playground evidence, source notes, and release history remain available without crowding the plug-and-play guide.
Source docsChangelogPlayground