Widget customizer reference (all settings & limits)
A field-by-field reference for the per-campaign widget customizer — every setting, its default, and its exact limits for Product Recommendations and Gift with Purchase.
This is the complete, setting-by-setting reference for the per-campaign widget customizer that styles your Product Recommendations (pre-purchase) and Gift with Purchase widgets. If you just want the high-level tour, start with Customizing widget appearance — this page goes deeper, listing every field, its default value, and its numeric limits.
How the customizer works
Each campaign has its own widget, and each widget has its own customizer. The customizer opens as a full-screen modal (or a dedicated page) with two panels: the editor on the left and a live preview on the right that mirrors how the widget looks on your storefront, including the responsive screen sizes shoppers will see.
The settings you choose are tied to a specific layout. Every campaign type has a layout-specific schema, so the set of sections and fields you see changes depending on which layout you pick. When you save, the settings persist to the app's database and are synced to a per-widget app metafield that your theme app extension reads at render time.
Changes go live only after you click Save. The preview updates instantly as you edit, but shoppers keep seeing the previously saved version until you save. Closing the customizer with unsaved changes prompts you to confirm.
You can also set global styles once in Settings that apply to every widget. Per-campaign settings in this customizer override the global styles, so use globals for your store-wide look and override here only where a specific campaign needs to differ. See App settings for the global style controls.
Layout (the Type dropdown)
The first control in the customizer is the Type dropdown, which sets the widget's layout. The layouts available depend on the campaign type.
| Campaign type | Available layouts |
|---|---|
| Product Recommendations | Slider, List, List Slider (Only for small containers) |
| Gift with Purchase | Slider, List (Only for small containers) |
Changing the layout swaps the entire section set. Each layout has its own schema, so switching layouts shows a different list of sections and fields, and the layout-specific fields reset to that layout's schema defaults. Set your layout first, then customize — if you change it later, re-check the fields below it.
The "List Slider" (Product Recommendations) and "List" (Gift with Purchase) layouts are labelled Only for small containers because they are designed for narrow placements, such as a sidebar or a slim theme column.
Appearance
The Appearance section controls colors, the heading, card layout, and corner rounding. The exact fields and defaults differ between Product Recommendations and Gift with Purchase.
| Setting | Default | Range/Limit | What it controls |
|---|---|---|---|
| Primary text color | #121212 | Any hex/RGB color | Color of the widget's text. |
| Background Color | #f6f6f6 | Any hex/RGB color | Widget background fill. |
| Add to cart button color | #121212 | Any hex/RGB color | Fill color of the add-to-cart button. |
| Add to cart button text color | #fff | Any hex/RGB color | Label color on the add-to-cart button. |
| Heading text | You may also like | Free text | The widget's title shown above the products. |
| Product CTA Layout | Vertical | Vertical or Horizontal | Whether the product card stacks its details and button vertically or arranges them horizontally. (Slider layout only.) |
| Border radius | 0 | 0–20 px | How rounded the widget's corners are. |
The List Slider layout replaces the four-color set above with a Primary color (default #fff) and Secondary color (default #f6f6f6), and adds a collapsible container (see below). The plain List layout keeps the four-color set but drops the Product CTA Layout option.
| Setting | Default | Range/Limit | What it controls |
|---|---|---|---|
| Primary color | #000 | Any hex/RGB color | The widget's primary accent color. |
| Secondary color | #f6f6f6 | Any hex/RGB color | Widget background / secondary fill. |
| Primary text color | #000 | Any hex/RGB color | Color of the widget's text. |
| Enable collapsible container | Off | On/Off | Wraps the widget in a collapsible panel (see Collapsible container). |
| Initial Collapse Open | On | On/Off | Whether that collapsible panel starts expanded. |
| Border radius | 0 | 0–20 px | How rounded the widget's corners are. |
The List Slider layout for Product Recommendations puts the Heading text field at the top of Appearance and also exposes the Enable collapsible container / Initial Collapse Open toggles, matching the Gift with Purchase small-container layout.
Slider settings
The Slider settings section sets how many products show per screen size, the gap between them, and the slider controls. Product Recommendations sliders and Gift with Purchase / small-container layouts have slightly different fields.
Products per view
The "Products Per View" sliders accept fractional values (a half-step shows part of the next card as a "peek" so shoppers know they can scroll).
| Setting | Default | Range/Limit | What it controls |
|---|---|---|---|
| Large Container (from 1024px) | 6 | 1–10 slides, step 0.5 | Products shown when the widget's container is at least 1024px wide. |
| Medium Container (from 469px to 1024px) | 4 | 1–7 slides, step 0.5 | Products shown in a medium container. |
| Small Container (up to 469px) | 3 | 1–3 slides, step 0.5 | Products shown in a narrow container. |
For the Gift with Purchase List layout (and the Product Recommendations List Slider layout), Products Per View is a single Small Container slider with a range of 1–6 slides and a default of 1 — there are no separate large/medium sliders, because these layouts only target small containers.
Spacing
| Setting | Default | Range/Limit | What it controls |
|---|---|---|---|
| Space Between Products | 12 | 0–40 px, step 1 | The gap between adjacent product cards. |
| Container Padding | 10px 16px | CSS padding string | Space around the container, e.g. 16px 18px 12px 16px. (Product Recommendations Slider only.) |
Autoplay (small-container layouts)
The Gift with Purchase List layout and Product Recommendations List Slider layout add autoplay controls.
| Setting | Default | Range/Limit | What it controls |
|---|---|---|---|
| Enable Autoplay | Off | On/Off | Whether the slider advances on its own. |
| Autoplay speed | 1 | 0–10 sec, step 0.1 | Delay between automatic advances. |
Behaviour (small-container layouts)
| Setting | Default | Range/Limit | What it controls |
|---|---|---|---|
| Scroll Direction | Horizontal scroll | Horizontal or Vertical | Direction the slides scroll. |
| Enable Free scroll mode | Off | On/Off | Lets shoppers scroll freely instead of snapping to each slide. |
Slider controls
| Setting | Default | Range/Limit | What it controls |
|---|---|---|---|
| Show Arrows | On | On/Off | Shows the previous/next navigation arrows. |
| Show Bullets | Off | On/Off | Shows the dot pagination indicators. |
| Loop slides | Off | On/Off | Loops back to the start after the last slide. (Small-container layouts only.) |
Product Card
The Product Card section controls the add-to-cart button labels, the optional Quick View button, and what happens when a shopper clicks a product.
Button text states
The add-to-cart button shows different labels depending on its state. You can edit all three.
| Setting | Default | Range/Limit | What it controls |
|---|---|---|---|
| Add to cart button text | Add | Max 50 characters | Default button label. |
| Add to cart button text on item added | Added | Max 50 characters | Label shown after the product is added. |
| Add to cart button text on item adding | Adding... | Max 50 characters | Label shown while the add request is in progress. |
The 50-character limit is enforced only on slider-layout button text. The list layouts do not enforce a maximum, but a long label can break the card's layout in a narrow container — keep these labels short regardless of layout.
Quick View button
| Setting | Default | Range/Limit | What it controls |
|---|---|---|---|
| Show Quick View Button | Off | On/Off | Adds a Quick View button to each product card so shoppers can preview details without leaving the page. |
To customize the style of the Quick View modal itself, go to Settings → Global Style. The per-widget toggle only turns the button on or off; the modal's appearance is set globally. See App settings.
Product click action
| Setting | Default | Options | What it controls |
|---|---|---|---|
| Product Click Action | No Action | Quick View, Redirect to Product Page, No Action | What happens when a shopper clicks a product card (not the button). |
With No Action (the default), clicking the card does nothing. Quick View opens the preview modal; Redirect to Product Page sends the shopper to the full product page.
Settings
The Settings section controls which products are eligible to appear in the widget.
| Setting | Default | Range/Limit | What it controls |
|---|---|---|---|
| Hide out of stock products | On | On/Off | Removes out-of-stock products from the widget. |
| Hide unlisted products | Off | On/Off | Gift with Purchase only. When on, products that are "unlisted" in Shopify (published to the channel but hidden from search) are kept out of the offer. |
| Hide added offers | On | On/Off | When on, offers that exceed the diversity limit are removed so the same offer isn't shown repeatedly. |
Product Recommendations layouts also expose App refresh on cart change (default on — when enabled, an added product disappears from the list) and, on Slider/List layouts, Group variants (default on — variants of one product are shown as a single product with options).
Collapsible container (Gift with Purchase)
Gift with Purchase widgets (and the Product Recommendations List Slider layout) can wrap the widget in a collapsible panel that shoppers can expand and collapse. These toggles live in the Appearance section.
| Setting | Default | Range/Limit | What it controls |
|---|---|---|---|
| Enable collapsible container | Off | On/Off | Turns the collapsible wrapper on. |
| Initial Collapse Open | On | On/Off | Whether the panel starts expanded when the page loads. |
Initial Collapse Open only has an effect when Enable collapsible container is on. If the container isn't collapsible, this toggle does nothing.
Custom Styles
Every layout includes a Custom Styles section with a single Custom CSS code field (empty by default). Use it to target this widget specifically with your own CSS when the standard controls don't reach far enough.
This per-widget CSS applies only to the campaign you're editing. To apply CSS across every widget at once, use the Global Styles CSS editor in Settings instead — see App settings.
Edge cases & complex scenarios
Example recipes
4-up desktop / 2-up mobile slider, arrows only
In a Product Recommendations Slider widget, set Large Container to 4, Medium Container to 3, and Small Container to 2. Leave Show Arrows on and turn Show Bullets off for clean navigation. Adjust Space Between Products (default 12 px) to taste, then Save.
Compact Gift with Purchase list in a narrow theme column
Choose the Gift with Purchase List (Only for small containers) layout. Set the single Small Container slider to 1 (its default) so one gift shows at a time, turn on Enable collapsible container with Initial Collapse Open off to save vertical space, and optionally enable Autoplay with a slow Autoplay speed of 2–3 sec. Save.
"Redirect to product page" recommendations with Quick View off
In a Product Recommendations widget, leave Show Quick View Button off and set Product Click Action to Redirect to Product Page so a card click opens the full product page. Keep the add-to-cart button labels short (within 50 characters) and Save.