Ecommerce storefront components in SG-Builder

In short. SGEN's ecommerce storefront components connect your product catalog directly to SG-Builder's drag-and-drop canvas. Drop a component into a Cell, pick a product from the dropdown, and SGEN renders live data — title, price, gallery, badges, add-to-cart — on the public page with no code. Nine components cover three jobs: product detail page (gallery + title + price + add-to-cart + description + badges), header cart (cart-button + mini-cart), and featured-products row (product-card). All use the ecommerce- prefix — not sgb-component-. That's the pitch — read on for the full component reference and step-by-step.

On this page: Component table · Three examples · Step-by-step · Trait reference · Troubleshooting

How to build product detail pages, cart widgets, and product grids without writing code

The nine ecommerce components at a glance:

All nine are leaf components — they sit inside a Cell and cannot hold child components. Drop them directly into an existing Cell; do not drop onto a Section or Row.

Naming rule — ecommerce- not sgb-component-: Every component in this family uses the ecommerce- prefix, not the sgb-component- prefix used by the rest of SG-Builder. The table below shows the correct name alongside the wrong variant that silently fails:

What is this for?

Ecommerce storefront components let you place live product data on any SGEN page using SG-Builder's drag-and-drop canvas — no code required. Instead of hand-coding product layouts, you drop a component into a Cell, point it at a product from the dropdown, and SGEN renders the title, price, gallery, badges, and add-to-cart button from your live catalog on the public page.

The nine components in this family cover three jobs: a product detail page (gallery, title, price, add-to-cart, description, badges), a header cart (cart button and mini-cart), and a featured-products row (product cards). Use them when you want catalog-driven content that stays in sync with your published products, rather than static text and images you would have to update by hand.

Good use cases

Example 1: Build a complete product detail page. Your store is launching a Digital Guide download. Create a new page, open it in SG-Builder, and compose six product-bound components — gallery, badges, title, price, add-to-cart, description — all pointed at the same product_id.

The key assembly rule: each component on the detail page must point at the same product_id. Components are not wired together automatically — set the ID individually in each component's trait panel.

Example 2: Add a cart button and mini-cart to your site header. Edit the header template in SG-Builder, drop ecommerce-cart-button into a nav Cell, set cart_mode to sg-dropdown, and place ecommerce-mini-cart in a sibling Cell on the same row. When a shopper adds an item anywhere on the site, the count badge updates and the mini-cart shows the full item list and subtotal.

Set show_count: true and inline_count: true so the count appears beside the icon without any badge-positioning CSS. Leave read_only: false on the mini-cart so shoppers can adjust quantities from the header dropdown.

Example 3: Curate a featured products row on the homepage. Drop ecommerce-product-card into three sibling Cells in a three-column Row. Give each card its own product_id and set card_style: "2" for a consistent visual treatment.

If the third card wraps in a three-column row, add body .sg-card-items { display: grid; grid-template-columns: repeat(3, 1fr); } to the Row's Additional CSS trait. The body prefix bumps specificity past the framework cascade rule.

What NOT to use this for

• Do not use ecommerce-product-card for a full category archive.

A curated row of hand-picked cards is the intended use. For a paginated, filterable grid of all products in a category, use ecommerce-products.

• Do not use ecommerce-related-products outside a product detail page.

The component infers its filter from the current page's product context. On a generic page with no product context, it renders empty or shows an unfiltered archive.

• Do not use ecommerce-product-gallery as a generic image gallery.

It is bound to a single product's media and has no layout configuration traits. For general image galleries, use sgb-component-gallery.

• Do not use ecommerce-mini-cart without ecommerce-cart-button nearby.

The mini-cart renders cart content but provides no trigger button. The standard pattern is both components in the same header row or template.

How this connects to other features

