Custom Blocks vs Widgets - when do I use which?
Valotrix Cart Rewards's storefront has two surfaces. They're both real, they both work, and they do different jobs. This is the page that resolves the confusion.
Two ways Valotrix Cart Rewards shows up on your storefront
- Widgets are UI the app paints on top of any page - toasts that slide in from the corner, progress bars in the cart drawer, modal popups, banner strips. The app controls where and how they render. They show up the moment you toggle them on. You don't touch the theme editor.
- Custom Blocks are placements that render inside your theme - on the product page, the home page, in the header, on the collection grid. You place them in the theme editor, you control where they sit, you control which sections they live in. They're full theme citizens.
The shorthand: Widget = overlay; Block = inline.
You can use both. They don't conflict - different surfaces, different jobs.
Use a Widget when...
There are five widget formats. Each has a specific job:
- Toast - a small slide-in card. Use when you want low-friction confirmation that something good just happened (gift was added, threshold was crossed). Doesn't interrupt the shopper.
- Promo popup - a modal that opens on a trigger. Use when you want the customer to stop and read - high-value offer they shouldn't miss.
- Progress bar - a persistent bar showing distance to the threshold. Use when the campaign is spend-threshold-based and the shopper needs to see "$12.50 more to go" in real time.
- Gift-choice modal - the picker for customer choice campaigns. Use when your campaign offers 2+ gifts and you want the buyer to pick rather than receive a default.
- Reminder banner - a thin strip across the top of the page. Use when you want every visitor - not just cart-page visitors - to know the promotion exists.
See the Widgets overview for previews of each format.
Use a Custom Block when...
There are seven block types. Each has a specific job:
- Threshold bar - drop a progress bar inline on the home page, PDP, or announcement bar. Use when the cart-drawer widget isn't enough - you want the offer visible before the customer opens the cart.
- PDP gift preview - show "Buy this and get a free X" inline on the product page. Use when one trigger product unlocks one gift and you want the shopper to see the offer while choosing.
- PDP buy-get pairing - a "Buy this · receive this" card showing the trigger product and the gift as a pair. Use for explicit BOGO promotions where the pairing is the message.
- Urgency banner - honest scarcity + countdown, with real inventory queries and server-anchored time. Use when the campaign has a real end time or low gift stock and you want to surface that without faking it.
- Inline tier stack - multi-tier campaign visualizer on the PDP. Use when you have a tiered campaign with 2+ tiers and want the buyer to see the next tier (combats the "I see one tier and don't know there's better" gap).
- Collection eligibility overlay - stamps a "Free gift" badge on every product card in a collection grid whose product matches an active BOGO campaign. Use when you want the offer surfaced before the buyer reaches the PDP.
- Gift unlock celebration - animated banner that fires when the cart crosses a free-gift threshold. Use when you want visceral confirmation of progress, beyond the toast.
See Custom Blocks for templates and placement instructions.
Plan caps
Widgets and Custom Blocks have different limits:
| Surface | Free | Growth $24/mo | Pro $49/mo | Scale $99/mo |
|---|---|---|---|---|
| Widgets | All 5 unlimited | All 5 unlimited | All 5 unlimited | All 5 unlimited |
| Custom Blocks | 1 active | Up to 3 active | Up to 10 active | Unlimited |
Free-plan note: the Free plan allows 1 active Custom Block. Upgrade to Growth for up to 3, Pro for up to 10, or Scale for unlimited. Widgets work on every plan, including Free.
Can I use both?
Yes - they're independent surfaces.
A typical setup for a tiered free-gift campaign:
- Progress bar widget in the cart drawer (the customer-engaged-with-cart surface).
- Threshold bar block in the header (the every-page surface).
- Gift unlock celebration block on cart pages (the cross-threshold confirmation surface).
- Toast widget firing when a tier unlocks (the just-now-something-happened surface).
That's three blocks plus two widgets. On Growth you'd cap out at 3 blocks; on Pro or Scale, no cap concern.
How to add each one
- Add a Widget: in the admin, open the campaign and go to its Messaging tab (the last tab in the rule editor). Toggle the widget formats you want. No theme editor.
- Add a Custom Block: in the admin, open Custom Blocks in the sidebar, create a block, and copy the block ID. Then open the Shopify theme editor, add the Valotrix Cart Rewards Embed host block (or the section-specific host block your theme allows), paste the block ID, and save.
Full walkthroughs: Widgets overview and Custom Blocks.
Next: Widgets overview →