Magic Box

Magic Box lets the customer build a box: a case of 6 wines, a sampler of 3 coffees, a PC with one part from each category. The customer picks products from the lists you design, and the box goes to the cart as one line, with its own title and image. At checkout it stays one line, and it can carry a discount. This page covers the Shopify side, the box, its rules, categories and the box panel.

How it fits together

Everything goes inside one Custom element, smootify-magic-box.

What Smootify needs:

• a smootify-magic-box element;
• inside it, the products the customer can pick, each with its own add-to-cart form. Inside the box, these forms add to the box instead of the cart;
• inside it, a smootify-magic-box-cart: the box panel. It holds a box-item template, repeated once per product in the box, and a Form Block that adds the whole box to the cart. Without it, the box is removed.

What is up to you:

• how the products are listed: a Collection list, several lists, a Slider or Tabs;
• where the box panel sits (a sidebar, a sticky bar, under the products) and what it shows;
• the layout, classes and styles of every part.

A fixed box of 6 looks like this in the Navigator:

1. Give the box a title, an image and a discount

In the cart and at checkout, the box line shows a title and an image of its own. There are two ways to set them.

A Magic Box entry in Shopify. In Shopify, go to Content > Metaobjects > Magic Box and create an entry with a Title, an Image and, if you want one, a Discount Percentage. On smootify-magic-box, set data-handle to the entry’s handle. The merchant can then change the title, the image or the discount in Shopify without touching the site.

A static box. Set data-title and data-image on smootify-magic-box. The image must be a Shopify file: upload it in Shopify under Content > Files and copy its URL. Checkout ignores an image from anywhere else.

The discount applies to every box the customer can add to the cart under its limits, not only to a full one. For a discount only on a full box, give the box the same data-min and data-max, such as data-min="12" data-max="12".

The discount is a percentage off the whole box, applied at checkout.

2. Build the box

1. Add a Custom element with the tag smootify-magic-box around the products and the box panel.
2. Inside it, list the products. Any list works: a Collection list of product cards, or a list loaded from Shopify without the CMS (product lists). Each card needs a smootify-add-to-cart with a Form Block inside. Its button adds the product to the box. Variant pickers and a quantity field work as on the product page.
3. Inside smootify-magic-box, add a Custom element with the tag smootify-magic-box-cart. Put inside it:
   • a Custom element with the tag items-list, holding one Custom element with the tag box-item. The box-item is the template: Smootify repeats it for each product in the box. items-list shows only while the box has products;
   • optionally, a Custom element with the tag empty-state, shown only while the box is empty;
   • a Form Block with a submit button. It adds the whole box to the cart.

Inside box-item:

• box-item="title", box-item="image", box-item="price", box-item="total" (price × quantity), box-item="quantity" and box-item="category" show the product in the box;
• the product and variant values also work, such as variant="title" for the variant name. See box item values;
• a Custom element with the tag button and data-action="remove" takes the product out of the box.

After a product goes into the box, the quantity field of its form goes back to 1.

3. Set the size of the box

These attributes go on smootify-magic-box:

The box can be bought when the number of products is between data-min and data-max and a multiple of data-step. The add button stays disabled until then. Some sizes and the boxes they allow:

data-unique and the category rules below are on whenever they have a value, even false. Write true, and remove the attribute to turn a rule off.

When a product does not fit, the product’s form shows an error in its Error message. You can change the text of each error:

• data-full-error: the box is full. Default “Box is full”;
• data-too-many-error: the quantity is more than what fits. {quantity} in the text becomes the number that still fits;
• data-only-one: the product is already in the box and data-unique is on. Default “You can add only 1 item inside the box”;
• data-only-one-per-category: the category already has a product. {category} becomes the category name. Default “You can add only 1 item of {category} inside the box”.

4. One product per category

For a box that needs one piece from each group (a base, a sauce and a topping; a PC with a motherboard, a GPU and RAM), split the products into categories.

1. Wrap each group of products in a Custom element with the tag smootify-box-category.
2. Give it the custom attribute data-name with the category name, such as Sauce.

Then choose the rules on smootify-magic-box. For a pizza with a Base, a Sauce and a Topping:

Steps without interactions. Put each category in a slide of a Webflow Slider, or in a pane of a Webflow Tabs element. When the customer adds a product, the Slider or Tabs moves on: to the next empty category with data-all-categories, otherwise to the next slide or tab. When the customer removes a product, it goes back to that product’s category.

Completed categories. A category gets the class is-complete while the box holds at least one of its products, and so do the slide and the tab link that show it when every category in them has one. To show a check mark inside a tab link, put it in an element with box-condition="category-complete"; box-condition="category-incomplete" is the opposite.

In the box panel, data-prop="missingCategories" lists the categories still empty, separated by commas. separator changes the separator, and separator="repeat" makes one copy of the element per missing category.

5. Show progress and the price

Inside smootify-magic-box-cart, outside the box-item, these elements follow the box:

• data-prop="currentQuantity", "minQuantity", "maxQuantity", "leftQuantity" (how many more fit): numbers;
• data-prop="leftQuantityWidth" on a Div block: its width follows how full the box is, for a progress bar. data-prop="leftQuantityPercentage" shows the same as text;
• data-prop="discount-percentage" and data-prop="discount-amount": the discount of the box, as a percentage and as money;
• a smootify-price shows the box total after the discount in data-prop="price", and the total before the discount in data-prop="compareAtPrice" when there is one;
• box-condition="can-purchase" and box-condition="cannot-purchase" show an element only while the box can, or cannot yet, be bought.

smootify-magic-box-cart also gets classes you can style as combo classes. For a box of 6 wines at $20.00 each, the panel goes through these states:

The full lists are in Magic Box values and Magic Box conditions.

The add button. A Form Button works, or a Custom element with the tag button and type="submit". It is disabled until the box can be bought. A second Custom element with the tag button, type="submit" and name="buy-now" adds the box and goes straight to checkout. data-buy-now="true" on smootify-magic-box-cart sends every submit to checkout.

Extra fields. A field in the box’s form, such as a gift message, is saved with the box, under its field name, and shows with the box in the cart. A name that starts with _ is saved but not shown.

6. In the cart and at checkout

The box is one line in the cart, with the box title and image. In the cart, a box-item inside the cart-item template repeats once per product in the box, with the cart line values such as box-item="title" and box-item="quantity". The customer cannot change the quantity of a box: its quantity field is removed. With a box-item in the template, cart-item="options" lists only the box’s own fields, such as a gift message. Without one, it lists the products as text (“1 x Wool Socks”), as 1.x did.

At checkout Shopify shows the box as one line, with its title, image and discount.

Subscriptions. A box cannot be sold as a subscription: Shopify does not merge cart lines that have a selling plan. See subscriptions for what you can build instead.

Developers can add a box to the cart from code with addBoxToCart. They can also change the box title and image as the box fills, for example “Box of 4 wines”: see the Magic Box example.

Before you publish

On your .webflow.io address, the Smootify debugger lists the Magic Box elements and tells you when they are not running. See the debugger.

Coming from 1.x

• The default texts of data-only-one and data-only-one-per-category say “inside the box”, where 1.x said “inside the cart”.