• Ecommerce → Products — the product_id you set on each component maps to a product created and published there. If a product is unpublished or deleted, the component renders empty on the public page with no error shown in the builder canvas.
• Ecommerce Orders — when a shopper clicks Add to Cart and completes checkout, an order appears at Ecommerce → Orders. The cart button's count badge reflects the live session cart, not a stored number.
• Media Library — product images in the gallery and card components come from images uploaded on the product's edit page, which draws from the Media Library. Upload product images at full resolution; the component handles display scaling for the canvas and public page.
• Appearance / Header template — the cart button and mini-cart belong in your header SGB template, not on individual pages. Edit them at Appearance → Header. Changes propagate to every page that uses that header template.

Before you start

• Confirm the Ecommerce module is active for your site.

If it is not enabled, ecommerce components register in the builder but render empty placeholders on the public page with no warning shown.

• Create and publish at least one product at Ecommerce → Products before dragging ecommerce components onto a page.

The product_id dropdown in each component's trait panel is populated from your live, published product list. An empty dropdown means no published products exist yet.

• For a product detail page, create the page first, then open it in SG-Builder.

The page does not need to be the official product template — ecommerce components work on any page type.

• Confirm the Section → Container → Row → Cell hierarchy is already in place before dropping components.

All nine ecommerce components are leaf-level and must land inside a Cell.

• For the header cart setup specifically: open the header template in SG-Builder, not a regular page.

Changes to a page's layout do not affect the header template and vice versa.

Where to go

1. For a product detail page: Pages → All Pages → find or create the page → Open in SG-Builder.
2. For a header cart button: Appearance → Header → Open in SG-Builder.
3. Inside the builder, open the Components tab on the left panel and expand the Ecommerce group.
4. Drag the component you need into the target Cell.

Steps

1. Drop the component into a Cell

All ecommerce components are leaf-level and must sit inside a Cell at level 5 of the hierarchy (Section → Container → Row → Cell → component). Drag directly onto a Cell in the canvas. If you drop onto a Section or Row, SG-Builder may reject the drop or wrap the component incorrectly.

2. Set the product ID

Click the component on the canvas to open its Traits panel on the right. For product-bound components, the product_id trait shows a dropdown populated with your published products. Select the target product and the canvas refreshes to show the component rendered with that product's data.

Components that require product_id: ecommerce-product-title, ecommerce-product-price, ecommerce-product-description, ecommerce-product-gallery, ecommerce-product-add-to-cart, ecommerce-product-badges, ecommerce-product-card.

Components that do not use product_id: ecommerce-cart-button, ecommerce-mini-cart.

On a product detail page, every component must point at the same product_id. They are not wired together automatically — you set the ID individually on each component.

3. Configure component traits

The two configuration-heavy components — ecommerce-cart-button and ecommerce-mini-cart — have multiple traits. All other product-bound components expose only product_id in their trait panel; their display format (currency symbol, button label, description markup) is governed by global ecommerce settings.

ecommerce-cart-button — all configurable traits:

ecommerce-mini-cart — all configurable traits:

ecommerce-product-badges — show_sale, show_new, and show_category are permission toggles, not generators. Each badge appears only when the product record carries the corresponding data: a sale price stored in the product edit form, a new-arrival flag enabled, or a category assigned. Setting show_sale: true on a product with no sale price entered produces no badge — this is expected.

ecommerce-product-card — card_style accepts "" (Default), "1", "2", or "3". Do not use the style_1 format — that is sgb-component-card's naming convention, a different component family.

4. Style with Style Manager and Additional CSS

Use the Style Manager (right panel) for padding, margin, width, and font-size per breakpoint. For states the Style Manager does not cover — sale price color, badge overlay position, card hover lift — use the Additional CSS trait on the component or its parent Cell. Selectors in Additional CSS are auto-scoped to the component.

Sale price color and strikethrough:

