# Layout and CSS selectors

> Choosing a built-in design, a layout and a list or grid arrangement, positioning the review writing area and styling every element of the component with your own CSS rules.

Source: /en/customize/css-hooks/

## 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](/en/features/setup-screens.md#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](/en/customize/theme.md#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:

```html
<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:

```css
[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:

```css
[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:

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

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

Fixing the number of columns in the grid arrangement:

```css
[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:

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

Enlarging review titles in the Editorial design only:

```css
[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:

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

Hiding the container when the reviews could not be loaded:

```css
[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](/en/reference/dom-attributes.md).

## 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](/en/customize/required-elements.md).

## 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](/en/reference/versions.md).