ProductReviews

Purpose

The ProductReviews component renders a section of the product page with the product's rating and its
published reviews. The merchant adds it to the product page from the page builder, where it is offered on the
product page only.

The component:

shows how the product's published reviews rate it: the average, the number of reviews and the per-star
breakdown;

lists the first page of the published reviews, newest first, rendered with the page;

reads the next pages on the client, through the Services SDK.

It shows the rating whatever the store's Show rating on product page setting says: that setting only
decides whether ProductSingle shows the rating next to the
product title.

The theme's shipped view is a minimal one: the rating summary, the list and a previous/next pager.

Inputs (model contract)

Model shape (storefront example)

{
  "productId": "Product Id",
  "rating": {
    "average": 4.5,
    "count": 12,
    "distribution": {
      "oneStar": 0,
      "twoStars": 1,
      "threeStars": 1,
      "fourStars": 2,
      "fiveStars": 8
    }
  },
  "reviews": {
    "items": [
      {
        "id": "Review Id",
        "authorName": "Sample name",
        "rating": 5,
        "comment": "Sample text",
        "createdAt": "2026-01-01T00:00:00.0000000+00:00",
        "purchasedVariantIds": ["Variant Id"]
      },
      "..."
    ],
    "page": 1,
    "pageSize": 10,
    "totalCount": 12,
    "totalPages": 2
  },
  "name": "ProductReviews",
  "view": "Default",
  "section": "SectionA",
  "settings": {
    "id": "Component Id",
    "section": "SectionA",
    "type": "NoirProductReviews",
    "name": "ProductReviews",
    "view": "Default",
    "cssClass": "",
    "header": "Sample text"
  },
  "translations": {
    "title": "Reviews",
    "reviewsCount": "reviews",
    "anonymous": "Customer",
    "previous": "Previous",
    "next": "Next"
  }
}

Required fields

settings.id

Optional fields

productId: the product of the page, for reading the next pages.

rating

average has two decimals; distribution counts the published reviews per star.

Null while the product has no published review: a product nobody rated has no rating, never a rating of
zero. Show no summary then.

The rating is recalculated a few seconds after a review is published, so just after the first one there
can be reviews while rating is still null. Decide on the summary and on the list separately.

reviews

The first page of the product's published reviews, newest first, 10 per page.

An empty page (items empty, totalCount 0) while the product has no published review.

authorName is the customer's name from the order, and may be null.

rating and reviews are both null while the store does not collect reviews, the company lacks the
Product reviews module, or the reviews could not be read. Render nothing then.

Reviews and ratings belong to the product, not to the store they were written in, so every store that
sells the product shows them.

settings.header, translations.*

Settings tokens used by the component

model.Settings.Id

model.Settings.CssClass

model.Settings.Header

JavaScript

Global object

Components/ProductReviews/Default.js exposes:

Liquid binds it via Alpine:

<section x-data='productreviewsdefault.initComponent({{ model.ProductId | serialize | escape }}, {{ model.Reviews | serialize | escape }}, {{ model.Translations.Anonymous | serialize | escape }})'>

initComponent(productId, firstPage, anonymousName)

Creates the Alpine state from the first page:

items, page, pageSize, totalPages: the page shown;

isLoading: true while a page is being read;

anonymousName: shown when a review has no authorName.

goTo(page)

Reads page with servicesreusabledefault.getProductReviews(productId, page, pageSize) and shows it. Does
nothing while a page is loading, or when page is out of range or already shown.

formatDate(value)

Formats createdAt as a date in the page's language.

Services / API calls

servicesreusabledefault.getProductReviews(productId, page, pageSize): GET
/api/product-reviews?productId=&page=&pageSize= (anonymous, pageSize at most 50). It returns the same
shape as reviews, and an empty page while the store does not show reviews. See
Services.

Dependencies

Alpine.js

servicesreusabledefault (Reusables/Services/Default.js)

Notes

Comments and author names are written by customers: render them with x-text or | escape, never as
HTML.

The component is not added to the default product page; add it in the page builder.

The rating next to the product title and on product cards is not part of this component: see
ProductSingle and the ShowRatingOn… flags in
LiquidGlobals.

Extras

Template behavior (Liquid + Alpine)

Renders nothing while there is neither a rating nor a published review.

Shows the rating summary only while rating is present, and the list only while it has items.

Shows the pager only when there is more than one page.

Loading state

This component has no skeleton loading state: it renders its content directly, and no --loading modifier class is applied.

ProductReviews

Purpose#

Inputs (model contract)#

Model shape (storefront example)#

Required fields#

Optional fields#

Settings tokens used by the component#

JavaScript#

Global object#

initComponent(productId, firstPage, anonymousName)#

goTo(page)#

formatDate(value)#

Services / API calls#

Dependencies#

Notes#

Extras#

Template behavior (Liquid + Alpine)#

Loading state#