Garland builder

The garland builder lets a shopper design an organic balloon garland on the product page: pick up to four colours, choose a style and a length, and watch the preview redraw. You pack the kit, or build the garland, in exactly that mix. It needs no app and no metafield: it reads its own block's colours and settings, and a product option for the length.

What shoppers see

• A live preview: an arc of balloons in three sizes on a soft wall, with a metre ruler under it. It's laid out from a fixed pattern for each product, so the same product always draws the same garland, and changing a colour only recolours the balloons; they never jump about. A longer length draws a longer arc. With nothing picked, it's a pale "ghost" garland and the line under it says "Pick up to 4 colours to see your garland."
• A text summary next to the preview, for everyone including screen reader users: "Organic, 3 m: Sage, Sand, Terracotta", with "About 110 balloons" beside it.
• Style: Classic ("Even 11" balloons") or Organic ("5", 11" and 18" mixed").
• Colours: one balloon swatch per colour, each with its name, ticked like checkboxes. The legend counts "2 of 4 picked". When the shopper reaches the most allowed, the others fade, and the line says "You've picked 4 colours, the most for this garland. Untick one to swap."
• Length comes from the product's own variant picker, which sits above the builder: choose 3 m and the preview and summary follow.

Buy it now stays hidden until at least one colour is picked, because it would skip the colours. If the shopper presses Add to cart with no colour, nothing is added: "Pick at least one colour." appears under the colours and the first colour gets focus.

Set it up

1. Create the product, such as "Organic garland kit", with an option called Length and one variant per length: 2 m, 3 m, 4 m, 6 m. Price each length.
2. Assign the product.garland template in the product's Theme template field and Save. The builder is already on that template, under the variant picker.
3. Set your colours: open the theme editor, choose Products › garland, and click the Garland builder block. Each colour is a Garland colour block inside it: rename, recolour, add, remove and reorder them. The presets ship eight (White, Sand, Sage, Terracotta, Blush, Cobalt, Sunshine and Chrome silver in Hooray).
4. Point the home page at it: in the home page's Featured product section, choose the kit as the Product. That section has its own Garland builder block with its own colours, so set them there too.
5. Set a lead time if you pack to order: give the product a custom.lead_days, such as 3. The cart's first event date then allows for it, and the panel says "Your garland needs 3 days, so the first date is…" (chapter 10).

Colours are set in each place the builder appears: the product.garland template and each Featured product section. Quick view borrows the colours from the product's own page.

Garland builder settings

Each Garland colour block has a Name ("Sage") and a Colour (#a8b596). The name is what the shopper reads and what's saved on the order, so use names your team will recognise when packing. With every colour removed, the theme editor shows a note and shoppers see no builder.

Lengths the builder understands

The builder reads the number at the start of the length value, and its unit: 3 m, 3 metres, 3m, 300 cm, 10 ft and 10' all work. A value with no unit counts as metres. The preview and the summary always show metres, so 10 ft reads "3 m". A value with no number, such as "Large", uses Length when no option matches.

If your lengths are a Size option, they still work: Size is on the list by default. If you call it something else, such as "Garland length", add that name to Length option names.

What you get on the order

The colours and the style are saved with the line as two line item properties:

The length is the variant itself ("3 m"). The shopper sees all three in the cart and at checkout. In Shopify admin, open the order: the properties are listed under the product's name in the order's items, and they're on the order whatever the shopper's device. Two garlands with different colours are two separate lines.

The property names come from the theme's words: change or translate Colours and Style in Edit default theme content if you need to (chapter 15).

Where else the builder works

• Featured product: with Layout set to Garland preview in place of the gallery, the live preview takes the gallery's place, as in every preset's home page. It needs a product chosen (chapter 4).
• Quick view: products on product.garland show the builder in quick view, with the colours from their product page. Quick add on their cards opens quick view rather than adding a garland with no colours.
• Other templates: you can add the Garland builder block to any product template, but keep garland products on product.garland: quick add and quick view only recognise that template, so a garland on the default template could be quick-added with no colours.