selector .sale-price { color: #d51522; font-weight: 700; }selector .regular-price { text-decoration: line-through; color: #9ca3af; }

Badge overlay positioning (when ecommerce-product-badges sits inside a relatively-positioned Cell):

selector { position: relative; }selector .badges-wrap { position: absolute; top: 10px; left: 10px; z-index: 2; }

Product card hover lift (applied to the Cell wrapping the card):

selector { transition: box-shadow 0.2s ease, transform 0.2s ease; }selector:hover { box-shadow: 0 8px 24px rgba(15,23,42,.12); transform: translateY(-2px); }

5. Save and verify on the public page

Save in the builder, then open your public page in a new browser tab. Ecommerce components are server-rendered — the canvas shows a placeholder approximation only. The actual live output comes from your product data, rendered fresh at each page load.

On the public page, verify:

• The correct product title, price, and images appear for the selected product.
• The Add to Cart button is active. An out-of-stock product shows a disabled button — this is expected behavior.
• The cart button count starts at 0 for a new browser session. Add an item and reload to confirm it increments.
• Badge labels (Sale, New, category name) match the product's actual stored data.

The complete flow

The table below shows a full product detail page composition for a Canvas Tote Bag (product_id: 7). Every component in both columns shares the same product ID — set individually per component.

What success looks like

On the public product page:

• Gallery shows the main image with thumbnail navigation below it.

Clicking a thumbnail swaps the main image in place without a page reload.

• Title renders as <h1> when heading_tag: h1 is set — correct for search indexing on a single-product page.
• Price shows the sale price prominently with the regular price struck through, when a sale price is stored on the product.
• The Add to Cart button is active. Clicking it adds the item to the session cart and the cart button count increments immediately.
• Related products show a row of items from the same category at the bottom of the page.

On the admin side: open Ecommerce → Orders after a test purchase. A new order with the product line item confirms the full cart → checkout → order flow is working end-to-end.

Canvas Tote Bag product page — what a shopper sees on the live public page:

What to do if it does not work

• Component renders empty on the public page — the product_id is unset, the product is unpublished,

or the Ecommerce module is not active on your site. Check the product's publish status at Ecommerce → Products. Confirm the module is enabled in your site settings.

• Cart button count does not update — the count reflects the live session cookie, not a stored value.

A freshly opened tab always starts at 0. Add an item to the cart in the same tab and reload; the count should appear on the button.

• Mini-cart dropdown opens but shows nothing — ecommerce-mini-cart must be on the same page template

as ecommerce-cart-button when using cart_mode: sg-dropdown. If the mini-cart component lives on a different template, the dropdown panel has nothing to render.

• Third product card wraps in a three-column row — add the grid override to the Row's Additional CSS:

body .sg-card-items { display: grid; grid-template-columns: repeat(3, 1fr); }. Apply this to the Row, not to the individual card component. The body prefix is required to beat the framework cascade specificity.

• Badges do not show even with show_sale: true — show_sale is a permission toggle, not a badge generator.

The badge renders only when the product has a sale price stored in its product edit form. Go to Ecommerce → Products → edit the product → enter a sale price → save → refresh the public page.

• Canvas does not refresh after setting product_id — this is a canvas-only display limitation, not a config error.

The component is correctly bound. Save in the builder and open the public URL to confirm the live output.

• Add-to-cart button style cannot be changed via traits — unlike ecommerce-cart-button,

the ecommerce-product-add-to-cart component has no btn_style trait. Button appearance follows your site's primary button style from Appearance → Site Settings. To change the color on a specific product page only, use Additional CSS: selector button { background: #your-color; border-color: #your-color; }.

Next step

After building a product detail page, add the page to your navigation at Appearance → Menu so shoppers can find it from anywhere on your site. Then configure your cart and checkout flow at Ecommerce → Configuration to set currency, shipping zones, tax rules, and payment methods.

For layout structure (Sections, Rows, Cells), see Structure and layout in SG-Builder. For the text, heading, and button components that fill non-product Cells, see Text, headings, and buttons in SG-Builder. For currency, tax, and payment configuration, go to Ecommerce → Configuration in your site admin.