Design product ratings and reviews

Requirements, and what makes reviews hard

A review is one customer's opinion of one product: a star rating from 1 to 5, usually a title and some text, sometimes photos. A rating can also come alone, with no text. The reviews section is the part of the product page that sums these up and lists them. Shoppers read it more than almost anything else on the page, because it's the only part the seller didn't write.

Several pieces already have their own guide here. The stars themselves (the input and the read-only display) are the star rating guide. The rest of the product page, gallery, price, and buy box, is the Amazon guide. Threaded replies are the comments thread guide, and photo uploads are the file uploader guide.

This guide covers the reviews feature as a whole: how the summary, the list, the votes, and the form fit together, and the decisions that make it honest, fast, and findable.

Start with questions. Each answer below changes something in the design. The middle column is what this guide assumes.

Functional requirements

• Summary: average rating to one decimal, total count, and a 5-row histogram whose bars are links that filter the list.
• List: 10 reviews per page, sort by 4 orders, filter by stars, verified, photos, variant, and keyword, with a count of matching reviews.
• Review card: stars, title, author, date, variant, badges, text with Read more, photos in a lightbox, a seller reply, translation toggle, helpful button, and report link.
• Helpful votes: one per signed-in user per review, can be undone, shown as a count.
• Write a review: eligibility check, stars, title, text, photos, pros and cons, a saved draft, guidelines, then a pending state until approved. Authors can edit and delete.

Non-functional requirements

• Fast product page: the reviews must not hurt Largest Contentful Paint (LCP, good is 2.5 seconds or less) and must not shift the layout (Cumulative Layout Shift, CLS, 0.1 or less).
• Fast interactions: a filter or sort change shows new results in under 500 ms at p75 on a mid-range phone; a helpful vote feels instant (Interaction to Next Paint, INP, at most 200 ms).
• Honest: the numbers shown match the reviews behind them, nothing is hidden because it is negative, and paid or gifted reviews are labelled.
• Findable: search engines see the rating and the first reviews in the HTML.
• Accessible: every part works with a keyboard and a screen reader, including the histogram and filters.

Out of scope

Questions and answers about the product (a separate feature with its own threading), seller ratings, the moderation tools staff use, and the machine learning models that score reviews. We design the shopper-facing parts and the contract with those systems.

What makes reviews hard

A reviews section looks like the easiest part of a product page: some stars and a list. Five properties make it harder than it looks, and the later chapters answer them one by one.

1. The numbers are small and skewed. Most products have a handful of reviews, and ratings bunch up at 5 stars. An average of 5.0 from 2 reviews and 4.6 from 9,000 reviews are not the same kind of fact, yet a naive UI shows them the same way.
2. Order decides what people read. Shoppers read the first 3 to 5 reviews and stop. Whatever sort sits on top shapes the buying decision more than the other 84,995 reviews. A good default sort is a ranking problem, not an ORDER BY date.
3. The list has many dimensions. 4 sorts, 5 star filters, verified, photos, 30 variants, and a keyword make thousands of possible views. Each must be shareable, survive Back, and load fast. That is search-page state on a product page.
4. It sits low on a heavy page. Reviews are below the fold of a page that already fights for LCP with a big product image. Yet the rating and the first reviews must be in the HTML for search engines. Fast and findable pull in opposite directions.
5. Trust is the product. Fake reviews, paid reviews, and hidden negative reviews destroy the value of the whole section. Since October 2024 the US Federal Trade Commission has a rule that makes several of these practices illegal, and parts of it show up as UI requirements: labels, disclosure, and what you may not hide.

Notice what is not on the list: real-time updates. A new review on a product with 9,000 reviews changes nothing a shopper would notice in the next minute. Reviews are read-heavy and slow-changing, so caching and server rendering do most of the work, and we can spend our effort on ranking, state, and trust.

The rating summary: average, count, and histogram

The summary is the block at the top of the reviews: a big number like 4.6, stars that show it, the number of ratings, and five bars from 5 stars down to 1. It's small, but it's what most shoppers read instead of the reviews, and it shows up in search results. Three decisions hide in it.

Always show the count next to the average

The naive summary is an average and stars: 4.8. Compare two products: A has 4.8 from 5 ratings, and B has 4.6 from 9,214 ratings. Without counts, A looks better. With counts, most shoppers trust B, and they are right to: one angry 1-star buyer would pull A down to 4.2, while B would still show 4.6.

