Variant Selector

The variant picker — buttons, dropdown, or custom designs — that sets the shared selection per product.

Last updated

August 14, 2026

How to use

Place the component on the product page or product card and connect ⛁ Butter Data to the product's Butter Data CMS field.
Choose Style — Buttons or Dropdown — and Mode: Config to style built-in states, or Connect to use your own designs.
Configure Behavior: which option(s) this instance controls, its Action, whether it auto-selects the first value, and how it treats out-of-stock options.
Set up Image Triggers so picking a value can update the product gallery — see the image triggers section below.
Style Title and Container — these apply in both modes. Then, in Config mode, style the Button/Dropdown/Swatches state colors (Default/Hover/Selected/Out of Stock); in Connect mode, connect your own designs instead — see Style and Mode below for exactly which slots each combination needs.

Style and Mode

Style picks the picker's shape — Buttons (one control per value) or Dropdown (a single trigger that expands) — and Mode decides where the design comes from:

	Config	Connect
Buttons	Built-in styled buttons — colors, borders, and fonts for Default/Hover/Selected/Out of Stock states.	Your own connected designs, with a `Type` choice — `Templated` or `Slots` — see below.
Dropdown	A native select styled through the panel.	Connect `⦿ Selected`, `⦿ Unselected`, and `⦿ Disabled` trigger designs — one trio covers every value; nest Variant Value inside for the dynamic label. If left empty, `⦿ Unselected` and `⦿ Disabled` just fall back to the Selected design.

Swatches aren't a Style choice. In Config mode, Butter automatically renders color or image swatches instead of plain buttons whenever it detects a swatch-eligible option — typically one named "Color", or one with variant images — styled via the Swatches group. Swatches only work in Config mode; switching to Connect hides that styling group entirely, since a connected design already controls its own appearance.

Connect + Buttons also unlocks a Layout group for arranging your connected designs instead of the built-in stack.

Which options this instance controls

The Behavior filter decides which option Name(s) an instance drives — all of them, or a Name that equals or doesn't equal a value. For a multi-option product (Size and Color), place one instance per option and filter each to its own Name, or use a single combined instance — pick one pattern and stay consistent on the page. This component is the source of the selection: Price, media, and the Purchase Button all update automatically from it, so don't try to set the variant anywhere else.

Turning a picker into an add-to-cart control

The Behavior Action can be set to Update Active (the normal picker behavior), Add to Cart, or Buy Now — the latter two let a single-variant option group double as its own purchase control, with a Cart trigger setting alongside it. Only use Add to Cart or Buy Now on single-variant groups.

Availability and auto-selection

Behavior holds four more decisions, one per control:

Select 1st — auto-select the first available value on load, so the product starts purchasable instead of waiting for a choice.
PDP — mark instances that live on the product page itself (rather than a card or quick-add), so selection behaves correctly for that context.
Singles — whether the selector still shows for a single-variant product, or hides itself since there's nothing to choose.
Out of Stock — whether out-of-stock options can still be clicked (to show their price or media) or are locked out entirely.

Separately, buttons and swatches use their own ⦿ Out of Stock style or design for unavailable values — that's about how they look, independent of whether they're clickable.

Linking selection to the gallery

Image Triggers connects the picker to the product media: choose the Type — None, Gallery, or Scroll Sections — set whether it fires ↳ On Click or Hover, turn on Two-Way so clicking a gallery image also updates the selection, set an Offset Y, and style the trigger's Border.

Option labels

Title controls how each option's name displays, using {{value}} in the template; leave it empty to show just the option title.

Connect + Buttons: Templated vs. Slots

This choice only exists for Connect mode with Style set to Buttons — Dropdown always uses one fixed ⦿ Selected/⦿ Unselected/⦿ Disabled trio (see above), and Config mode doesn't connect designs at all.

The Type control decides how your connected designs map onto option values. Use Templated to connect a single design to dynamically repeat for every option, or Slots to create a custom, manually connected design for each unique option.

`Type`	What you connect	How it maps to values
`Templated` (default)	One `⦿ Unselected` design — leave it empty and the whole picker shows a placeholder instead of rendering. `⦿ Selected` and `⦿ Out of Stock` are optional: leave either empty and that state just uses the Unselected design instead, so selected or out-of-stock values won't look visually different until you connect them.	The same design is repeated once per value, automatically. Nest Variant Value inside so each repeated button shows its own value's label.
`Slots`	Set `No. of Slots`, then for each slot connect its own `Unselected`/`Selected`/`Out of Stock` designs and type the exact `Option Value` it represents (e.g. "Red"). Add an `Option Name` too (e.g. "Color") unless this instance's `Behavior` filter is already narrowed to `equals` one option.	Each slot only renders for the value you typed — matched by exact text, not by position. A CMS value with no matching slot renders nothing.

Two things worth knowing before you build a Slots setup:

New values need new slots. If you add a color in Shopify that doesn't have a matching slot here, that option silently disappears from the picker — there's no fallback design for an unmatched value the way Templated always has one.
Each matched slot still needs its own Unselected at minimum. The same fallback pattern as Templated applies per slot — an empty slot Selected or Out of Stock design just falls back to that slot's Unselected. But if a slot's Unselected is also empty, that one option disappears silently rather than showing a placeholder; the group-wide placeholder only appears if every slot fails to resolve anything.
Fill in Option Name when driving more than one option. If this instance's Behavior filter isn't set to match exactly one option, slots are matched by Option Name and Option Value together — skip Option Name only when you're certain the instance is scoped to a single option already.