Design a star rating widget

Requirements: two components hiding in one

A star rating is a row of usually five stars. Everyone has seen two versions of it. On a product page, the stars under the title show what other people think: 4.3 out of 5, from 1,204 reviews. In a review form, the same row of stars asks you what you think: you click the fourth star and your rating is 4.

They look almost the same, so teams often build one component with a readOnly flag. That is the first thing to question in the interview. The two versions answer different questions, take different input, and must sound different to a screen reader. A strong answer splits them early and then designs each one properly.

Questions to ask

Each question below changes a real decision. The middle column is what this guide assumes.

Functional requirements

• Show an average from 0 to 5 with a fractional fill, the number itself, and the review count, like "4.3 (1,204)".
• Let a signed-in user pick 1 to 5 stars with mouse, touch, or keyboard, and see which star they are about to pick before they commit.
• Show a word for each value, like "Terrible" to "Excellent", on hover and focus.
• Work inside a native form: submit under a name, support required, reset with the form, show a validation message.
• Save the user's own rating, update the shown average right away, and roll back if the save fails.
• Show a histogram of 5, 4, 3, 2 and 1 star counts that filters the review list.

Non-functional requirements

• Accessible: correct roles and names for both components, the standard radio group keyboard model, a visible focus ring, filled and empty stars that differ by shape and not only by color (WCAG 1.4.1), and 3:1 contrast for the star outlines (WCAG 1.4.11).
• Light: a product grid shows 48 cards, each with a display. The display must be pure HTML and CSS with no JavaScript, so it costs nothing to hydrate. The input can be a small client component, about 2 to 3 KB gzipped.
• Works before JavaScript loads: a review form submitted on a slow 3G phone must still send the rating.
• Correct under load: one person, one rating per item. Double clicks and retries must not create duplicate ratings.
• International: numbers formatted per locale ("4,3" in German), labels translated, stars fill from the right in Arabic and Hebrew.

Out of scope

Review text, photo uploads, moderation, fake review detection, and ranking reviews by helpfulness belong to a product reviews feature, not this component. Say so out loud, so the interviewer knows you chose to leave them.

What makes five stars hard

Most candidates draw five stars, add an onClick to each, and move on. That version works for one person: a sighted mouse user on a desktop. Here is what it misses, and every later chapter fixes one of these.

• It's two components. A display of 4.3 and an input for your 4 need different HTML, roles and data.
• It's a picture of a number. The display must say the number in words, draw fractions like 0.3 of a star, and always show the count.
• It's a form control in disguise. Choosing one value from five is a radio group; five buttons break the keyboard model, form submission, required and reset.
• It holds three values at once: the saved value, the value under the pointer (the hover preview), and the value on the server. Mixing them up gives stars that flicker, forget, or lie.
• It depends on color. Gold versus grey is lost on colorblind users, in high contrast modes and on paper.
• It writes to a shared number. The rater wants instant feedback; the server must count each person once.

The wireframe shows the three pieces this guide designs: the summary (stars, number, count), the histogram, and the rating input. The rest of the page is out of scope.

The display: drawing and saying 4.3 out of 5

Start with the read-only display, because it's on every product card and page. The naive version rounds the average with Math.round(4.3) and draws 4 gold stars and 1 grey star.

Three things go wrong. The picture lies: 4.3 and 4.0 look the same, and 4.6 jumps to 5 full stars. A screen reader hears silence, or "star, star, star, star, star" if each icon has alt text. And a lone row of stars hides how many people voted.

What a screen reader should hear

<div class="rating-summary">
  <span role="img" aria-label="Rated 4.3 out of 5" class="stars"
        style="--whole: 4; --part: 0.3">
    <!-- 5 empty star SVGs, then a .filled row of 5 clipped by CSS -->
  </span>
  <span aria-hidden="true">4.3</span>
  <a href="#reviews">1,204 reviews</a>
</div>

