# Mix-and-match box

Chapter 10 of the Sprinkle user guide.

The Mix-and-match box lets shoppers fill a box flavour by flavour and see it fill. On the left: your flavours as rows, each with a small round, its name, "$5.50 each" and a stepper. On the right: a Box of 6 and Box of 12 control and **the open box**, a tray in your colour block with a numbered slot for each treat. Each flavour added drops a cookie into the next slot. Under the tray: "4 of 6", a progress bar and the button. When the box is exactly full, there's one small burst of sprinkles and the button changes from "Add 2 more" to **Add box to bag · $32.00**.

## Set it up

1. **Create the box product** in admin, with an option called **Size** and one variant per box, priced per box: "Box of 6" at $32.00 and "Box of 12" at $60.00. Because the price is on the variant, no discount app is needed.
2. **Tag it** `mix-box` (or the tag you set in **Theme settings › Mix-and-match box › Mix box tag**), and set its **Theme template** to `product.mix-box`. Do both: "The box has no Add to bag of its own", below, says why.
3. **Create the flavours collection.** Each flavour is a product in one collection. They can be products you also sell on their own, or products that exist only for the box. Rows follow the collection's own order, so choose the sort order you want (**Manually** gives you full control).
4. **Choose the flavours.** In the theme editor, open the box product, select the **Mix-and-match box** section under the Product section and choose the **Flavours collection**. Leave **Box product** blank: on a product template it uses the page's product.
5. **Add it to the home page too,** if you like. Sprinkle and Patisserie have the section there already: choose the **Box product** and the **Flavours collection**. Anywhere else, click **Add section** and choose **Mix-and-match box**.

The section's settings:

| Setting | Default | What it does |
| --- | --- | --- |
| Eyebrow | "Mix and match" | The small line above the heading |
| Heading | "Build a box of 6 or 12" | The section's heading |
| Text | "Pick your favourites, one by one. We bake them fresh for your pickup date." | The lede |
| Box product | Empty | The product with your box variants. Blank on a product template uses that page's product. |
| Box size option name | "Size" | The option that holds your box sizes. With no match, the first option is used. |
| Flavours collection | Empty | The flavours |
| Flavours to show | 12 (6 to 24) | The most rows to list, from the top of the collection |
| Cart property name | "Flavours" | The name of the line's property on the order |
| Background | Page | Page, Surface or Icing |
| Show piped edge | Off | Chapter 4 |
| Piped edge back row | Icing | Chapter 4 |

With no product or no collection, the theme editor shows a sample tagged **Sample** and shoppers see nothing. A box product without the tag gets a warning in the theme editor, because its own page and cards can still sell it with no flavours.

**The box size comes from the variant's name.** Sprinkle takes the first number in the option's value, so "Box of 12" holds 12, "12 macarons" holds 12 and "Dozen" holds nothing. A value with no number is left out, and the theme editor lists it. If no value has a number, the box can't be built: the editor says so and shoppers don't see the section. You aren't limited to 6 and 12: Patisserie's demo uses a Box of 12 and a Box of 24. With only one size, the control hides.

## How it behaves

* **The sum rule.** The counts must add up to exactly the box size before the box can be added. **+** stops at the box size and **−** at 0. Shoppers can repeat a flavour as often as they like.
* **Changing size.** Switching from 12 to 6 with 8 chosen keeps all eight: "8 of 6. Take out 2 to fit this box." Nothing is dropped silently, and the button stays off until it fits.
* **Sold-out flavours** stay listed, with "Sold out" in place of the stepper and a faded image, so shoppers know the flavour exists. If every flavour is sold out, the section says "All flavours are sold out for now."
* **A sold-out box size** shows as unavailable in the size control.
* **After adding**, the steppers reset and the bag opens.
* **Screen readers** hear each step ("4 of 6 chosen.") and the limit ("Box full. 6 of 6.").

## On the order

The box is one line item, with one property, written exactly like this, in the collection's order:

| Property | Example |
| --- | --- |
| `Flavours` | 2× Choc chip · 4× Red velvet |

To call it something else, such as `Macarons`, change **Cart property name**.

**What to know about price and stock:**

* **The shopper pays the box variant's price.** The "$5.50 each" on a row is that flavour product's own price, shown for information, and it isn't added up. If a flavour exists only for the box, price it at what one treat costs, or what you'd like the row to say.
* **Stock is counted on the box.** The flavour products' stock isn't touched by a box sale, so track stock on the box variants, and mark a flavour sold out yourself when you run out.
* **Lead time comes from the box product.** Set `custom.lead_days` on the box. The flavours' own lead times aren't read for the box.

## The box has no Add to bag of its own

The section is the only place a box gets its flavours, and a box added anywhere else would have none on it. So a product with the **Mix box tag** can't be bought any other way:

* **On its own page** the Variant picker, Add to bag, Buy it now and the sticky bar are gone. A **Choose flavours** button takes the shopper down to the section instead.
* **On cards** it reads **Choose flavours** and links to its page, with no quick add and no **Quick look** pill.
* **Quick view** shows a **Choose flavours** link, should a search result or an app open it.
* **A Featured product section and Ready-made boxes** show the same link, and the **Quick order list** doesn't show on it.

**If the page has no working box,** because the product uses another template or no **Flavours collection** is chosen, shoppers see "This box can't be filled on this page yet. Get in touch and we'll take your order.", with a link to the page with the handle `contact` if you have one. The theme editor says what's missing in place of that line. Nothing offers an unfilled box.

**With script turned off** the section's add button stays off too, and the section says the box needs JavaScript.

If you make your own template for a box, it needs a **Mix-and-match box** section with **Box product** blank or set to that product.

## Allergens and the box

Each flavour's name links to its product, and a row shows a small "Contains: wheat, egg, milk." when the flavour has `custom.allergens`. A flavour with none shows no line, not the fallback. The full statement lives on the product page (chapter 11), so:

* Fill in the **box product's** `custom.allergens` to cover **every** flavour it can hold, and its `custom.dietary` with only what's true of every flavour.
* Fill in `custom.allergens` on each flavour, so the row can say what's in it.