Color & Image Swatches

Swatches turn plain text filter options like "Red" or "Navy" into visual color circles or image thumbnails. Shoppers can identify and select colors at a glance instead of reading a text list.

You configure swatches from the Appearance tab on the Filters page (/app/filters), in the swatch configuration section.

What Swatches Do

When you enable swatches for a filter, each option value is displayed as a colored circle (or image thumbnail) instead of a checkbox label. For example:

• "Red" shows as a red circle
• "Navy" shows as a dark blue circle
• "Floral Print" shows as a small image of the pattern

Swatches work with any filter that represents visual attributes -- most commonly color variant options, but also materials, patterns, and textures.

Configuring Color Swatches

Mapping Values to Colors

Each product value needs to be mapped to a hex color:

1. Go to the Appearance tab on the Filters page
2. Scroll to the Swatches section
3. You will see a list of all discovered color values from your products
4. For each value, click the color picker to choose a hex color
5. Click Save

For example:

• "Red" --> #FF0000
• "Navy" --> #001F3F
• "Forest Green" --> #228B22
• "Blush" --> #DE5D83

Auto-Detection

FilterIQ attempts to auto-detect colors for common color names. When you first set up swatches, standard names like "Red", "Blue", "Black", and "White" are pre-mapped automatically. You only need to manually map custom or brand-specific color names.

Swatch Shapes

You can choose from three swatch shapes:

Shape	Description
Circle	Round swatches (default)
Square	Square swatches with sharp corners
Rounded	Square swatches with rounded corners

Select the shape that matches your store's design aesthetic. The shape applies to all swatches globally.

Image Swatches

For attributes that cannot be represented by a single color -- patterns, textures, multi-color prints -- you can upload image swatches:

1. In the Swatches section, find the value you want to assign an image to
2. Click the upload icon next to the color picker
3. Upload a small square image (recommended size: 64x64 pixels or larger)
4. The image replaces the color circle for that value

Image swatches work alongside color swatches. You can mix and match: some values use colors, others use images.

Supported formats: PNG, JPG, WebP

Unmapped Values

If a product value does not have a color or image mapping, FilterIQ falls back to displaying it as a standard text label with a neutral gray circle. This ensures all filter options remain visible even if you have not mapped every value.

To find unmapped values:

1. Open the Swatches section
2. Look for values marked with a gray indicator or "Unmapped" label
3. Assign a color or image to each one

Swatch Sizing

Swatch size is controlled by the --ssf-swatch-size CSS variable. The default is 32px. You can adjust this in your theme CSS:

:root {
  --ssf-swatch-size: 40px; /* larger swatches */
}

Available size presets in the app:

• Small -- 24px
• Medium -- 32px (default)
• Large -- 40px

Auto-Republish After Changes

When you save swatch changes, FilterIQ prompts you to republish your configuration so the changes appear on your storefront. Swatch mappings are part of your filter configuration, so they follow the same draft-and-publish workflow:

1. Make swatch changes and click Save -- changes are saved as a draft
2. Click Publish to push the updated swatches live

If you have auto-publish enabled, swatch changes are pushed to your storefront automatically when you save.

Best Practices

• Map all values -- Unmapped values degrade the visual experience. Audit your swatch list regularly as new products are added.
• Use accurate colors -- If "Navy" looks more like black in your swatch, shoppers may be confused. Match the actual product color as closely as possible.
• Keep image swatches consistent -- Use the same image size and style for all image swatches so they look uniform in the filter panel.
• Test on mobile -- Verify that swatches are large enough to tap accurately on mobile devices. The default 32px size works for most stores.

Need Help?

If you need help mapping a large number of color values, contact support@filteriq.app. We can help with bulk swatch configuration.