# Offer Variant Popup

**Category:** Storefront  ·  **Min plan:** Free  ·  **Slug:** `offer-variant-popup`

Replaces the inline per-piece variant selector with a beautiful, responsive popup modal when customers select multi-quantity offers. Shows variant images, colors, and names in an easy-to-use interface.

## Features

* Beautiful responsive popup modal
* Shows variant images and colors
* Per-piece variant selection for offers
* Auto-scroll to the next unfinished piece
* Cross-piece stock awareness

## What it does

When a product has a **multi-quantity offer** (*"Buy 3, save 20%"*, *"Pack of 2"*, *"Buy 1 get 1 free"*), each piece can have its own variant selection — a customer buying 3 t-shirts may want 1 red, 1 blue, 1 black.

By default, this is shown as inline pickers on the product page — clean for 2 pieces, cramped for 5. The add-on replaces those inline pickers with a responsive modal:

* One section per piece in the offer, all of them in a single scrollable sheet.
* When the customer finishes a piece, the modal smooth-scrolls to the next unfinished one.
* Variant images render with the larger card layout — easier to tap on mobile.
* The customer taps **تأكيد / Confirmer** (*Confirm*) when every piece is filled. That validates the picks, updates the displayed price and totals, and closes the modal.

Confirming does **not** add anything to the cart. Adding to cart / submitting the order stays a separate action on the product page.

After confirming, the product page shows a compact summary of each piece's picks (with colour dots). Tapping that summary reopens the modal with the previous selections preserved, so a customer can change one piece without redoing the rest.

## How to activate

1. Open **Dashboard → Add-ons** at [`/dashboard/addons`](https://dzbuild.com/dashboard/addons).

2. Find **Offer Variant Popup** under *Storefront*.

3. Click **Activate** (Free plan).

4. The settings panel exposes:

   <!-- -->

   * **Auto-advance to next piece** — on by default: after a piece is complete the modal scrolls to the next unfinished one. Turning it off does **not** add a Next button (there is no Next button) — the customer simply scrolls to the next piece themselves.
   * **Show variant images**: on by default. Turned off, no option shows a photo: colour options keep their colour swatch, image options without a colour show a plain tile, and text options stay text. Even with it on, an image only appears for variant options you have linked to one of the product's gallery images: colour options without a linked image render as a colour dot, and plain text options render as text.

No product setup required beyond the offers and variants themselves.

## Where it applies

* The product page, on all seven live themes — including `digital`.
* Only for products that have **both** multi-quantity offers **and** variants. If either is missing, the add-on does nothing and the standard picker is used.
* **Not** on landing pages (`/landing/...`) — those keep their inline per-piece pickers.

## Compatibility

* Compatible with [Cascading Variants](https://dzbuild.com/docs/addons/cascading-variants.md) — child groups appear inside the modal once the parent is picked. The add-on also fixes add-to-cart validation for that combination: cascade-hidden child groups no longer count as unfilled, so customers stop hitting false "please select all options" errors.
* Compatible with [Stock Management](https://dzbuild.com/docs/addons/stock-management.md) per-combination stock. It doesn't just hide globally sold-out combinations — it also accounts for what the *other* pieces of the same offer have already taken. A customer buying 3 of a variant with 2 in stock cannot pick it three times: the option greys out and is deselected. Options with no stock value set are treated as unlimited.
* Compatible with the [Multi-Language](https://dzbuild.com/docs/addons/multi-language.md) add-on — popup labels translate.

## Tips

* Leave **auto-advance** on for fashion (Color → Size flows fast). Turn it off when each piece has many groups (Brand → Model → Year) so the customer can review picks at their own pace before scrolling on.
* The **Show variant images** toggle is most useful when your variants are visually distinct (colors, prints). It changes nothing for pure text variants like sizes: they always show as compact text buttons.
* Pair with [Image Cadre & Crop](https://dzbuild.com/docs/addons/image-cadre.md) so the variant images in the popup are framed correctly.
* For one-piece offers (no multi-quantity), the popup doesn't activate — the customer sees the standard inline picker.