A screen reader typically announces "Rated 4.3 out of 5, image", then "1,204 reviews, link". The visible "4.3" is hidden from it because the image label already says it. When the count is not a link, put it in the label instead: "Rated 4.3 out of 5 from 1,204 reviews". With zero reviews, show "No reviews yet" as text, not five empty stars, which read as a rating of 0, the worst score.

Drawing 0.3 of a star

There are two common ways to fill part of a star. The clip approach stacks two rows: five empty stars below, five filled stars on top, and clips the top row so only the first 4.3 stars show. The gradient approach gives each star its own SVG linearGradient with two hard stops at the same offset, so the fourth star is fully gold and the fifth is gold up to 30% and grey after.

The clip has a trap. If you clip the top row at 4.3 / 5 = 86% of its width, you forget the gaps between stars. With 20 px stars and 4 px gaps, the row is 116 px wide, and 86% is 99.8 px: only 3.8 px into the fifth star, about 19% of it instead of 30%.

The fix is to measure in stars and gaps: the filled width is 4 x (20 + 4) + 0.3 x 20 = 102 px. In CSS that's a calc() on custom properties, so it still needs no JavaScript.

.stars { --size: 20px; --gap: 4px; position: relative; display: inline-flex; gap: var(--gap); }
.stars .filled {
  position: absolute; inset: 0; display: inline-flex; gap: var(--gap);
  /* --whole and --part are set from the server: 4 and 0.3 */
  clip-path: inset(0 calc(100% - (var(--whole) * (var(--size) + var(--gap))
                                 + var(--part) * var(--size))) 0 0);
}
:dir(rtl) .stars .filled {
  clip-path: inset(0 0 0 calc(100% - (var(--whole) * (var(--size) + var(--gap))
                                       + var(--part) * var(--size))));
}

The gradient handles gaps naturally, because each star fills itself. Its cost is ids: fill="url(#half)" looks up a gradient by id in the whole document, so on a grid of 48 cards repeated ids make every card show the first card's fill, and each instance needs a unique id from React's useId. This guide picks the clip: one CSS rule, no ids, and one more rule for right-to-left.

Rounding: what the stars and the number show

Exact fill is honest, but a sliver under about 15% of a star is hard to see. Nearest half is easy to read, but at 4.75 it draws five full stars, which looks perfect; rounding down to the half avoids that. Our choice: exact fill, plus the number with one decimal from Intl.NumberFormat (4,3 in German), plus the count. Pass the locale explicitly, so the server and the browser produce the same string and hydration doesn't mismatch.

The input: five radios dressed as stars

Now the part people interact with. What is this control, really? The user picks exactly one value from a short, fixed list: 1, 2, 3, 4 or 5. HTML has a control for exactly that, a group of radio buttons sharing one name, and the stars are just how the radios look.

<fieldset class="rating-input">
  <legend>Your rating</legend>
  <input class="sr-only" type="radio" name="rating" value="1" id="r1" required>
  <label for="r1"><svg aria-hidden="true">...</svg>
    <span class="sr-only">1 star, Terrible</span></label>
  <!-- r2 to r4 the same -->
  <input class="sr-only" type="radio" name="rating" value="5" id="r5">
  <label for="r5"><svg aria-hidden="true">...</svg>
    <span class="sr-only">5 stars, Excellent</span></label>
</fieldset>

Two details matter. First, "visually hidden" means the sr-only pattern (1 px size, clipped, absolutely positioned), never display: none or visibility: hidden, which remove the radio from the Tab order and from the accessibility tree.

Second, the stars up to the checked one must fill. With :has(), supported in all major browsers since late 2023, the fieldset can ask which radio is checked and fill every label up to it. Older code reverses the DOM order and uses the ~ sibling combinator; :has() keeps the DOM in reading order, which screen readers need.

The keyboard model you get for free

The browser does all of this without a line of script. A screen reader announces something like "Your rating, group, 4 stars, Good, radio button, checked, 4 of 5". The exact words differ between NVDA, JAWS and VoiceOver, but every part comes from the native markup: the legend, the label, the role, the state and the position.

Letting people take a rating back

