Important — Choose the correct implementation path

Most Growth Theme–based themes already use the shared V2 product-options renderer and require CSS only. Do not add custom Jinja, JavaScript, or selection logic unless your theme intentionally replaces the shared renderer.

Dynamic Bundle options#

Info — Dynamic Bundle scope

Do not reuse the Product Details Page list-option CSS as an implementation requirement for Dynamic Bundle option chips. Dynamic Bundle display behavior is owned by vitrin-sdk.

Terminology

Although the metadata value is named icon, it contains an absolute image URL and is displayed as an image thumbnail.

Metadata example#

{
  "id": "color-option",
  "name": "Color",
  "slug": "color",
  "choices": ["Red", "White", "Pattern", "Blue"],
  "choices_metadata": {
    "Red": {
      "id": "choice-red",
      "value": { "en": "Red" },
      "type": "color",
      "type_value": "#ff0000"
    },
    "White": {
      "id": "choice-white",
      "value": { "en": "White" },
      "type": "color",
      "type_value": "#ffffff"
    },
    "Pattern": {
      "id": "choice-pattern",
      "value": { "en": "Pattern" },
      "type": "icon",
      "type_value": "https://cdn.example.com/pattern.png"
    },
    "Blue": {
      "id": "choice-blue",
      "value": { "en": "Blue" },
      "type": "default",
      "type_value": null
    }
  }
}

Metadata mapping#

Important — Exact key matching

A metadata entry must use the exact raw choice value as its key. Metadata is presentation-only; the raw choice string remains the value used for variant selection.

Supported metadata values#

Fallback behavior#

Warning — Failed image requests in custom renderers

The fallback rules above cover missing or invalid metadata resolved before rendering. In a fully custom renderer, an image URL may appear valid but still fail when the browser requests it. Prefer the shared renderer or shared macro, and preserve the theme's existing image-error handling when implementing custom markup.

Recommended path

Use the shared V2 product-options renderer whenever possible. It owns the supported metadata, markup, fallback behavior, and selection compatibility.

CSS selectors#

Styling considerations#

Tip — Design-system customization

You can adjust the fallback values for --border, --radius, --foreground, --background, and --primary to match your theme. Keep the required dimensions, visible light-color border, and distinguishable active state when customizing the appearance.

Standard renderer checks#

Custom renderer checks#

Important — Regression testing

Test products with and without metadata. The feature must enhance presentation without changing variant matching, availability behavior, or add-to-cart behavior.

Important — Standard themes should stop before this section

This section is not needed for Growth Theme–based themes that use the V2 product-options renderer. Use it only if your theme intentionally renders product options with its own markup.

Use the shared V2 product-options renderer#

{% with options=product.options, product=product, style='list' %}
  {% include 'vitrin:v2/products/options/variant_options.jinja' %}
{% endwith %}

Use the shared product-option macro#

{{ render_variant_option_choice(option, choice, is_selected) }}

Tip — Prefer the shared macro

The shared macro reduces duplicated rendering logic and preserves the supported metadata and fallback behavior. Use fully custom markup only when the theme has a specific requirement that the shared renderer or macro cannot meet.

Create custom list markup#

{% set display = option.choice_display(choice) %}

<li
  value="{{ choice }}"
  onclick="productOptionListItemClicked(event)"
  class="product-options__item product-options__item--{{ display.type }}{{ ' active' if is_selected else '' }}"
  {% if display.type != 'default' %}
    title="{{ choice }}"
    aria-label="{{ choice }}"
  {% endif %}
>
  {% if display.type == 'color' %}
    <span
      class="product-options__swatch"
      style="background-color: {{ display.value }};"
      aria-hidden="true"
    ></span>
    <span class="product-options__item-text product-options__item-text--sr">{{ choice }}</span>

  {% elif display.type == 'icon' %}
    <img
      class="product-options__thumb"
      src="{{ image_url(display.value, w=64, q=85, f='auto') }}"
      alt="{{ choice }}"
      width="40"
      height="40"
      loading="lazy"
    />
    <span class="product-options__item-text product-options__item-text--sr">{{ choice }}</span>

  {% else %}
    <span class="product-options__item-text">{{ choice }}</span>
  {% endif %}
</li>

Accessibility note for fully custom markup

Preserve the keyboard and interaction behavior already used by your theme. A clickable custom choice must remain reachable and operable for keyboard users, expose its selected state through the theme's existing accessibility pattern, and keep the raw choice label available to assistive technologies. The shared renderer or macro remains the preferred implementation.

Preserve variant-selection compatibility#

Warning — Metadata is not the selected value

Do not use id, type_value, a hex color, or an image URL as the <li> value. Metadata controls presentation only; selection continues to use the raw choice string.

Accessibility requirements#

Native dropdown limitations#

Info — Expected dropdown behavior

A native dropdown continuing to show text is expected and is not a fallback error. Visual swatches and thumbnails require a list-style renderer.

Do Growth Theme–based themes need custom Jinja or JavaScript?#

What happens when choices_metadata is missing or invalid?#

Does type: "icon" expect an icon-library name?#

Does this CSS apply to Dynamic Bundle options?#

Can native <select> dropdowns display color swatches or images?#

Which value must a custom renderer use for variant selection?#

Final publishing check

Before publishing, confirm that the implementation changes presentation only. Products without metadata must continue to render and behave as they did before, and selecting a visual choice must still resolve the correct variant and preserve add-to-cart behavior.