> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digifist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Swatches

> Configure color swatch display for product variants

Swatch settings transform product variant options from text dropdowns into visual color swatches, creating a more engaging shopping experience. Instead of reading "Navy Blue" in a list, customers see actual color circles they can click. Well-configured swatches increase variant product engagement by 25-40% and reduce decision fatigue.

## What this controls

Swatch settings determine how product variant options are displayed as visual color swatches instead of dropdown menus. This creates a more engaging shopping experience by allowing customers to see color options at a glance.

<Tip>Color swatches increase engagement with variant products by 25-40% compared to text-based dropdowns, especially in fashion and home decor categories.</Tip>

## How it works

Sahara's swatch system automatically converts specified variant options into clickable visual swatches. Instead of a dropdown menu showing "Red", "Blue", "Green", customers see actual colored circles or squares they can click.

The system works by:

1. **Option Name Matching:** You specify which option name (e.g., "Color") should display as swatches
2. **Automatic Color Detection:** The theme matches variant values to built-in color definitions
3. **Visual Display:** Swatches appear on product cards and product pages
4. **Custom Swatch Support:** Upload custom swatch images for unique colors or patterns

<Note>Swatches work best with standardized color names. Use "Navy Blue" consistently rather than mixing "Navy", "Navy Blue", and "Dark Blue".</Note>

## Getting started

<Steps>
  <Step title="Open Theme Customizer">
    From Shopify admin → **Online Store** → **Themes** → **Customize**
  </Step>

  <Step title="Access swatch settings">
    Click **Theme settings** → Select **Swatches**
  </Step>

  <Step title="Specify option name">
    Enter the exact variant option name to display as swatches (e.g., "Color" or "Colour")
  </Step>

  <Step title="Test with products">
    Preview products with color variants to verify swatch display
  </Step>

  <Step title="Optional: Add custom swatches">
    Upload custom swatch images in theme files for unique colors/patterns
  </Step>
</Steps>

## Location

**Path:** Theme settings → Swatches

## Settings

<Tabs>
  <Tab title="Swatch Option">
    **Swatches option name**: Enter the exact name of the product option that should display as color swatches.

    **Default:** `Color`

    **Common values:**

    * `Color` (English)
    * `Colour` (British English)
    * `Renk` (Turkish)
    * `Farbe` (German)
    * `Couleur` (French)

    <Warning>The option name is case-sensitive and must match exactly how it appears in your product variants. If some products use "color" and others use "Color", swatches will only work for one variant.</Warning>

    **How it works:**

    * The theme searches your products for this exact option name
    * When found, it converts that option's values into visual swatches
    * Other variant options continue displaying as dropdowns or buttons
  </Tab>

  <Tab title="Color Recognition">
    **Built-in colors:** Sahara includes automatic color recognition for common color names:

    * Basic colors (Red, Blue, Green, Yellow, etc.)
    * Extended palette (Navy, Burgundy, Teal, Coral, etc.)
    * Neutrals (Black, White, Gray, Beige, Cream, etc.)
    * Variants (Light Blue, Dark Green, etc.)

    **Pattern matching:**

    * "Navy Blue" → Blue swatch with darker shade
    * "Light Gray" → Gray swatch with lighter shade
    * "Forest Green" → Green swatch with darker shade

    <Tip>Use standard color names when possible for automatic swatch generation. Reserve custom swatches for unique colors, patterns, or textures.</Tip>
  </Tab>

  <Tab title="Custom Swatches">
    For colors not recognized automatically or for pattern/texture variants, you can add custom swatch images.

    **How to add custom swatches:**

    1. Create a swatch image (minimum 50x50px, square format)
    2. Name it exactly as your variant value (e.g., `burgundy.png`, `striped.jpg`)
    3. Upload to your theme's `assets` folder or Files section
    4. The theme automatically uses custom swatches when available

    **Best practices:**

    * Use consistent image dimensions (recommended: 50x50px or 100x100px)
    * Keep file sizes small (\<10KB per swatch)
    * Use PNG for solid colors, JPG for patterns/textures
    * Name files in lowercase with hyphens for spaces (e.g., `navy-blue.png`)

    <Note>Custom swatches override automatic color detection. If you upload "red.png", the theme uses your image instead of the built-in red color.</Note>
  </Tab>