Once a radio in a group is checked, the user can't return to none checked: clicking a checked radio does nothing, and so does Space. That's right for a required review form, but in a quick "rate this" row people misclick and want to undo. Three ways to allow it:

• A visible "Clear rating" button, shown only when there is a value. Everyone can find it. When it's pressed and hides, move focus into the radio group, or focus falls to the page body and a keyboard user is lost.
• Click the checked star again to clear. Pointer users find it by accident, but keyboard users can't do it, so it can only be an extra.
• A sixth radio, "No rating", before the first star. It's fully native and works with no JavaScript, but it adds a stop to the arrow cycle and needs its own visual, often a small "x".

This design uses the visible button, with click-again-to-clear as a bonus for pointer users. The allowClear prop turns both on; with required, they stay off.

Half stars: ten radios or a slider

Some products allow half stars; Letterboxd, for example, lets members rate films from half a star to five. Five radios can't express 3.5, so the input needs ten values, 0.5 to 5. The pointer part is easy: each star gets two hit areas, so the left half of the fourth star means 3.5 and the right half means 4, swapped in right-to-left layouts. The real choice is the semantics.

Whichever you pick, the value sent to the server stays a number with a fixed set of allowed values, and the server checks it. A crafted request with rating: 3.7 or rating: 9 must be rejected with a 422, not stored.

Hover preview: showing a value without choosing it

On desktop, hovering the third star lights up stars one to three and shows the word "Okay"; moving away restores the saved value. That preview shows what a click will do. The bug to avoid is letting it become the value: if onMouseEnter calls setValue, passing the mouse over the stars changes the rating and fires a save.

So the input keeps two separate things. The committed value is what the radios hold and what a form submits. The preview value exists only while a mouse hovers, and the stars draw it when it's there. Only a click, a tap or a key changes the committed value, and only that fires onChange.

const [preview, setPreview] = useState<number | null>(null);
const shown = preview ?? value; // what the stars draw

function onPointerEnter(e: React.PointerEvent, star: number) {
  if (e.pointerType !== "mouse") return; // touch and pen: no hover
  setPreview(star);
}
// on the fieldset, so moving between stars doesn't flicker:
const onPointerLeave = () => setPreview(null);

Touch has no hover

On a phone, a tap also fires compatibility mouse events such as mouseenter, and the browser keeps the tapped element in the :hover state until the next tap elsewhere. A preview driven by mouseenter or :hover therefore sticks on the screen. Pointer events behave better, because pointerleave fires after the finger lifts, but then the preview only flashes, which is noise.

So the handler ignores pointers whose pointerType isn't mouse, and any CSS hover styles go inside @media (hover: hover), which matches only when the main pointer can hover. Phones then show the committed value only, and a tap commits straight away, which is what people expect on touch.

The preview can even live in CSS alone: when a label is hovered, fill it and every label before it, and unfill the ones after. That keeps the no-JavaScript version pleasant on desktop. The JavaScript version is still useful for the word under the stars.

Words for each star

Labels like "Terrible, Poor, Okay, Good, Excellent" make the scale concrete. They appear in two places: in each radio's accessible name ("4 stars, Good"), so screen reader users hear them, and in a small visible caption that shows the word for the previewed or chosen value. The caption is marked aria-hidden, because the name already says it. As the tooltip guide argues, a tooltip should never be the only place information lives; here a tooltip-style bubble would be only a visual extra.

Forms and the component API

The input will sit inside review forms written by other teams. Native radios already bring most form behavior; the job is to not break it, and to expose it through props that feel like any other input.

What the form gets from native radios

• Submission: radios with name="rating" send rating=4 in the form data, and nothing when none is checked, which the server reads as "no rating".
• Required: required on any radio makes the group required, and the browser blocks submit with its own message on the first radio. For a custom message, call setCustomValidity on the first radio and clear it when a star is picked, or show your own text under the stars, linked with aria-describedby.
• Reset: a form reset restores each radio to its default, the checked attribute in the HTML (defaultChecked in React).
• No JavaScript: the server-rendered HTML is a complete form. On a phone that hasn't loaded the bundle yet, tapping a star and pressing Submit still sends the rating.

