Widget Setup

Installation

Add the widget to your product page template:

<div id="simplerreviews"></div>
<script>
  window.__simplerreviews = {
    shopDomain: "{{ shop.permanent_domain }}",
    productId: "{{ product.id }}",
  };
</script>
<script src="https://cdn.simplersuite.co/widget.js" async defer></script>

Configuration Options

The window.__simplerreviews object accepts:

Property	Type	Required	Description
shopDomain	string	Yes	Your .myshopify.com domain
productId	string	Yes	Shopify product ID
apiUrl	string	No	Custom API URL (for self-hosted)
customerEmail	string	No	Logged-in customer’s email (from Liquid {{ customer.email }}). Enables interactive badge ratings.
customerName	string	No	Logged-in customer’s name (from Liquid {{ customer.name }}). Used as the author name for badge ratings.

Star Rating Badge

Add a compact star-rating badge near the product title that links to the full reviews section. Place a <div id="simplerreviews-badge"></div> element anywhere on the page:

<!-- Near the product title -->
<div id="simplerreviews-badge"></div>

<!-- Full reviews section (further down the page) -->
<div id="simplerreviews"></div>

<script>
  window.__simplerreviews = {
    shopDomain: "{{ shop.permanent_domain }}",
    productId: "{{ product.id }}",
    customerEmail: "{{ customer.email }}",
    customerName: "{{ customer.name }}"
  };
</script>
<script src="https://cdn.simplersuite.co/widget.js" async defer></script>

The badge displays the aggregate star rating and review count (e.g. ★★★★☆ 24 reviews). Clicking it smooth-scrolls to the full reviews widget.

Badge-only mode

You can use the badge without the full reviews widget. If only #simplerreviews-badge exists on the page (no #simplerreviews), the widget script will fetch the summary and render just the badge.

Interactive badge ratings

When badge ratings are enabled in Settings → Widget, logged-in customers can submit a star rating directly from the badge — one click, zero friction. Customer identity comes from Liquid template variables (customerEmail and customerName), so no login form is needed.

Customer state	Badge behavior
Not logged in	Display-only. Shows “Log in to rate this product” tooltip on click, then scrolls to reviews.
Logged in (require purchase ON, not a buyer)	Display-only. Shows “Purchase this product to rate it” tooltip.
Logged in (require purchase ON, is a buyer)	Interactive. Clicking a star submits instantly.
Logged in (require purchase OFF)	Interactive. Clicking a star submits instantly (marked unverified if not a buyer).

How It Works

1. The widget script loads asynchronously (never blocks page rendering)
2. Reads configuration from window.__simplerreviews
3. Fetches the review summary from the edge cache (~10ms)
4. Renders the rating summary, distribution, and first page of reviews
5. Lazy-loads the photo lightbox, submission form, and pagination as needed

Performance

• Bundle size: <5KB gzipped
• First render: <100ms after script loads
• API latency: <10ms from edge cache
• Zero layout shift: Fixed-height containers prevent CLS