</Tabs>

## Use cases

<CardGroup cols={2}>
  <Card title="Fashion & Apparel" icon="shirt">
    Display clothing colors as swatches on product cards. Customers see all color options without opening product pages.

    **Example:** T-shirt available in Black, White, Navy, Red → 4 circular swatches
  </Card>

  <Card title="Home Decor" icon="couch">
    Show furniture and home goods in different fabric colors or finishes.

    **Example:** Sofa in Beige, Gray, Navy → 3 swatches showing fabric colors
  </Card>

  <Card title="Beauty & Cosmetics" icon="paintbrush">
    Display makeup colors or product shades visually for easier selection.

    **Example:** Lipstick in nude, pink, red → Color-accurate swatches
  </Card>

  <Card title="Pattern Variants" icon="pattern">
    Use custom swatch images for patterns, textures, or complex materials.

    **Example:** Rug in Striped, Geometric, Floral → Custom pattern images
  </Card>
</CardGroup>

## Best practices

<CardGroup cols={2}>
  <Card title="Use consistent color naming" icon="tags">
    Standardize color names across all products. Always use "Navy Blue" instead of mixing "Navy", "Navy Blue", "Dark Blue" for same color. Create a color naming guide. This ensures swatches work reliably and customers can filter by color accurately.
  </Card>

  <Card title="Limit swatch count" icon="circle-dot">
    Keep visible swatches to 5-8 colors on product cards for clarity. Show most popular colors first, use "+3 more" indicator for additional colors, full color range appears on product page. Too many swatches on cards creates visual clutter and decision paralysis.
  </Card>

  <Card title="Test swatch visibility" icon="eye">
    Ensure swatches are large enough to distinguish colors (minimum 32px diameter), have adequate spacing (8-12px gap), include border for white/light swatches on light backgrounds, and work on mobile devices (minimum 44px touch target).
  </Card>

  <Card title="Combine with variant images" icon="images">
    For best results, pair swatches with variant-specific images. Each color variant has its own product image, clicking swatch shows that color's image, creates "try before you buy" experience. This combination reduces returns and increases customer confidence.
  </Card>

  <Card title="Match swatch colors accurately" icon="droplet">
    Swatch colors should accurately represent actual products. Use custom swatches for precise color matching, test swatches against product photos, consider color calibration across devices. Mismatched swatches lead to customer disappointment and returns.
  </Card>

  <Card title="Keep option name simple" icon="input-text">
    Use single-word option names when possible. "Color" is simple and clear, "Product Color" works but is verbose, "Choose Color" is unnecessarily wordy. Short names work better in theme templates and reduce layout issues.
  </Card>
</CardGroup>

## Common issues

<Warning>
  **Swatches not appearing?** Check these common issues:

  1. **Option name mismatch:** Verify the exact option name in your products matches the setting (case-sensitive)
  2. **Unrecognized color names:** Use standard color names or add custom swatch images
  3. **Cache issues:** Clear browser cache or use incognito mode to see changes
  4. **Product has no variants:** Swatches only appear for products with the specified option
</Warning>

<Tip>
  **Pro tip:** Create a product template specifically for swatched products. This ensures consistent display and allows custom layouts optimized for color-focused shopping.
</Tip>

## Technical notes

* Swatch setting applies globally to all product displays (cards, pages, quick view)
* Multiple option names can be styled as swatches by entering comma-separated values
* Swatch images are loaded lazily for performance optimization
* The theme respects inventory levels - out-of-stock swatches appear grayed/crossed out
* Swatches support accessibility with proper ARIA labels and keyboard navigation

## Related guides

<CardGroup cols={3}>
  <Card title="Products" icon="box" href="/themes/sahara/theme-settings/products">
    Configure overall product display and card settings
  </Card>

  <Card title="Colors" icon="palette" href="/themes/sahara/theme-settings/colors">
    Set up theme-wide color schemes
  </Card>

  <Card title="Product Page" icon="file" href="/themes/sahara/products/product-page">
    Customize product page layout and features
  </Card>
</CardGroup>