Ratings and Reviews quick start

Show approved product reviews below the product details on your product pages. The list shows 20 reviews per page and includes page controls when more reviews are available.

The setup uses four parts: the drop-in package, an import map entry, an initializer, and the Product Reviews block. If your storefront already has scripts/initializers/ratings-reviews.js and blocks/product-reviews/, skip to Check the result.

Before you begin

Turn on product reviews and approve at least one review in the Admin. See Before you begin on the overview page.
Run your storefront locally. See Run your storefront locally.

Add the drop-in to your storefront

Install the package and create the files that connect the review list to your storefront.

Install the drop-in package from the root of your storefront project.
Terminal window
```
1
# Adds the package to package.json with an exact version.
2
npm install @dropins/storefront-ratings-reviews
3
# Copies the drop-in files into scripts/__dropins__/ for the browser.
4
npm run install:dropins
```
Your storefront’s .npmrc disables package install scripts to protect against supply-chain attacks. Run npm run install:dropins to copy the files that npm install skips. After it finishes, confirm that scripts/__dropins__/storefront-ratings-reviews/ exists.

In head.html, add the drop-in to the existing import map.

1
<script nonce="aem" type="importmap">
2
 {
3
   "imports": {
4
     "@dropins/storefront-pdp/": "/scripts/__dropins__/storefront-pdp/",
5
     "@dropins/storefront-ratings-reviews/": "/scripts/__dropins__/storefront-ratings-reviews/",
6
     "@dropins/storefront-recommendations/": "/scripts/__dropins__/storefront-recommendations/"
7
   }
8
 }
9
</script>

Add only the @dropins/storefront-ratings-reviews/ entry and keep your other entries. It maps imports in block code to the installed files under scripts/__dropins__/storefront-ratings-reviews/.

Create the initializer at scripts/initializers/ratings-reviews.js.

1
import { initializers } from '@dropins/tools/initializer.js';
2
import { initialize, setEndpoint } from '@dropins/storefront-ratings-reviews/api.js';
3
import { initializeDropin } from './index.js';
4
import { CORE_FETCH_GRAPHQL, fetchPlaceholders } from '../commerce.js';
5

6
// Loads label overrides from the placeholders/ratings-reviews.json sheet.
7
const labels = await fetchPlaceholders('placeholders/ratings-reviews.json');
8

9
await initializeDropin(async () => {
10
 // Reviews and review settings come from Commerce GraphQL, not Catalog Service.
11
 setEndpoint(CORE_FETCH_GRAPHQL);
12

13
 // Loads the store's review settings and saves them in the drop-in config.
14
 return initializers.mountImmediately(initialize, {
15
   langDefinitions: {
16
     default: { ...labels },
17
   },
18
 });
19
})();

CORE_FETCH_GRAPHQL supplies your Adobe Commerce GraphQL endpoint and store headers.
fetchPlaceholders loads custom labels from placeholders/ratings-reviews.json.
mountImmediately waits for the store’s review settings to load before initialization finishes.

For configuration options, see Ratings and Reviews initialization.

Create the block script at blocks/product-reviews/product-reviews.js.

1
import { config, getProductReviews } from '@dropins/storefront-ratings-reviews/api.js';
2
import { render as reviewsRenderer } from '@dropins/storefront-ratings-reviews/render.js';
3
import { Review } from '@dropins/storefront-ratings-reviews/containers/Review.js';
4
import { Pagination } from '@dropins/storefront-ratings-reviews/containers/Pagination.js';
5
import { readBlockConfig } from '../../scripts/aem.js';
6
import { getProductSku } from '../../scripts/commerce.js';
7
// Runs the initializer before the block reads the review settings.
8
import '../../scripts/initializers/ratings-reviews.js';
9

10
export default async function decorate(block) {
11
 const { sku: authoredSku } = readBlockConfig(block);
12
 block.replaceChildren();
13
 block.hidden = true;
14
 // Keeps the block hidden and skips requests when reviews are turned off.
15
 if (config.getConfig()?.isProductReviewsEnabled !== true || !block.isConnected) return;
16
 // An authored sku row wins; otherwise use the SKU of the current product page.
17
 const sku = authoredSku?.trim() || getProductSku();
18
 if (!sku) throw new Error('A product SKU is required to display product reviews.');
19

20
 // A unique scope keeps this list's events separate from other review lists on the page.
21
 const scope = `product-reviews-${crypto.randomUUID()}`;
22
 const fragment = document.createRange().createContextualFragment(`
23
   <div class="product-reviews__list"></div>
24
   <div class="product-reviews__pagination"></div>
25
 `);
26
 const reviews = fragment.querySelector('.product-reviews__list');
27
 const pagination = fragment.querySelector('.product-reviews__pagination');
28
 block.appendChild(fragment);
29
 block.hidden = false;
30

31
 await Promise.all([
32
   reviewsRenderer.render(Review, { scope })(reviews),
33
   reviewsRenderer.render(Pagination, { scope })(pagination),
34
 ]);
35

36
 if (!block.isConnected) return;
37
 // Not awaited, so slow reviews never delay the rest of the page.
38
 getProductReviews(sku, { pageSize: 20, currentPage: 1, scope }).catch((error) => {
39
   console.error('[Product Reviews] Failed to load reviews:', error);
40
 });
41
}