Here is a trap that catches many React implementations. If the stars are drawn from React state, a form reset changes the radios but not the state, because reset fires no change event. The stars still show 4 while the form holds nothing.

The fix is to draw the committed fill from CSS (:checked with :has()) and use React state only for the hover preview. Then a reset, the checked state Firefox restores after a reload, and the no-JavaScript page all draw correctly with no syncing code. If the component is controlled (the parent owns the value), it should also listen for the form's reset event and call onChange(null).

The props

The component API lesson's rule applies: make the common case one line, and name things the way the platform does. Two exports, not one with a flag: StarRating for the input and RatingDisplay for the read-only picture.

type StarRatingProps = {
  value?: number | null;           // controlled; null means not rated
  defaultValue?: number | null;    // uncontrolled
  onChange?: (value: number | null) => void;
  onPreviewChange?: (value: number | null) => void; // hover, for analytics or a caption
  max?: number;                    // default 5
  precision?: 1 | 0.5;             // default 1
  labels?: string[];               // ["Terrible", ..., "Excellent"], one per whole star
  legend: string;                  // "Your rating"; required, it names the group
  name?: string;                   // form field name
  required?: boolean;
  allowClear?: boolean;            // shows "Clear rating"; ignored when required
  disabled?: boolean;
  size?: "sm" | "md" | "lg";      // maps to design tokens: 16, 24, 32 px
};

type RatingDisplayProps = {
  value: number;                   // the average, 0 to 5
  count?: number;                  // number of ratings
  max?: number;
  rounding?: "exact" | "half";     // default "exact"
  size?: "sm" | "md" | "lg";
  href?: string;                   // makes the count a link to the reviews
};

onChange gets a number or null, never an event, because consumers want the value. legend is required, because an unnamed radio group is an accessibility bug the type system can catch. There is no readOnly: a read-only rating is a picture, so teams use RatingDisplay instead of five disabled radios that a screen reader would announce as unavailable controls. disabled stays for the short moments when the input exists but can't be used.

Visual design: stars that survive any screen

The stars look simple, but they are shown at 16 px on a product grid and 32 px in a review form, in light and dark themes, in Windows high contrast mode, in right-to-left languages, and sometimes printed. The way you draw a star decides which of those still work.

Filled and empty must differ by shape, not just color

The classic design is gold filled stars and grey filled stars, and it fails three groups of people. Users with color vision deficiency may see gold and grey as similar. Gold #F5A623 on white has a contrast of about 2 to 1, under the 3 to 1 that WCAG 1.4.11 asks of graphics that carry meaning.

The third group uses forced colors mode (Windows contrast themes), where the browser swaps author colors for a small palette of system colors such as Canvas and CanvasText. Stars drawn as text glyphs or CSS backgrounds all turn the same system color, so every star looks filled. Inline SVG keeps hard-coded fills by default, so gold and grey stay as they are, ignore the user's theme, and can vanish against its background.

The fix is to make the difference a shape: filled stars are solid, empty stars are outlines. Both use currentColor, so in forced colors mode the SVG takes its parent's forced text color and the shapes still read clearly. For full control, an @media (forced-colors: active) rule can color the stars CanvasText and the input's chosen stars Highlight, as native controls do; check it with the browser's forced colors emulation. In normal mode, a darker stroke around the gold brings the outline to 3 to 1.

A focus ring on a hidden input

The hidden radios' own focus ring is invisible, so move it to the star: input:focus-visible + label gets a 2 px outline with an offset. Use outline, not box-shadow: forced colors mode removes box shadows but keeps outlines, in a system color. :focus-visible matches keyboard focus and usually not mouse clicks, like native controls.

Right to left

In Arabic or Hebrew, the first star sits on the right and the stars fill from right to left. A flex row does the layout for free, because flex follows the writing direction. Two places need care: the display's clip must cut from the other side (the :dir(rtl) rule from the display chapter), and the half-star hit areas swap. The star shape is symmetric, so it never needs mirroring, but do check which way the arrow keys move in your target browsers and screen readers.

