Variant Swatches and Media Grouping

Use Firefly’s Variant picker to show native color swatches, variant-image swatches, custom gradient swatches, and variant-specific media groups. The swatch and media-grouping features share one option-name setting, so configure that setting first.

Before you begin

1. In Shopify admin, open Online Store > Themes and customize an unpublished Firefly theme.
2. Open a product template and select the Product or Featured product section.
3. Add or open the Variant picker block.
4. Choose Pills as the Picker type. Swatches are not shown with the Dropdown picker type.
5. In Option to display swatches and group media on, enter the exact product option name, such as Color, Colour, Farbe, or Couleur. If this field is blank, Firefly uses the first option whose name contains “color” or “colour.”

Group product media by variant option

Media grouping shows only the contiguous group of product media that belongs to the selected option value. Each group’s first image must be assigned as the variant image for that option value.

1. Upload all product media in complete, contiguous groups. For example: black1 → black2 → black3 → white1 → white2 → white3.
2. Assign black1 as the Black variant image and white1 as the White variant image.
3. In Firefly’s Variant picker block, enter the option name in Option to display swatches and group media on.
4. Turn on Enable media grouping.
5. Save, preview the storefront, and select every option value.

The assigned variant image is the boundary marker, not just a thumbnail. If White is assigned to white2 instead of white1, the Black group includes white1, and the White group begins at white2. Keep the first media item as the first group’s marker and assign the first image of every later group accurately.

If several variants share the same color, such as separate size variants, assign the same group-start image to those variants whenever possible. Test each option value, each available combination, and any direct variant link used in advertising or support.

Create custom gradient color swatches

Custom swatch colors read a valid CSS gradient from the ALT text of the matching variant’s assigned image. They are available only when Swatch display is set to Color swatches.

1. Turn on Enable swatches.
2. Choose Color swatches under Swatch display.
3. Turn on Enable custom swatch colors.
4. In the product’s Media area, open the image assigned to the matching variant and edit its ALT text.
5. Paste one valid CSS gradient function into the ALT text, then save the product and preview the storefront.

You can build a gradient with CSS Gradient. Its generated CSS may include a fallback color and a declaration such as background: linear-gradient(...);. Copy only the gradient function value: do not include background: or the trailing semicolon.

Firefly accepts linear, radial, conic, and repeating CSS gradients, including color stops written with rgba(). For example:

linear-gradient(125deg, rgba(0, 0, 0, 1) 30%, rgba(250, 0, 25, 1) 50%)

A blank or invalid ALT gradient falls back to the native Shopify swatch or option value. Firefly rejects unsafe or unsupported values such as url(...), comments, braces, semicolons, or multiple background-image values.

Choose the right swatch source

• Native Shopify swatches: best when Shopify’s product-option swatch data already represents the product accurately.
• Image swatches: choose Image swatches to use each matching variant’s assigned image as the swatch thumbnail.
• Custom gradient swatches: use ALT gradients for split colors, multicolor finishes, or other CSS-rendered color combinations.

Accessibility note: Custom gradient swatches repurpose variant-image ALT text as theme configuration. A screen reader may encounter that gradient code when the same image appears in the product gallery. If meaningful descriptive ALT text is important for that media, prefer native Shopify swatches or Image swatches.

Troubleshooting

• No swatch appears: confirm Picker type is Pills, Enable swatches is on, and the configured option name matches the product option.
• The gradient does not appear: confirm Swatch display is Color swatches, Enable custom swatch colors is on, the ALT belongs to the assigned variant image, and the value contains only one valid gradient function.
• The wrong media appears: reorder the product media into contiguous groups and verify that each option value is assigned to the first image of its group.
• A group starts one image late: move or reassign the boundary image. The assigned variant image always starts the group.
• Changes look stale: save the product and theme editor, then refresh the storefront preview before retesting every option value.

For the rest of the product-page controls, see Product Pages and Merchandising.