Initial request: getProductReviews loads the first page and publishes events for both containers.
Separate lists: Each block uses a unique scope to keep its events separate from other review lists on the page.
Later requests: Pagination requests pages when a shopper uses the page controls. Review retries a failed request when a shopper selects Try again.

Create the block styles at blocks/product-reviews/product-reviews.css.

1
/* Separates the reviews section from the content above it. */
2
.product-reviews {
3
 margin-block-start: var(--spacing-xxbig);
4
}
5

6
/* Keeps the block hidden while reviews are turned off or loading has not started. */
7
.product-reviews[hidden] {
8
 display: none;
9
}
10

11
.product-reviews .product-reviews__pagination {
12
 min-width: 0;
13
 margin-block: var(--spacing-medium);
14
}
15

16
/* Removes the pagination spacing when there is only one page. */
17
.product-reviews .product-reviews__pagination:has(.ratingsreviews-pagination[hidden]) {
18
 display: none;
19
}

Place the block on product pages. Choose one option:
- Author the block: Add a Product Reviews block to your product page template or another page. See Product Reviews block.
- Add it automatically: Append the block when the storefront builds a product page from its SKU. Follow Add reviews to product pages automatically.

Add reviews to product pages automatically

When the storefront builds a Product Details block from a SKU in page metadata or the product URL, it can also add reviews. Extend the automatic block creation (auto-blocking) code to append a Product Reviews section.

In scripts/commerce.js, add a function that appends a Product Reviews section to the page.

1
/**
2
* Appends a product-reviews section unless reviews are already authored.
3
* @param {Element} main The main element
4
*/
5
export function buildProductRatingsAndReviews(main) {
6
 // Respects an authored Product Reviews block, so the page never shows two lists.
7
 if (main.querySelector('.product-reviews')) return;
8
 const section = document.createElement('div');
9
 section.append(buildBlock('product-reviews', { elems: [] }));
10
 main.append(section);
11
}

scripts/commerce.js already imports buildBlock from ./aem.js.
The check for .product-reviews keeps an authored block from appearing alongside a second, automatically added list.

In scripts/scripts.js, import the function and call it right after buildPDPBlock(main).

1
import {
2
 buildPDPBlock,
3
 // Add this import next to buildPDPBlock.
4
 buildProductRatingsAndReviews,
5
 getProductSku,
6
 loadCommerceEager,
7
 loadCommerceLazy,
8
} from './commerce.js';
9

10
function buildAutoBlocks(main) {
11
 try {
12
   // ...existing auto-blocking code...
13
   const pdpBlock = document.querySelector('.product-details');
14
   if (metaSku && !pdpBlock) {
15
     buildPDPBlock(main);
16
     // Adds the reviews section at the end of the page.
17
     buildProductRatingsAndReviews(main);
18
   }
19
 } catch (error) {
20
   console.error('Auto Blocking failed', error);
21
 }
22
}

Keep your existing imports and auto-blocking code, including the SKU lookup that defines metaSku. Add only the buildProductRatingsAndReviews import and the call after buildPDPBlock(main).

This automatic placement runs only when the storefront creates the Product Details block. For pages with an authored Product Details block, add Product Reviews to the page or template instead.

Add a Write review button

Add a Write review button above the list to let shoppers submit reviews. The button opens the WriteReview form in a modal dialog over the page. New reviews appear in the list after approval in the Admin.

Replace blocks/product-reviews/product-reviews.js with this version to keep the review list and add the button and modal.

1
import { events } from '@dropins/tools/event-bus.js';
2
import { Button, provider as UI } from '@dropins/tools/components.js';
3
import { config, getProductReviews } from '@dropins/storefront-ratings-reviews/api.js';
4
import { render as reviewsRenderer } from '@dropins/storefront-ratings-reviews/render.js';
5
import { Review } from '@dropins/storefront-ratings-reviews/containers/Review.js';
6
import { WriteReview } from '@dropins/storefront-ratings-reviews/containers/WriteReview.js';
7
import { Pagination } from '@dropins/storefront-ratings-reviews/containers/Pagination.js';
8
import { readBlockConfig } from '../../scripts/aem.js';
9
import {
10
 CUSTOMER_LOGIN_PATH,
11
 checkIsAuthenticated,
12
 fetchPlaceholders,
13
 getProductSku,
14
 rootLink,
15
} from '../../scripts/commerce.js';
16
import createModal from '../modal/modal.js';
17
import '../../scripts/initializers/ratings-reviews.js';
18

19
// Shows the product name and image in the form when this page's product is the one being reviewed.
20
function getPageProduct(sku) {
21
 const product = events.lastPayload('pdp/data');
22
 if (!product || product.sku !== sku) return {};
23
 const image = product.images?.[0];
24
 return {
25
   productName: product.name,
26
   productImage: image?.url ? { src: image.url, alt: image.label || product.name } : undefined,
27
 };
28
}
29