Architecture and data: who owns which number

Zoom out to the product page. It shows three numbers: the average and count everyone sees, the histogram of how many people gave each star, and my rating, the signed-in user's own value. They come from different places and change at different speeds, so they live in different places.

The data model

type Stars = 1 | 2 | 3 | 4 | 5;

type RatingSummary = {
  productId: string;
  histogram: [number, number, number, number, number]; // counts for 1 to 5 stars
  count: number;      // sum of the histogram
  average: number;    // exact, e.g. 4.264; the UI rounds for display
  updatedAt: string;  // ISO time, for cache checks
};

type MyRating = {
  productId: string;
  value: Stars | null; // null: not rated
  updatedAt: string | null;
};

// Lives only in the component: never sent, never cached.
type RatingUiState = { preview: Stars | null; saveState: "idle" | "settling" | "saving" | "failed" };

Why send the histogram instead of just the average? Because the client must update the average when you rate, and it can't do that correctly from a rounded number.

Take 1,204 ratings with counts of 64, 42, 108, 288 and 702 for 1 to 5 stars. The sum of all stars is 64 + 84 + 324 + 1,152 + 3,510 = 5,134, and the average is 5,134 / 1,204 = 4.264, shown as 4.3. Add a 5-star rating and it becomes 5,139 / 1,205 = 4.265, still 4.3. With whole counts the math is exact, so the client and the server always agree.

The figure follows both directions. Reads: the counters feed the page HTML, which the CDN caches and the browser draws before any JavaScript runs; my rating is a separate, private request. Writes: the island changes the store first, the API client sends one PUT, and the summary in the response replaces the optimistic one.

The histogram: the shape behind the average

An average of 3.0 can mean everyone thinks the product is okay, or that half love it and half hate it. The histogram, five bars for 5 down to 1 star, shows which. On a product page it also works as a filter: clicking the 1-star bar shows only 1-star reviews, the quickest way to see the worst complaints.

Each bar is a link, like ?stars=1, whose text is the full fact: "1 star, 64 reviews, 5%". The bar itself is a decorative div sized from the percentage and hidden from screen readers, because the link text already says it. Links, not buttons, because the result is a new URL that can be shared and reloaded.

The selected filter gets aria-current="true" and a visible "Clear filter" link. When the review list updates in place, move focus to the list heading or announce "Showing 64 one-star reviews" in a polite live region, so keyboard and screen reader users know something happened.

One small trap: rounded percentages may not add up to 100. With counts of 702, 288, 108, 42 and 64, the exact shares are 58.3, 23.9, 9.0, 3.5 and 5.3, which round to 58, 24, 9, 3 and 5: a total of 99. If the design needs 100, use the largest remainder method: round every share down (58, 23, 8, 3, 5), then give the 3 missing points to the largest fractions (8.97, 23.92 and 3.49), which gives 58, 24, 9, 4 and 5.

Format each share with Intl.NumberFormat and style: "percent", because languages differ in where the sign goes and whether a space comes before it, as the poll widget guide shows. Consider hiding the bars when a product has only a handful of ratings, because two reviews make a dramatic but meaningless chart.

Submitting a rating: instant, correct, and counted once

In a review form, the rating goes with the form. The standalone "rate this" row is different: a click must save on its own. The naive version calls POST /ratings with { productId, stars } on every change and then refetches the summary.

Count what goes wrong. A retry after a timeout can store a second rating. A keyboard user arrowing from 1 to 4 sends three requests, the old average shows until the refetch returns, and if two requests race, the older one can land last.

PUT /api/products/p_812/my-rating
Content-Type: application/json

{ "value": 4 }

HTTP/1.1 200 OK
{ "myRating": { "value": 4, "updatedAt": "2026-10-20T16:02:11Z" },
  "summary": { "histogram": [64, 42, 108, 289, 702], "count": 1205,
               "average": 4.264 } }

DELETE /api/products/p_812/my-rating      -> 200 with the new summary
PUT with { "value": 9 }                   -> 422 { "error": "value must be 1 to 5" }
Too many writes                           -> 429, Retry-After: 30