So the count is part of the rating, not decoration. Show it right next to the stars (4.6 out of 5, 9,214 ratings), format it for the locale with Intl.NumberFormat, and say "ratings" if star-only ratings are counted, "reviews" if only written reviews are. Mixing the two words is a common bug: the summary says 9,214 and the list says 1,207 reviews, and shoppers think reviews are being hidden. Label both: "9,214 ratings, 1,207 with text".

Perfect scores are not as strong as they look either. A 2017 report by Northwestern University's Spiegel Research Center found that purchase likelihood peaked for average ratings between about 4.0 and 4.7 and fell as ratings got closer to 5.0; the authors' reading is that shoppers see a perfect score as too good to be true. That's another reason to show the distribution, not only the average.

Display the average to one decimal, computed on the server from exact sums (sum of stars / count), never from the rounded percentages. The stars beside it use a partial fill for the fraction; the star rating guide covers that display and its accessible name.

Making the histogram add up to 100%

Each bar shows a share of ratings. Round each share on its own and the total can be 99% or 101%. Take a new product with 7 ratings: five 5-star, one 4-star, one 3-star. The true shares are 71.43%, 14.29%, and 14.29%, which round to 71 + 14 + 14 = 99%.

It can overshoot too. With 200 ratings split 101, 49, 49, 0, 1, the shares are 50.5%, 24.5%, 24.5%, 0%, and 0.5%, and rounding half up gives 51 + 25 + 25 + 0 + 1 = 102%. Shoppers notice, and support gets tickets asking where the missing review went.

// counts[0] is 5 stars ... counts[4] is 1 star
export function percentages(counts: number[]): number[] {
  const total = counts.reduce((a, b) => a + b, 0);
  if (total === 0) return counts.map(() => 0);
  const result = counts.map((c) => Math.floor((c * 100) / total));
  const remainder = counts.map((c) => (c * 100) % total);
  let left = 100 - result.reduce((a, b) => a + b, 0);
  const order = counts
    .map((_, i) => i)
    .sort((a, b) => remainder[b] - remainder[a] || a - b);
  for (const i of order) {
    if (left === 0) break;
    result[i] += 1;
    left -= 1;
  }
  return result;
}
// percentages([5, 1, 1, 0, 0]) -> [72, 14, 14, 0, 0]
// percentages([1, 1, 0, 0, 1]) -> [34, 33, 0, 0, 33]

Bars are filter links

Shoppers click the 1-star bar to read the complaints. Make each bar a real link, <a href="?stars=1#reviews">, not a div with a click handler. A link works before JavaScript loads, can be opened in a new tab, has a URL to share, and is announced as a link. With JavaScript loaded, the click is intercepted and the list refetches in place (the filters chapter).

• A bar with 0 ratings is plain text, not a link: a filter that returns nothing is a dead end.
• The selected bar shows a pressed look and a "Clear" link next to it, so the filter is visible and reversible.
• Filtered URLs carry a noindex robots meta tag, so search engines don't index five copies of the page. Google's pagination guide recommends exactly this for filter and sort variations of a list.

Ranking products fairly: raw average vs Bayesian average

The summary shows one product's rating. But the same numbers also rank products: "Sort by customer rating" on a category page, a "Top rated" carousel, the order of search results. The reviews feature owns the score these use, so the frontend engineer should know how it's made and what the UI may claim about it.

The naive ranking sorts by raw average. Here is what that does to five headphones in one category:

