Display swatches in product overview

Since version 3.1.7

Why?

Product overview pages (category listings, search results, etc.) traditionally show a single variant of configurable products. The swatch feature allows customers to preview and switch between different variants directly from the product overview, improving the shopping experience by:

• Showing color/style variations without leaving the page
• Allowing quick comparison of different variants
• Reducing clicks needed to see product alternatives
• Improving visual browsing experience

This is particularly useful for:

• Fashion and apparel stores (showing different colors/sizes)
• Electronics with color variants
• Any configurable products with visual attributes

We have included a demo extension which is illustrated in the following sections.

How?

Enable the feature

import { defineExtension } from "@front-commerce/core";
import type { PublicConfig } from "@front-commerce/core/react";

type ProductItemConfig = PublicConfig["theme"]["productItem"];

const productItemSwatchConfigProvider = {
  name: "product-item-swatch-demo:public",
  values: {
    public: {
      theme: {
        productItem: {
          showSwatchGroup: true,
        } satisfies ProductItemConfig,
      },
    },
  },
};

export default defineExtension({
  name: "product-item-swatch-demo",
  meta: import.meta,
  configuration: {
    providers: [productItemSwatchConfigProvider],
  },
});

Understanding the implementation

The swatch functionality is implemented through several key components:

The useSwatchGroup hook

This hook processes the product configurations and returns:

• selectedProduct: The currently selected product variant
• swatchGroup: The swatch attribute group (if available)
• currentSwatchValue: The currently selected swatch value
• handleSwatchChange: Function to handle swatch selection changes

The Swatches component

This component renders the visual swatch options and handles user interactions. It supports different swatch types:

• Color swatches (showing actual colors)
• Image swatches (showing small variant images)

GraphQL integration

The feature requires product configuration data including:

• attribute_id: The attribute identifier
• code and value: The option values
• swatch: Swatch display information (type and value)