On a product card, customers pick a variant with the variant selector. In the Card Editor you can choose how that selector looks:
One dropdown for the whole product, with optional swatch or variant image thumbnails.
Option groups: one selector per product option (for example Size, Color, Material), each shown as buttons, swatches or a dropdown.
[screenshot - the same product card three ways: basic dropdown, swatch thumbnail dropdown, option groups with size buttons and colour swatches]
The step must use an Editable card template. Legacy card styles keep the standard dropdown. See Card Template Editor.
The step must show product cards (display type: product level). Variant cards show one variant each, so they have no selector.
The selector only shows on products that have variants.
For swatches, set them up in Shopify first (next section).
Swatches come from the swatches on your product option values. Shopify stores them as category metafield entries that are connected to the option.
Give each product a product category.
Add or edit the swatch entries for the option values (a colour, an image, or both).
Connect the option (for example Color) to the category metafield.
Shopify explains all three steps here: Adding color swatches using category metafields.
Options other than Color, or your own metaobject: see Add variants with metafields.
If you use your own metaobject, turn on Storefront access for it. See Options for custom data.
If you store swatches in a variant metafield instead, see "Use a variant metafield" below.
Open the bundle, find the step, and under Card style click Open layout editor.
Make sure the Product template type is selected in the header.
Click Variant selector in the component tree, or click the dropdown in the preview. Clicking blocks in the preview is on by default. The target button in the header turns it off.
Under Selector style, turn Show option groups off for one dropdown, or on for option groups.
[screenshot - Variant selector settings panel with the Selector style section]
Dropdown style
Basic: the standard dropdown.
Swatch thumbnails: each row shows a swatch next to the variant name. The swatch comes from the first option (in option order) whose value has one. A variant with no swatch shows its variant image, then the product image, then text only.
Variant image thumbnails: each row shows the variant image. A variant with no image shows the product image, then text only.
Group by first option (thumbnail styles only): splits the list into sections. Each section heading is a value of the first option, for example a size. The rows under it show the remaining options. Only for products with more than one option. The closed dropdown still shows the full variant name.
Image shape (thumbnail styles only): Square or Circle thumbnails.
Swatch thumbnails only: by default, swatches come from the swatches set on your product option values. Tick Use a variant metafield to check a variant metafield first, then the Shopify swatch (see below).
[screenshot - open swatch thumbnail dropdown grouped by first option]
The card shows one selector per product option. Shopify allows up to 3 options. Each option name appears with a suffix, for example "Color:". You can change the suffix in Settings > Languages (Option name suffix).
Option styles are rules. Each rule says how the options with certain names look.
Option names: the option names this rule applies to, separated by commas. List the name in every language your store uses, for example "Color, Colour, Farbe, Couleur". Matching ignores capital letters and spaces around the names. If a name is in two rules, the first rule wins.
Style
Buttons: text buttons. With an image source, each button also shows a small swatch or thumbnail before the text.
Images only: swatch or image chips with no text. The selected value's name appears next to the option name. With a mouse, hovering a chip shows its name there. With Image source None, this style shows as Buttons.
Dropdown: a dropdown for this option, with thumbnails when an image source is set.
Image source: None, Swatches (your Shopify swatches) or Variant images.
Image shape (Swatches or Variant images only): Square or Circle.
Use a variant metafield (Swatches only): check a variant metafield before the Shopify swatch (see below).
A new selector starts with three rules. Size: Buttons, Image source None. Color: Images only, Image source Swatches. Material: Dropdown, Image source Variant images. Edit or remove them to match your products. You can add up to 10 rules.
If you turn Show option groups off, the rules stay saved and come back when you turn it on again.
Fallback style sets how options with no matching rule look: Buttons or Dropdown, text only.
[screenshot - option styles list with three rules and the Add option style row]
Values with no variant in stock: buttons and chips are greyed with a diagonal line through them. Dropdown rows are greyed and labelled Sold out. For the second and third option, this is judged against the values already chosen. A variant with less stock than the step's fixed quantity counts as sold out.
If the chosen combination of options is not in stock, the app keeps the option the customer just changed and picks the in-stock variant that matches the most of the other chosen options. Screen readers hear "Selection adjusted to ..." You can change this text in Settings > Languages.
If every variant of the product is sold out: the basic dropdown is hidden; thumbnail dropdowns and option dropdowns are disabled and read Sold out; buttons and chips are all struck out; Images only shows Sold out next to the option name.
Option values that only exist on variants you left out of the step are hidden.
With a mouse, hovering a swatch chip or a button with a thumbnail shows that variant's image in the card's Media block. The variant needs its own image; otherwise the product image stays. Touch has no hover preview.
Dropdowns work with the keyboard: arrow keys, Home and End move; Enter, Space or Tab select; Escape closes; typing jumps to a matching value. Buttons and chips work like radio buttons.
With the Add to bundle button on: buttons and chips show a small dot on values already in the bundle. For the second and third option, the dot shows only on values that match the earlier chosen values. The single dropdown's rows show "x2" or "Required". A per-option dropdown shows them only when the product has one option.
For an option style with image source Swatches, the app looks in this order and uses the first thing it finds:
The variant metafield, when Use a variant metafield is on and a metafield is set.
The Shopify swatch on the option value: its image first, then its colour.
The image of the first variant in the step that has that value.
The product image. For the Dropdown style, always. For Buttons and Images only, only when the product has variant images.
Text only, when none of the above exists.
For image source Variant images, the app uses the image of the first variant in the step that has that value, then the product image under the same rule, then text only.
Shopify swatches belong to the option value, so every size of a colour shares one swatch. Metafield swatches and variant images come from the first variant in the step that carries the value. If you set swatches per variant, set the same swatch on every size of that colour. If the card's Media block replaces images with a metafield, the thumbnails follow that setting.
Tick Use a variant metafield and pick the metafield. It must be a variant metafield of one of these types:
Color
File (an image)
Metaobject reference, where the metaobject has a Color field, a File field that accepts images, or both. The image shows first; the colour shows when the entry has no image.
For an option style, the app picks the metaobject's first Color field and first image field, and you can change them. For the single Swatch thumbnails dropdown, the metaobject fields must be named image and color.
If the swatches do not show on your store, check that Storefront access is on for the metaobject and for the variant metafield definition. See Options for custom data.
[screenshot - the Swatch variant metafield picker showing a metaobject's Color and Image fields]
The dropdowns and option buttons take their colours from the theme block settings you already use: input text color and background, product card text color and background, and the card text colour for the selected outline. There are no separate settings for them. See Customise the look of your bundle form.
For developers: the new elements use classes that start with biscuits-bundle-radio-group, biscuits-bundle-option-select, biscuits-bundle-variant-select, biscuits-bundle-option-thumbnail and biscuits-bundle-option-swatch, inside biscuits-bundle-item__option-groups or biscuits-bundle-item__options--custom-dropdown. An open dropdown list is moved to the form while open, so Custom CSS scoped to the card does not reach it.
Stores that saved their languages before this release do not have the two new texts yet. Open Settings > Languages, select each language you use, and save. Check Option name suffix while you are there.
Check that the step uses an Editable card template and shows product cards.
If the styled selector cannot load on the page, the app shows the standard dropdown so customers can still choose. Check the browser console for a "Biscuits Bundle Error" message and send it to us.
Open the Variant selector settings. Check that the rule's Option names include the option name exactly as it appears on the product, in each language.
Check that the rule's Image source is not None.
If you use your own metaobject, check that Storefront access is on. For the single Swatch thumbnails dropdown, the fields must be named image and color.
Shopify sometimes loses the connection between a product option and the category metafield entries that hold the swatches. The product then shows text values instead of swatches, in the bundle and on its own product page.
Check the product page first. Open the product's own page on your storefront. If your theme shows swatches and they are missing there too, the problem is the Shopify connection, not the bundle. You can also open the product in Shopify admin: a connected option shows the metafield name next to the option name in the Variants section.
Refresh the connection on the parent product, not on a single variant:
In Shopify admin, open the product. In the Variants section, edit the option (for example Color).
Click the connected metafield name, then click Disconnect. The option becomes a custom option. Save.
Edit the same option again. Click the dynamic source icon and select the Color category metafield.
Check that every existing value is still selected. Save.
Do not delete the option. Do not remove and recreate the variants. If Shopify warns that values will be cleared or variants deleted, click Cancel, stop, and contact Shopify Support.
This refreshes the connection. It does not fix every case. If the swatches are still missing on the normal product page, contact Shopify Support. Shopify describes connecting and disconnecting options in Add variants with metafields.
[screenshot - Variants section with the connected metafield name and Disconnect button]
[screenshot - the dynamic source icon on the option, selecting the Color category metafield]