Optimistic update of my rating and of the average

Rating should feel instant, and it almost always succeeds, so it's a good fit for an optimistic update: change the screen first, then send the request, and undo the change if it fails. It's the same move as the vote in the poll widget guide. On click, save a snapshot of the summary and my rating, then change both locally.

My rating becomes 4. In the histogram, the old value's bar loses one (if there was an old value) and the 4-star bar gains one; the count grows only if there was no old value. The average is recomputed from the new histogram. When the response arrives, the server's summary replaces the local one, which also picks up other people's ratings.

Wait for the value to settle, and send one request at a time

Arrow keys produce a burst of values, and so does a user who changes their mind. Two rules keep the network calm. First, settle: after a change, wait about 500 ms with no further change before sending; the stars update instantly, and only the request waits. If the page is hidden (visibilitychange) while a value waits, send it at once with fetch and keepalive: true, so the request survives the tab closing.

Second, one at a time: never have two writes in flight. If the value changes while a PUT is out, remember only the newest value and send it when the first returns. Otherwise a PUT of 3 and a PUT of 4 can reach the server in the wrong order, and 3 wins. Aborting the first request doesn't help, because the server may already be processing it.

These two rules also keep a normal user far below the server's rate limit, for example 30 rating writes per user per minute, which stops scripts from flooding the counters. If the server still answers 429, the client keeps the optimistic value, waits for the time in Retry-After, and tries once more before rolling back with a message.

When it fails

• Network error, timeout or 5xx: the server may have saved the value before the answer was lost. PUT is idempotent, so retry the same value once or twice with backoff, as the optimistic updates lesson advises. If that fails, roll back the stars and the summary and show "Couldn't save your rating. Try again" in a polite live region next to the stars, keeping focus where it is.
• 401, signed out: a signed-out user sees the stars with "Sign in to rate". Clicking a star keeps the value in sessionStorage through sign-in and applies it on return, so the intent isn't lost.
• 422: a bug or a tampered request. Roll back and log it; the user can't fix it.
• Clear: DELETE is optimistic too: the stars empty, the histogram bar and count drop by one, and failure restores them.

Testing the widget

A star rating is small enough to test thoroughly, and most of its bugs are in behavior and semantics, which tools can check. Here is what each testing layer covers for this component.

• Unit tests for the math: the clip width for 4.3 with gaps, half-star rounding (4.24, 4.25, 4.75), the average and percentages from a histogram, and the optimistic histogram change for new, changed and cleared ratings.
• Component tests with Testing Library: getByRole("group", { name: "Your rating" }) and getByRole("radio", { name: /4 stars/ }) only work if the semantics are right. Then test arrows, Space, reset, required, and that hovering never calls onChange.
• Display tests: getByRole("img", { name: "Rated 4.3 out of 5" }) exists, and with zero reviews it doesn't.
• Network tests with a mocked API: a rapid 2, 3, 4 sends exactly one PUT with 4; a 500 that outlasts the retries rolls back and shows the error; a 429 waits for Retry-After.
• Automated accessibility checks: axe on the display, the empty and checked input, and the error state. It catches missing names and low contrast, not keyboard logic.
• End to end and visual tests: a keyboard-only run through the review form in real browsers, and screenshots in light, dark, forced colors (Playwright can emulate forced-colors: active) and right to left.
• Manual screen reader passes: NVDA with Firefox or Chrome, VoiceOver with Safari on macOS and iOS, TalkBack on Android.

Watch production too: log save failures by status code, and track how often people change or clear a rating within a few seconds. A spike in quick changes often means misclicks, for example stars too small to tap.

Running it in the interview

A star rating is usually a 30 minute question, and the interviewer is checking whether you see past the picture. The strongest move is to split the two components in the first five minutes. Here is one way to spend the time.

Draw the wireframe first, because it makes the split obvious, then the radio anatomy. Leave the architecture for later: for a component question it's three boxes, and the interviewer cares more about the HTML than about servers.

Follow-up questions to expect