Product A is first because two people (maybe the seller's friends) gave 5 stars. That's not a ranking, it's a lottery that rewards small samples, and it invites fake reviews: two or three fake 5-star ratings beat 3,000 honest ones.

Some stores go further and display a weighted rating. Amazon, for example, says its star ratings come from models that weigh factors such as how recent a review is and whether the reviewer bought the product, not a simple average. That is a valid product choice, but it needs a clear explanation on the page. In an interview, displaying the raw average and ranking by a separate score is simpler to build, explain, and audit.

How the Bayesian average works

Think of C as the number of "imaginary average reviews" every product starts with. Product A has 2 real ratings of 5 and 20 imaginary ratings of 4.1: (20 * 4.1 + 10) / 22 = 92 / 22 = 4.18. Product B has 900 real ratings averaging 4.6, which swamp the 20 imaginary ones: (82 + 4,140) / 920 = 4.59. With few ratings, the prior dominates; with many, the data does.

• m is the mean rating of the category (headphones may average 4.1, printers 3.6). Using a site-wide mean would punish categories that are rated harshly.
• C sets how skeptical you are. Common starting points are the 25th percentile of rating counts in the category (Algolia's guide uses it) or the mean count. Half our products have 5 or fewer ratings, so the 25th percentile would barely smooth anything; we start at C = 20 and tune it by checking where new and popular products land. Larger C means new products need more ratings to climb.
• Store count and sum per product, not the average, so every new rating is an O(1) update and both scores can be computed exactly.

type RatingStats = { count: number; sum: number };

export function bayesianScore(
  { count, sum }: RatingStats,
  categoryMean: number, // m, for example 4.1
  priorWeight: number, // C, for example 20
): number {
  return (priorWeight * categoryMean + sum) / (priorWeight + count);
}

// Display uses the raw numbers:
// rawAverage = sum / count, shown with the count

Sorting the list: what "most helpful" means

Shoppers read the first few reviews and stop, so the default sort is the most important ranking on the page. We offer four sorts: Most helpful (the default), Newest, Highest rating, and Lowest rating. The last three are plain columns with a tie-breaker: ORDER BY created_at DESC, id DESC or ORDER BY stars DESC, helpful_score DESC, id DESC. The id at the end makes the order total, which cursor pagination needs (next chapter).

Most helpful is the interesting one. The naive version is ORDER BY helpful_votes DESC. It has two failures that grow with time.

• Rich get richer. The first reviews to reach the top get read, so they get votes, so they stay on top. A review with 400 votes from launch week can't be beaten by a better one written later, because nobody scrolls far enough to vote for it.
• Stale advice. A 3-year-old review says "the battery lasts 2 days", but the maker changed the battery last spring. The product changed; the top of the list didn't.

A worked example with a one-year half-life

This formula discounts each review by its own age, so new votes on an old review also count for little. A variant decays each vote from the moment it was cast, the exponential decay Evan Miller describes for hot lists: an old review that keeps earning votes stays high, while launch-week votes fade. It needs a timestamp per vote, which the votes table has anyway, and the same hourly job.

Two details make either version work in practice. The + 1 gives every review a small starting score so zero-vote reviews can still be ordered by age. And the score is recomputed in bulk, not on every vote, so one vote doesn't make reviews jump while someone is reading. Try the half-life yourself:

Balance: the top positive and the top critical review

Ratings bunch at 5 stars, so the most helpful reviews are mostly positive. Some stores add a small block above the list: the most helpful positive review (4 or 5 stars) next to the most helpful critical one (1 to 3 stars). Amazon has shown a block like this, labelled Top positive review and Top critical review.

It costs one extra query, served from the same cache as the summary, and it answers the shopper's real question: "what do unhappy buyers say?" It also shows that critical reviews are not buried.

Filters, the URL, and pagination

A shopper with a question filters: "1-star reviews from verified buyers of the black one that mention battery". That is five dimensions (stars, verified, photos, variant, keyword) plus a sort. The search results page guide covers facets in depth; here we need a small version of the same machine inside a product page.

Where the list state lives

const SORTS = ["helpful", "recent", "high", "low"] as const;
type Sort = (typeof SORTS)[number];

export type ReviewQuery = {
  sort: Sort; stars: 1 | 2 | 3 | 4 | 5 | null;
  verified: boolean; media: boolean;
  variant: string | null; q: string;
};

export function parseQuery(p: URLSearchParams): ReviewQuery {
  const sort = SORTS.find((s) => s === p.get("sort")) ?? "helpful";
  const n = Number(p.get("stars"));
  const stars = n >= 1 && n <= 5 && Number.isInteger(n) ? (n as 1 | 2 | 3 | 4 | 5) : null;
  return {
    sort, stars,
    verified: p.get("verified") === "1",
    media: p.get("media") === "1",
    variant: p.get("variant")?.slice(0, 40) || null,
    q: (p.get("q") ?? "").trim().slice(0, 100),
  };
}

Normalizing matters for caching too: ?sort=helpful&stars= and ? are the same view, so they must produce the same cache key. Serialize back in a fixed key order and drop defaults.

Pages, Load more, or infinite scroll

A bestseller has 85,000 reviews; nobody reads them all, but some shoppers read 50. Offset pagination (?page=37) gets slow on deep pages and shows duplicates when new reviews arrive between requests. Cursor pagination (the pagination lesson) returns an opaque nextCursor that encodes the last row's sort key and id, so each page continues exactly where the last one stopped.

For the interaction, infinite scroll is a poor fit: the reviews sit above related products and the footer, which would keep running away. Use a Load more button that appends 10 reviews with a cursor. For search engines and no-JavaScript visitors, the server also renders plain numbered review pages at stable URLs (the SEO chapter).

Counts that match the filters

Show what the filters did: "87 reviews match: 1 star, verified, 'battery'". Star counts come free from the summary. Combined counts (1 star and verified and with photos) come from the search index that serves the list, which returns them with the results, the same way facet counts work on a search page.

For very large keyword matches, show "1,000+" instead of paying for an exact count. And when a filter combination returns 0, say so and offer a one-click "Clear filters", never an empty box.

What happens when a filter changes

1. The click updates the URL with history.pushState (through the router).
2. The list reads the new params; if the cache has that key, it shows it at once.
3. Otherwise it aborts any request still in flight with AbortController, so a slow old response can't overwrite a new one, and starts a new one.
4. The old results stay on screen, dimmed and marked aria-busy="true", instead of a skeleton that collapses the height and shifts the page.
5. Results arrive; the list swaps, and a polite live region announces "87 reviews". Focus stays on the control the user pressed.

The lab below puts the pieces together: histogram links, filter toggles, sorting, the URL they write, and helpful votes (the helpful votes chapter covers them in depth). Turn on "Fail next vote" to watch a rollback.

The review card: long text, photos, translations, and replies

One review packs a lot: stars and a title, the author and date, the variant they bought ("Color: Black"), badges, the text, pros and cons, photos, maybe a translation note and a reply from the brand, then Helpful and Report. Each piece has a decision behind it.

Read more without shifting the page

Reviews range from 3 words to 5,000 characters. Ten long reviews would make the list endless, so long ones are cut to about 6 lines with a Read more button. The naive way measures the text in JavaScript after render, then cuts it and adds the button. On a product page that means every long review renders full height, then jumps shorter after hydration: a layout shift on every card, counted against CLS.

.review-body {
  white-space: pre-line;
  overflow-wrap: anywhere;
}
.review-body[data-clamped="true"] {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 6;
  overflow: hidden;
}

Review text is plain text, always. Render it as a text node, never as HTML, keep line breaks with white-space: pre-line, and don't turn URLs into links (spammers love review links). The xss lesson covers why dangerouslySetInnerHTML on user content is the classic hole.

Photos and videos

• Thumbnails are small (72 by 72 CSS pixels), with width and height set so they reserve space, loading="lazy", and a srcset for 1x and 2x screens. The image-optimization lesson covers formats.
• Each thumbnail is a button that opens a lightbox dialog with the full image, the review's other photos, and a link back to the review text. The image carousel guide covers the swipe, keyboard, and preloading inside it.
• Above the list, a strip of "Photos from customers" collects media across all reviews: shoppers often want to see the product on real people before reading. It is its own paginated endpoint.
• Videos show a poster image and use preload="none", so nothing downloads until the shopper presses play. Never autoplay with sound.
• Alt text: shoppers rarely write it, so default to "Photo 2 of 4 from Maya's review" rather than an empty or file-name alt.

Translated reviews with Show original

A Spanish shopper sees reviews from Germany, Japan, and the US. The server translates reviews into the viewer's locale with a machine translation service, caches each translation by review id and language, and sends it in the list response with the original.

The card shows the translation with a line: "Translated from German. Show original". The toggle swaps text locally, with no request.

• Set lang on the review body to the language actually shown (lang="de" for the original), so screen readers switch voice and pronunciation and the browser hyphenates the text correctly. Google ignores lang and detects language from the visible text, so this attribute is for people, not for ranking.
• Keep keyword search working in both: index the original and the translations, so "batería" finds a German review about the battery.
• The translation-architecture lesson covers the interface strings; user content is different, because it can't be translated ahead of time by people.

Seller and brand responses

A brand can reply once to a review: "Sorry about the strap. Contact us for a free replacement." Show it under the review, indented, with a clear label ("Response from Sony, 3 days later") and a different background, so nobody mistakes it for the reviewer. It's one reply, not a thread: open discussion is the questions feature, and nested replies are the comments thread guide. Replies go through moderation too, and a seller can't edit or hide the review they reply to.

Badges

Badges are claims, and the server makes them. Verified purchase means the order system shows this account bought this product. Received free product or Incentivized review marks reviews written in exchange for something; disclosure is required (the trust chapter). Employee marks reviews by staff. The client renders badges from a list of codes in the response and never infers them, because a badge that is wrong is worse than no badge.

Helpful votes: instant, idempotent, one per person

Under each review: "52 people found this helpful" and a Helpful button. It's the input to the helpful sort, so it must be fair, and it's tapped a lot, so it must feel instant. The poll widget guide solved the same shape of problem for poll votes; this chapter reuses its rules (a retry never counts twice, an unknown result is retried, a clear failure rolls back) with a simpler request.

The naive version is POST /reviews/r_81/helpful, which adds one to a counter. A double tap adds two. A retry after a timeout adds another. Undo needs a second endpoint, and the server can't tell "vote" from "vote again".

The optimistic toggle and its rollback

Waiting 300 ms for the server before the button changes feels broken. So the button flips and the count moves at once, then the request confirms it (the optimistic-updates lesson). If it fails, the button and count go back to the last state the server confirmed, and a short message says "Couldn't save your vote".

Fast toggles need one more rule: only the latest intent matters. Keep at most one request in flight per review; if the user toggles again meanwhile, remember the latest desired state and send it when the first returns, if it differs. Sending one at a time also means a slow request for an old state can't land after a newer one.

Failures are not all alike, as the poll widget guide explains. A network error or a 5xx is unknown: the vote may have been saved. Because PUT is idempotent, the client can safely resend the same request two or three times with backoff before rolling back. A 429 (rate limited) or another 4xx is a clear answer, so the client rolls back at once.

type Saved = { helpful: boolean; helpfulCount: number };
const lastSaved = new Map<string, Saved>(); // the server's latest answer per review
const wanted = new Map<string, boolean>(); // the shopper's latest intent
const inFlight = new Set<string>();

// The guess: the last saved count, plus or minus one if the intent differs.
const guess = (s: Saved, want: boolean): Saved => ({
  helpful: want,
  helpfulCount: s.helpfulCount + (want === s.helpful ? 0 : want ? 1 : -1),
});

export async function setHelpful(id: string, want: boolean) {
  wanted.set(id, want);
  render(id, guess(lastSaved.get(id)!, want)); // instant
  if (inFlight.has(id)) return; // the running loop picks up the new intent
  inFlight.add(id);
  try {
    let saved = lastSaved.get(id)!;
    while (wanted.get(id) !== saved.helpful) {
      saved = await putVote(id, wanted.get(id)!); // retries network errors and 5xx
      lastSaved.set(id, saved);
    }
    render(id, saved);
  } catch {
    render(id, lastSaved.get(id)!); // roll back to the last confirmed state
    toast("Couldn't save your vote. Try again.");
  } finally {
    inFlight.delete(id);
    wanted.delete(id);
  }
}

One vote per person, and abuse

• Signed-in only. A signed-out tap opens sign-in and then sends the vote, so intent isn't lost. The server enforces one row per (user, review); the client can't.
• No votes on your own review. Hide the button for the author, and reject it on the server too.
• Rate limits. Over about 30 votes a minute from one account gets 429 Too Many Requests; the client rolls back and shows the message, without retrying in a loop.
• Counted is not the same as ranked. Votes from brand new accounts, or from accounts linked to the seller, can be shown in the count but given little or no weight in the helpful score. The score is computed server-side, so the client needs no change for this.

Writing a review: eligibility, the form, drafts, and pending

Many reviews start from a follow-up email after delivery ("How are your headphones?"), a few from the product page. Both open the same form. Its job is to collect a good review with little friction, never lose what the customer typed, and be clear about what happens after Submit.

Eligibility first

Before showing the form, the client asks GET /products/{id}/review-eligibility. The answer is one of: eligible (with the variant they bought, to prefill), already reviewed (with the review id, so we open it for editing instead), not purchased (allowed in some categories, without the Verified badge), or blocked (account restrictions). Don't hide the Write a review button when someone isn't eligible; show it and explain why on press. A missing button looks like a bug.

The form

• Stars, required, first. The star rating guide covers the radio-group input. Pressing a star from the email link can preselect it via ?stars=4.
• Title up to 120 characters, text up to 5,000 with a live counter, and optional pros and cons as short lines.
• Photos and video, uploaded as soon as they are picked, so Submit doesn't wait on them. The file uploader guide covers pre-signed uploads and progress. The server strips location data (EXIF GPS) from photos, because a review photo taken at home can reveal an address.
• Guidelines as 4 short lines beside the text box ("Talk about the product, not the delivery", "No personal details"), with a link to the full policy. A wall of rules above the form gets skipped.
• Validation on the client for speed and on the server for truth (the input-validation lesson). A gentle client hint when the text looks like an email address or phone number saves a rejection later.

Submit, then pending

Submit sends POST /reviews with an Idempotency-Key header (a random id made when the form opened), so a double click or a retry creates one review, not two. The server answers 202 Accepted with { id, status: "pending" }: accepted, not yet public. Automated checks run in seconds; some reviews wait hours or a few days for a person.

The author must see their review right away, or they'll write it again. The client inserts it at the top of their own view with a clear badge: "Pending: only you can see this. We'll email you when it's published." Other shoppers don't see it, and the summary doesn't count it. When moderation finishes, the author gets an email and an in-app notification, and the next load shows it published, or rejected with the reason and an Edit button.

Editing and deleting

Edits go back through moderation, otherwise anyone could post a clean review and edit in spam later. While the edit is pending, the last published version stays public and the author sees both, labelled. Changes to the stars alone go through the fast automated checks.

Deleting asks for confirmation, removes the review from the author's view at once, and the summary catches up when its cache refreshes (minutes). Helpful votes on a deleted review are dropped with it.

Moderation and trust: what the UI must and must not do

A reviews section is worth exactly as much as shoppers trust it. Moderation is mostly a backend system, but it decides states the frontend shows, and the law now shapes some UI choices directly. A frontend engineer who knows these rules avoids building something illegal by accident.

The moderation pipeline, from the client's view

1. Automated filters run within seconds: profanity and abuse, personal data (phone numbers, emails), links, duplicate text across accounts, and a language check.
2. Risk signals score how likely the review is fake. Common ones in industry write-ups include a burst of 5-star reviews in a short window, new accounts with no other activity, many reviews from one device or network, reviews that copy each other, and links between the reviewer and the seller. No single signal proves anything, so they feed a score, not an automatic verdict.
3. Human review handles the uncertain middle and every report from shoppers.
4. Outcome: published, or rejected with a reason the author can act on. Reports from shoppers can send a published review back for review.

For the client this means three states it must render (pending, published, rejected) and one action (Report, which opens a short dialog with reasons and sends POST /reviews/{id}/reports). Reported reviews stay visible until a person decides: hiding on the first report would let a competitor erase honest reviews.

The FTC rule on fake reviews

In August 2024 the US Federal Trade Commission (FTC) finalized its Trade Regulation Rule on the Use of Consumer Reviews and Testimonials (16 CFR Part 465). It took effect on October 21, 2024, and lets the FTC seek civil penalties for each violation. Among other things, it bans fake reviews (from people who don't exist or had no real experience with the product), buying reviews conditioned on a positive or negative sentiment, undisclosed reviews by a company's officers and managers, and review suppression.

Suppression has a precise meaning in the rule: implying that the reviews on display are all or most of the reviews submitted while some are withheld because of their rating or negative sentiment. Withholding reviews for reasons applied to every rating alike, such as abuse, another person's personal information, clearly false content, or a review the seller reasonably believes is fake, is allowed. Several parts turn into frontend requirements:

Review gating is the trick of asking "Did you enjoy your purchase?" first and only sending happy customers to the review form, while unhappy ones go to a private feedback box. It skews the ratings without hiding a single review.

The FTC's Endorsement Guides, revised in 2023, say advertisers should not procure, suppress, boost, or organize reviews in a way that distorts what consumers think, and Google's policy for business reviews forbids selectively asking happy customers for reviews. So the post-purchase email links every customer to the same review form, and the form never branches on the stars before submit.

Architecture, data model, and API

With the decisions made, we can draw the parts. One idea shapes the whole architecture: split public data from personal data.

The summary and the review list are the same for every shopper with the same filters, so a content delivery network (CDN) can cache them. "Did I vote on this?" and "my pending review" differ per user and must never be cached publicly. Mixing them in one response would make the whole section uncacheable, at 1,500 page views a second.

Why these boundaries? The summary is server-only because it must be in the HTML for search engines and it never changes on the client. Filters only touch the URL, so they can't drift from it. The form is its own route because it's large (uploads, validation, rich input) and only a few percent of visitors open it; shipping it with every product page would be waste.

Caching follows the split. The summary and anonymous list pages go out with Cache-Control: public, s-maxage=300, stale-while-revalidate=600, so the CDN serves them and refreshes in the background. A new review shows up in the summary within about 5 minutes, which is fine for a slow-changing feature.

Personal responses use Cache-Control: private, no-store. Writes (votes, reviews, reports) go straight to the origin and never through a cache.

Data model and API

The client holds five kinds of data, and each lives in a different place. Getting this right avoids the most common bugs: a filter that the URL and the list disagree on, a vote that shows pressed for the wrong user, a draft that leaks between accounts.

type ReviewSummary = {
  productId: string;
  ratingCount: number; // all ratings, with or without text
  reviewCount: number; // only the ones with text
  ratingSum: number; // average = ratingSum / ratingCount
  histogram: [number, number, number, number, number]; // 5 stars first
};

type Badge = "verified_purchase" | "free_product" | "employee";

type Review = {
  id: string; productId: string;
  stars: 1 | 2 | 3 | 4 | 5; title: string; body: string;
  pros: string[]; cons: string[];
  author: { displayName: string; avatarUrl: string | null };
  createdAt: string; editedAt: string | null;
  variant: Record<string, string> | null; // { color: "Black" }
  badges: Badge[];
  media: { id: string; kind: "image" | "video"; thumbUrl: string; fullUrl: string; width: number; height: number }[];
  lang: string; original: { title: string; body: string; lang: string } | null;
  sellerResponse: { body: string; createdAt: string; sellerName: string } | null;
  helpfulCount: number;
};

type MyReviewState = { myVotes: Record<string, boolean>; myReview: (Review & { status: "pending" | "published" | "rejected"; rejectReason?: string }) | null };

Endpoints

{
  "reviews": [{ "id": "r_81", "stars": 1, "title": "Strap broke in a month", "helpfulCount": 52, "...": "..." }],
  "nextCursor": "eyJzIjoxMi40LCJpZCI6InJfODEiLCJ2IjoxNzYxMDE2MDAwfQ",
  "matchCount": 87,
  "matchCountCapped": false,
  "facets": { "verified": 61, "media": 23, "variant": { "Black": 54, "White": 33 } }
}

Errors use one shape, { "error": { "code": "RATE_LIMITED", "message": "...", "retryAfter": 30 } }, so the client can map codes to messages: NOT_ELIGIBLE explains why on the form, RATE_LIMITED rolls back a vote, VALIDATION points at the field, and an expired cursor (CURSOR_EXPIRED) makes the list reload page one with the same filters.

SEO, performance, and accessibility

Reviews pull in two directions. Search engines want the rating and review text in the HTML, and stars in search results bring clicks. But the reviews sit far below the fold of a page whose LCP is the product photo, and every byte and script they add competes with it. The answer is to decide, part by part, what the server sends and what waits.

Structured data for review snippets

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Aria Wireless Headphones",
  "aggregateRating": { "@type": "AggregateRating", "ratingValue": 4.6, "reviewCount": 1207, "ratingCount": 9214 },
  "review": [{
    "@type": "Review",
    "author": { "@type": "Person", "name": "Maya R." },
    "datePublished": "2026-09-14",
    "reviewRating": { "@type": "Rating", "ratingValue": 5, "bestRating": 5 },
    "name": "Best noise cancelling I've owned",
    "reviewBody": "Wore them on a 12 hour flight..."
  }]
}

• A product snippet needs the product's name and at least one of review, aggregateRating, or offers. An AggregateRating needs ratingValue and at least one of ratingCount or reviewCount.
• Google's review snippet guidelines ask that marked-up ratings and reviews be visible on the page, about one specific product, not aggregated from other websites, and not fake or undisclosed incentivized reviews. If you mark up individual reviews, also mark up the aggregate rating.
• The self-serving rule (a business marking up reviews about itself) applies to LocalBusiness and Organization pages. A store marking up shoppers' reviews of a product it sells uses Product, which that rule does not cover.
• Rich results are never guaranteed; valid markup only makes the page eligible. Check it with the Rich Results Test.

Paginated review URLs

Load more serves people. For crawlers, the server also renders /p/aria-headphones/reviews?page=2 and so on: plain pages with 10 reviews each, linked with ordinary <a> tags at the bottom of the list and in Load more's href. Each page is its own canonical URL, as Google's pagination guide asks.

Google said in 2019 that it no longer uses rel="next" and rel="prev", so the links themselves are what matter. Filtered and sorted views carry a noindex robots meta tag, which is Google's recommendation for variations of the same list; a canonical pointing at the unfiltered page is only a hint, and a weak one when the content differs.

Loading the interactive parts on approach

const section = document.getElementById("reviews")!;
const io = new IntersectionObserver(
  (entries) => {
    if (!entries.some((e) => e.isIntersecting)) return;
    io.disconnect();
    void import("./reviews-islands").then((m) => m.hydrate(section));
    void loadMyReviewState(productId, visibleReviewIds(section));
  },
  { rootMargin: "1600px 0px" },
);
io.observe(section);
// A deep link to #reviews or ?stars= starts this at once instead.

• Images: thumbnails use loading="lazy" with width and height, so they never compete with the hero image for LCP and never shift layout.
• Rendering: review cards get content-visibility: auto with contain-intrinsic-size: auto 240px, so the browser skips layout and paint for cards far off screen.
• Interaction: a filter change updates the pressed state at once and wraps the list swap in startTransition, so the tap paints within the INP budget of 200 ms even when 10 new cards render.
• Weight budget: about 12 KB compressed of JavaScript for the islands, loaded on approach; the lightbox and the form are separate chunks loaded on use.

Accessibility: a histogram you can hear

A sighted shopper reads the summary in one glance: tall 5-star bar, small 1-star bar. A screen reader user gets whatever text we wrote. If the bars are empty divs with widths, they get nothing. The screen-readers lesson covers the general rules; here is how they apply to each part.

• The summary reads as one phrase: "Rated 4.6 out of 5, based on 9,214 ratings". The star icons are hidden with aria-hidden="true" because the text already says it.
• Histogram bars are links with the full meaning in their name: "5 stars, 72% of ratings, 6,634 ratings. Show these reviews." The visual bar is decoration. The selected bar adds aria-current="true", and zero bars are plain text.
• Filters that toggle in place (Verified, With photos) are <button aria-pressed> elements, grouped with a visible label. The sort is a native <select> with a label. Both keep focus where it was after the list updates.
• Result counts go to a polite live region (role="status"): "87 reviews, filtered by 1 star". Announce once, after results arrive, not on every keystroke in the keyword box.
• Load more moves focus to the first newly loaded review's heading, so keyboard users continue reading where the new content starts instead of landing back on the button.
• Each review is an <article> with its title as a heading, so screen reader users can jump review to review with heading navigation. The stars inside are text ("Rated 2 out of 5").
• Helpful is a <button aria-pressed> whose name includes the count: "Helpful, 52 people found this helpful". After a rollback, the error message goes to the same status region.
• Readable text: review body at the page's base size (at least 16 CSS pixels), line length under about 75 characters, and enough contrast for the gray meta text (4.5 to 1 for normal text).

The lightbox is a modal dialog: focus moves in, Escape closes it, focus returns to the thumbnail that opened it, and arrow keys move between photos. The modal dialog and image carousel guides cover these in depth. The review form uses visible labels, ties errors to fields with aria-describedby, and moves focus to the first invalid field on submit.

Running it in the interview

This question rewards breadth with a few sharp deep dives. Interviewers want to see that you know reviews are a ranking and trust problem, not a list with stars. Here is one way to spend 45 minutes.

Draw the wireframe first. It anchors every later decision in something visible, and it shows the interviewer you think from the shopper's side. Then pick deep dives that show judgment, ranking and votes, rather than spending ten minutes on CSS for stars.

Follow-up questions to expect