Customizing the widget

The review widget inherits your theme’s fonts and exposes a comprehensive set of colour and visibility controls via the Widget Editor in the BetterReviews admin.

What inherits from your theme automatically

• Body font family — same font as your product description (unless you override it)

What’s deliberately not inherited

The widget uses a fixed internal spacing scale — hardcoded to a 16px rem base with its own scale variable, not your theme’s root font size. This is intentional: some themes set html { font-size: 10px } which would shrink everything on the widget to an unusable size. By holding our own scale steady, the widget stays legible regardless of what your theme does.

The widget editor

Open Display → Widget editor in the BetterReviews admin.

Screenshot of the Widget Editor — manual capture, drop in here.

You can customise:

Colour mode

• Auto (default), Light, Dark — forces the widget into the chosen mode regardless of theme context

Colours (granular palette)

• Accent — Write a Review button background, primary accent
• Star fill — star colour (separate from accent; can be independently set)
• Widget background, Text, Border, Card background
• Verified badge, Merchant-reply background, Muted background, Muted text

When you install BetterReviews, we automatically pull these colours from your live Shopify theme — so the widget editor opens with theme-matched defaults rather than empty CSS-default fields. Click Match my store to re-pull the palette later if you change themes or rework your store’s colours; we confirm before applying so a re-pull never silently overwrites your saved colours. If we couldn’t read your theme at install time (some custom themes block the settings file), the editor surfaces a small banner inviting you to click Match my store to retry, and the CSS defaults stay in place until then.

Typography

• Corner style — Sharp / Slightly rounded / Rounded / Extra rounded
• Font scale — slider from 0.8× to 1.3×

Sections and visibility

• Photo gallery — show / hide the photo gallery (6 thumbnails, the last one showing “+N” when there are more)
• Photo thumbnails on review cards — independent setting from the gallery; hides photos inline on individual review cards
• Customer Pulse — the “mentioned most” tag pills section
• Rating distribution bars
• Value driver pills
• Verified badge on review cards
• Imported review badges — an optional label shown next to the verified badge on reviews brought in from another platform. You set one label per source, so a store that imported from both Judge.me and Feefo labels each correctly instead of stamping one name on everything. The editor shows a field only for the sources you actually have reviews from (Judge.me, Okendo, Yotpo, Loox, Feefo or a CSV upload). Every field is blank by default — no badge appears unless you set one, and a source you leave blank shows no badge while your other sources still do. The label describes where the review came from and makes no claim about purchase verification — and only use a third-party name or trademark if you have the right to display it. Changing a label is usually visible within ~10 minutes, and up to ~90 minutes on catalogues with tens of thousands of products, while we rebuild the cached review data. Note this badge is not covered by the Verified badge toggle above — blanking every field is its only off switch.
• Helpful / Not helpful vote buttons
• Merchant replies
• Sticky toolbar — filter bar sticks to top while scrolling

Default sort and enabled sorts

Pick the Default sort (shown first) — that dropdown only offers sorts you have ticked below, so enable a sort before you can make it the default. Below it, under Enabled sort options, tick which sorts appear in the shopper-facing dropdown: Most Relevant, Most Helpful, Newest, Highest Rated, Lowest Rated, Most Detailed, Featured, Critical First, Best Media. Out of the box six are enabled: Most Relevant (the default), Most Helpful, Newest, Highest Rated, Most Detailed, Best Media.

Empty state

• Empty-state title — what shows when no reviews exist
• Empty-state CTA text — the “Be the first!” button copy

Colour fields take hex values. Every colour setting on this block accepts a hex code (3-, 4-, 6- or 8-digit, e.g. #rgb, #rrggbb, #rrggbbaa) or one of inherit, transparent and currentColor. Named colours, rgb() and hsl() are not accepted — anything else is rejected and the save fails with an error naming the field, rather than falling back to a default. Use the Custom CSS box below for anything the colour pickers will not take.

Custom CSS

Drop in your own CSS for power-user overrides, up to 20 KB. Anything longer is silently truncated at 20 KB when you save. For safety every < is removed before it reaches your storefront, so the box can hold CSS rules only — never <style> or <script> markup. The > child combinator is preserved, so .a > .b keeps working.

Sticky offset

If your theme has a fixed header, set a pixel offset so the sticky toolbar sits below it.

Previewing changes

The editor includes a live preview that updates as you change values. Same idea as the conversation editor preview. Your changes don’t apply to the live widget until you click Save.

Screenshot of the Widget Editor preview pane — manual capture, drop in here.

Photo display: marketing-ready only

Settings → Branding → Widget photos has a toggle: Only feature marketing-ready photos.

When ON, the storefront widget hides customer photos that BetterReviews has flagged as not marketing-grade — typically too dark, blurry, or where the product isn’t visible. The remaining photos are shown normally. Imported reviews from Loox, Judge.me, and Okendo always show their photos regardless — imported photos aren’t run through our photo analysis. They appear once copied to our storage, and a photo the source platform no longer serves is hidden automatically.

When OFF (the default), all non-hidden customer photos appear on the widget exactly as before.

Changes propagate to your storefront within ~10 minutes — we re-bake the cached metafields on every product after you save.

Screenshot of the toggle in Settings → Branding — manual capture, drop in here.

Settings apply store-wide

Widget settings apply to every product page. There’s no per-product customization today. If you need different widget styles on different products, let us know what the use case is.

Translating widget copy

The theme extension ships with a default English locale at locales/en.default.json. Shopify’s storefront localization picks up locales/<lang>.json files alongside it — drop in a translated copy and the widget renders the new strings on storefronts in that locale.

This covers only the widget on your product pages. The review pages customers open from their email (chat, review form, review hub) and the review request emails are translated by BetterReviews itself — see Languages. Locale files you add here don’t change those pages.

Group-aware copy keys (only render when the product is in a review group):

Key	Default copy
based_on_group_reviews	Based on {{ count }} reviews across {{ product_count }} product variants
based_on_group_reviews_named	Based on {{ count }} reviews across {{ product_count }} product variants in the {{ name }} collection
reviewed_product	Reviewed: {{ product }}

based_on_group_reviews_named fires when the merchant has set a display_name on the group; based_on_group_reviews is the fallback. reviewed_product is rendered as a small “Reviewed: other variant name” badge on each review row whose source product differs from the PDP being viewed.

What isn’t customizable

A few things can’t be changed in the editor (the Custom CSS box can still hide or restyle any part of the widget):

• The overall structure — metrics row, pulse, gallery, review list, Write a Review button. Order and general layout aren’t swappable.
• “Write a Review” CTA wording — tuned for conversion and not exposed.
• Star-rating precision — half-stars render automatically based on the average rating.
• Spacing scale — intentionally fixed to prevent theme overrides from breaking the widget.

Related

• Review widget overview
• What your customers see in the widget
• Star rating badge