30
async function openWriteReview(sku) {
31
 const content = document.createElement('div');
32
 content.className = 'product-reviews__modal-content';
33
 const modal = await createModal([content]);
34
 // Opens the modal first, because the form loads rating categories before it appears.
35
 modal.showModal();
36
 await reviewsRenderer.render(WriteReview, {
37
   sku,
38
   ...getPageProduct(sku),
39
   isAuthenticated: checkIsAuthenticated(),
40
   routeSignIn: () => rootLink(CUSTOMER_LOGIN_PATH),
41
 })(content);
42
}
43

44
export default async function decorate(block) {
45
 const { sku: authoredSku } = readBlockConfig(block);
46
 block.replaceChildren();
47
 block.hidden = true;
48
 // Also hides the Write review button when reviews are turned off.
49
 if (config.getConfig()?.isProductReviewsEnabled !== true || !block.isConnected) return;
50
 const sku = authoredSku?.trim() || getProductSku();
51
 if (!sku) throw new Error('A product SKU is required to display product reviews.');
52

53
 const scope = `product-reviews-${crypto.randomUUID()}`;
54
 const fragment = document.createRange().createContextualFragment(`
55
   <div class="product-reviews__write-review"></div>
56
   <div class="product-reviews__list"></div>
57
   <div class="product-reviews__pagination"></div>
58
 `);
59
 const labels = await fetchPlaceholders('placeholders/ratings-reviews.json');
60
 const reviews = fragment.querySelector('.product-reviews__list');
61
 const pagination = fragment.querySelector('.product-reviews__pagination');
62
 block.appendChild(fragment);
63
 block.hidden = false;
64

65
 await UI.render(Button, {
66
   children: labels.Global?.WriteReview ?? 'Write review',
67
   variant: 'secondary',
68
   onClick: () => openWriteReview(sku),
69
 })(block.querySelector('.product-reviews__write-review'));
70

71
 await Promise.all([
72
   reviewsRenderer.render(Review, { scope })(reviews),
73
   reviewsRenderer.render(Pagination, { scope })(pagination),
74
 ]);
75

76
 if (!block.isConnected) return;
77
 getProductReviews(sku, { pageSize: 20, currentPage: 1, scope }).catch((error) => {
78
   console.error('[Product Reviews] Failed to load reviews:', error);
79
 });
80
}

Button label: Global.WriteReview in placeholders/ratings-reviews.json supplies the text. If the key is missing, the button shows Write review.
Shopper access: checkIsAuthenticated() tells the form whether the shopper is signed in. When guests cannot write reviews, signed-out shoppers see a Sign in button that opens your sign-in page.

Add these rules to blocks/product-reviews/product-reviews.css:

1
.product-reviews__write-review {
2
 margin-block-end: var(--spacing-medium);
3
}
4

5
/* footer.css offsets every modal's close button by 40px with !important; restore the corner for this modal. */
6
.modal:has(.product-reviews__modal-content) .close-button {
7
 top: 0 !important;
8
 right: 0 !important;
9
}
10

11
/* Keeps the form clear of the close button. */
12
.product-reviews__modal-content {
13
 padding-block-start: var(--spacing-big);
14
}

To protect the form with reCAPTCHA, configure Enable for Product Review in the Admin reCAPTCHA settings. Your storefront already configures the reCAPTCHA library. See reCAPTCHA.

Check the result

Open a product page for a product with approved reviews.

The Reviews heading appears above the review list.
Each review shows the reviewer’s name, stars or Not rated, the date, the title, and the text.
Products with more than 20 approved reviews show page controls below the list.
If you added the Write review button, select it and submit a review. Confirm that the success message says the review is waiting for approval. Approve the review in the Admin to see it in the list.

If the reviews section does not appear, check these common causes:

What you see	Likely cause	What to do
No reviews section and no errors	Product reviews are turned off for the store	Turn on product reviews in the Admin, then reload the page.
Console error `[Ratings Reviews] Failed to fetch store config:`	The initializer could not load review settings, so reviews stay off	Check the Commerce GraphQL endpoint and store headers in your storefront configuration.
Console error `A product SKU is required to display product reviews.`	The block could not find a SKU	Add a `sku` row to the authored block, or place the block on a product page.
No reviews on this page.	The product has no approved reviews	Approve a review in the Admin.
Unable to load reviews. with a Try again button	The `reviews` request failed	Confirm that your Commerce GraphQL endpoint provides the `reviews` query.

Quick reference

Package: @dropins/storefront-ratings-reviews
Initializer: import '../../scripts/initializers/ratings-reviews.js';
Review container: import { Review } from '@dropins/storefront-ratings-reviews/containers/Review.js';
Pagination container: import { Pagination } from '@dropins/storefront-ratings-reviews/containers/Pagination.js';
WriteReview container: import { WriteReview } from '@dropins/storefront-ratings-reviews/containers/WriteReview.js';
Render provider: import { render } from '@dropins/storefront-ratings-reviews/render.js';
API function: import { getProductReviews } from '@dropins/storefront-ratings-reviews/api.js';

Next steps

Show average ratings on the product page header.
Show ratings on product listing cards and recommendation cards.
Customize review rows with slots or change labels in the dictionary.