Layout and CSS selectors

Layout

The default component has eight built-in designs and two layouts. The channel’s design and layout are chosen in the panel on the Store appearance screen; new channels use the Warm design and the Cards layout (see Store appearance). The data-review-theme and data-review-style attributes on the container or on the script tag override this choice; an unrecognised value is ignored and the design or layout chosen for the channel in the panel is used. Whether reviews are arranged one below the other or in a grid is chosen with the data-review-layout attribute:

Attribute	Result
data-review-theme="warm"	Warm: cream summary panel, yellow stars, coloured initials
data-review-theme="trust"	Trust: green score box and accents; puts the verified buyer first
data-review-theme="editorial"	Editorial: black and white, large score, quoted titles
data-review-theme="minimal"	Minimal: white and light grey with a thinly framed summary
data-review-theme="soft"	Blush: blush pink tones, pink stars and round corners
data-review-theme="bold"	Sport: black score box, orange stars, upper-case titles and sharp corners
data-review-theme="natural"	Natural: earth and olive tones
data-review-theme="night"	Night: dark background with light text; the review section brings its own dark background
data-review-style="cards"	Cards: the summary and rating bars on top, each review in its own card
data-review-style="sidebar"	Side panel: in a wide area the summary and rating bars on the left and the reviews on the right; in a narrow area stacked as a list with dividers
data-review-layout="list"	Reviews are shown one below the other (default)
data-review-layout="grid"	Reviews are shown in a grid; the number of columns depends on the width

The colours and corner values of the designs can be changed with CSS variables: CSS variables › Built-in designs.

The layout adapts to the component’s own width rather than the page width (a CSS container query; the container name is sayproof-reviews). This keeps the component correct in a narrow column of your page too:

• In the side panel layout, the component must be at least 880 px wide for the summary to sit on the left; in a narrower area the summary is shown above the list.
• From 640 px, the summary splits into two columns: the average rating on the left and the rating bars on the right. In the left column of the side panel layout, the summary stays in a single column.
• Below 480 px, spacing and image previews become smaller.

By default, the review writing area is shown inside the container, below the summary; in the side panel layout it sits in the left column together with the summary when the area is wide. If you want to show it elsewhere on the page (for example below the product title), add an empty element at that position and specify its selector in the data-review-gate attribute:

<div id="write-review"></div>

<div data-review-mount
     data-review-product="PRODUCT-CODE"
     data-review-gate="#write-review"></div>

If no element matches the selector, the area is shown in its default position.

CSS selectors

Every element of the component carries a data-review-* attribute. These attributes are a contract: they do not change and are not removed within the same version. The component does not use class names; write your CSS rules only against these attributes.

The component’s style tag is added at the start of the <head> element, and its rules are defined inside a :where(...) scope that adds no specificity; the rules that depend on the design or the layout (card borders, the side panel arrangement, grid columns, the differences between the built-in designs) are inside this scope too. As a result, a rule of yours with the same specificity as the selector the component uses for an element overrides the component’s rule without an extra prefix or !important; for example, your [data-review-item] rule changes the look of the card in every design and layout. If you want your rule to apply only in one design or layout, put the root element’s attribute at the start of the selector: [data-review-root][data-review-theme="editorial"], [data-review-root][data-review-style="sidebar"].

The one exception is the background, padding and corner radius that the Night design gives the root element: this rule has the same specificity as the root element’s [data-review-root] selector. A [data-review-root] rule of yours on the root element still applies, because it comes after the component’s style tag.

If you use server-side rendering, the <link data-review-stylesheet> at the start of the root element in the HTML from the server comes after your page’s CSS, so your rules with equal specificity do not apply until the script takes over the component. If you want a rule to apply on this first display too, put [data-review-root] at the start of the selector. If the rule targets the root element itself (for example to change the background of the Night design), write the selector as [data-review-root][data-review-theme="night"].

Examples

Turning the cards into a list separated by lines:

[data-review-item] {
  border: none;
  border-bottom: 1px solid #e5e7eb;
  border-radius: 0;
  padding: 24px 0;
  background: transparent;
}

Enlarging the average rating and moving the rating breakdown to the top of the summary:

[data-review-average] {
  font-size: 3rem;
  font-weight: 700;
}

[data-review-distribution] {
  order: -1;
}

Making the rating bars thinner and changing the colour of the filled part:

[data-review-bar] {
  height: 4px;
}

[data-review-bar]::before {
  background: #0b4f9c;
}

Fixing the number of columns in the grid arrangement:

[data-review-root][data-review-layout="grid"] [data-review-list] {
  grid-template-columns: repeat(3, minmax(0, 1fr));
}

@media (max-width: 768px) {
  [data-review-root][data-review-layout="grid"] [data-review-list] {
    grid-template-columns: minmax(0, 1fr);
  }
}

Enlarging photo and video previews:

[data-review-media-open] {
  width: 128px;
  height: 128px;
}

Enlarging review titles in the Editorial design only:

[data-review-root][data-review-theme="editorial"] [data-review-title] {
  font-size: 1.5em;
}

Removing the review section’s own dark background in the Night design so that your page’s background shows:

[data-review-root][data-review-theme="night"] {
  padding: 0;
  background: transparent;
}

Hiding the container when the reviews could not be loaded:

[data-review-mount][data-review-failed] {
  display: none;
}

Styling states

Attribute	Element	Meaning
data-review-busy	Root element	A request is in progress (filter or sort change, search, “More reviews”)
data-review-ready	Container	The component is ready
data-review-failed	Container	The reviews could not be loaded
data-review-gate-state	Review writing area; the container in headless use	pending, closed, open, refused or submitted
data-review-viewer-state	Review writing area	can_write or written for a signed-in customer
data-review-open	Long review text (data-review-body)	The visitor has opened the text with “Read more”
data-review-fill	Stars (data-review-stars), rating bar, scale marker	The fill or position: between 0 and 100, in multiples of 5. On the stars, the filled part is shown in the star colour and the rest in the --review-track colour.
data-review-avatar-tone	Initials circle (data-review-avatar)	Between 0 and 5; the colour chosen from the author’s name
data-review-line-state	Item row on the order page (data-review-order-line)	can_write, pending, published, rejected, removed, waiting or closed
aria-pressed="true"	Star row (data-review-star-filter), filter buttons (data-review-filter), the “Yes” and “No” buttons	The filter is applied, or the visitor has voted that way

For all attributes and their meanings, see DOM attributes.

Elements that cannot be hidden

You can style the sort menu, cards, spacing, rating breakdown and photos as you wish. Some elements, however, must remain visible under the regulations or the method statement. Hiding these elements with CSS (display: none, the same colour as the background, moving them off screen and so on) is contrary to the terms of use:

• the verification badge (data-review-verified),
• the method statement link (data-review-method-statement),
• the sort menu and its options (data-review-sort, data-review-sort-option),
• the source label of reviews carried over from another source (data-review-origin),
• the process experience label of reviews written after a cancellation or return (data-review-experience),
• the seller response and the resolution (data-review-seller-response, data-review-resolution).

For the list of elements and their legal basis, see Required elements.

Versions

The root element carries the data-review-version attribute; the current version is 3. Adding a new attribute is a minor version change and does not affect your existing CSS rules. Removing an attribute or changing its meaning is a major version change; the previous version remains supported for at least one year, and the change is announced in the release notes.