1. Developing Open Storefront Framework Applications for Oracle CX Commerce
  2. Design Storefront Pages
  3. Configure and display color swatches

Configure and display color swatches

Swatches let shoppers see images of a product in all its available colors without leaving the product details page.

When a shopper clicks a swatch, the main product image changes to display the product in the selected color. If applicable, other product information, such as price, description, and sizes, is also updated along with the product image.

To display swatches on a product details page, you must configure catalog, widget, and image settings.

Configure catalog settings

First, you must create a custom property on productType and set both its name and ID to x_swatchMapping. Make sure you select Allow property to be searched for this property in order to enable color swatches to appear on the product listing page.

You can create the custom property on either the Base product type or any custom product type that requires swatches. See Create and edit product types for more information about creating custom product-type properties.

Once you have created the custom property, modify packages/tools/cli/config/search/index.js to include product.x_swatchMapping under attributes and sku.<colorProperty> (for example sku.color) under childRecordAttributes, and run the command yarn occ upload-search-config. For more information, see Develop and Deploy Applications.

Finally, populate the product property (x_swatchMapping) on a product with mapping information. For example: 

{"Gray":"gry","Red":"red","Pale Green/New Green":"pgn"}

The key must match the color values configured on the product. The value can be any short string.

To see the colors configured on the product, open the Commerce administration interface. Edit the product and click its SKUs tab. Under Configure Storefront Display, look for colors available for that product.

Configure the Product Variant Options widget

The Product Variant Options widget displays a product's variant options, such as color or size. To display color swatches, you configure the widget to display the options as swatch images. Before you configure the widget, make sure you have configured catalog settings and uploaded the images you want to use.

You can configure the widget on the Design page in the Commerce administration interface. Edit the following options:

  • Color Swatch Variant Option (Variant Option To Be Displayed As Swatch Image): Leave the setting at the default value, which is Color.
  • Product Property for Color Swatch Mapping (Product Property that contains swatches mapping information) The default value is x_swatchMapping. If you change the name from x_swatchMapping, an additional step must be taken to ensure this value is returned in search results. First, edit the file packages/tools/cli/config/search/index.js to change the x_swatchMapping in product.x_swatchMapping to your new property name, then run yarn occ upload-search-config to upload this new configuration.
  • Color Swatch URL placeholder. (The URL template used for product color swatch images). You can modify this URL if you want to fetch JPG images instead of PNG images, or if you are looking for images in a different path. The default value is:
    /ccstore/v1/images/?source=/file/products/__productId__.__swatchKey__.png&outputFormat=JPEG&quality=0.8&height=__height__&width=__width__

    When the widget renders a product, it replaces the __productId__ and __swatchKey__ and finally resolves to a valid image URL. For example, the __swatchKey__ is replaced with gry, red or pgn values from the following mapping on the product: {"Gray":"gry","Red":"red","Pale Green":"pgn"}.

  • Overlay Image for Unavailable Color Swatch (The image used to overlay on a swatch image, if the swatch is invalid or unavailable) The default value is /file/general/outofstock_overlay.png.

Configure site-level settings

Upload the swatch images on the administration interface Media page, under Products. For example, the gray swatch image in media could be named prod10004.gry.png.

Now when the widget replaces __productId__ and __swatchKey__ parts of swatchUrlPlaceholder to a valid URL, it finds the image in the media library and renders it on the UI. The final URL might look like this: 

/ccstore/v1/images/?source=/file/products/prod10004.gry.png&outputFormat=JPEG&quality=0.8&height=40&width=40

where __productId__ = prod and 10004 __swatchKey__ = gry