Keystone Documentation

Appearance

Swatch (Multi) ​

Allow customers to select multiple visual choices using color or image swatches.

Overview ​

Swatch (Multi) is a selection option type that displays choices as visual swatches - either colors or images. Customers can click multiple swatches to select several options simultaneously. It's ideal for visual decisions where customers should choose more than one color, pattern, or material.

Use Swatch (Multi) for:

  • Multiple color selections
  • Combination patterns or materials
  • Accessory color bundles
  • Multi-color customizations
  • Style combination options

Key characteristics:

  • Multiple selections allowed
  • Visual representation (color or image)
  • Color swatches support multi-tone (up to 4 colors)
  • Image swatches show uploaded images
  • Can be marked as required (at least one must be selected)
  • Values can have price add-ons
  • Values can be reordered by dragging
  • Supports pre-selection of multiple swatches

Configuration ​

Basic Settings ​

SettingDescription
LabelOption name displayed to customers (e.g., "Select Colors")
Option is required for this option setIf enabled, customers must select at least one swatch before adding to cart
Hide Label from storefrontIf enabled, only the swatches are shown (label is hidden)

Advanced Settings ​

SettingDescription
Internal LabelAdmin-only identifier (replaces label in options list)
Help TextAdditional guidance shown to customers (based on display mode)

Swatch Options (Values) ​

Each swatch can be configured with:

SettingDescription
Value NameOption name (max 255 characters) - shown as tooltip/label
Pre-selected by defaultIf enabled, this swatch is checked when page loads
Swatch TypeColor or Image
PricingThree options: Free (default), Add fee, Link variant

Swatch Type: Color

  • Single color: Add one color with hex code
  • Multi-tone: Add up to 4 colors for split effect
  • Click Add Color to add additional colors (max 4)

Swatch Type: Image

  • Upload one image per swatch
  • Recommended size controlled in customization settings
  • Common formats: JPG, PNG

Managing swatches:

  • Add Value button creates new swatches
  • Drag handle (⋮⋮) to reorder swatches
  • Chevron (⌄) to expand swatch settings
  • Toggle between Color/Image for each swatch

Pricing Options ​

Free (Default) ​

No additional cost for this selection.

When to use: Standard color/style options included in base price

Add Fee ​

Manually set a specific price for each selected swatch.

Example: Each Color (+$5.00)

How it works:

  • You enter the price amount
  • App creates a hidden Shopify product automatically
  • Price is added to cart for each selected swatch

Hidden Products

The app creates hidden products for Add Fee pricing. Do not edit or delete these products in Shopify.

Connect the swatch to an existing Shopify product for automatic price syncing.

Example: Link each color to corresponding product

How it works:

  • You select an existing product
  • Price automatically syncs with that product
  • Updates when you change the linked product price

How to Add Swatch (Multi) ​

  1. Navigate to Option Sets and open your option set
  2. Click Add Option
  3. Select Swatch (Multi) from the Option Type modal
  4. Enter a Label (e.g., "Select Colors")
  5. Check Option is required if at least one selection is mandatory
  6. (Optional) Click Advanced Settings to add Help Text
  7. In Swatch Options, add your swatches:
    • Enter Value Name for each swatch
    • Choose Color or Image tab
    • For Color: Enter hex code(s), click Add Color for multi-tone (up to 4)
    • For Image: Upload image file
    • Click Add Value for more swatches
    • Drag to reorder swatches
    • Expand (⌄) to set pricing or pre-selection
  8. Click Save in the contextual save bar

Use Cases ​

Thread Color Selection ​

Label: Choose Thread Colors Required: Yes (at least one) Swatches:

  • Red [Color: #FF0000] (+$2.00)
  • Blue [Color: #0000FF] (+$2.00)
  • Green [Color: #00FF00] (+$2.00)
  • Yellow [Color: #FFFF00] (+$2.00)
  • Black [Color: #000000] (+$2.00)

Result: Multiple color selection with per-color pricing

Accent Color Combination ​

Label: Select Accent Colors (Choose up to 3) Required: No Swatches:

  • Gold [Image: gold.jpg] [Free]
  • Silver [Image: silver.jpg] [Free]
  • Rose Gold [Image: rose-gold.jpg] (+$5.00)
  • Bronze [Image: bronze.jpg] (+$5.00)

Result: Multiple metallic accent selections

Fabric Bundle ​

Label: Select Fabric Swatches Required: Yes (at least one) Pre-selected: Cotton, Linen Swatches:

  • Cotton [Image: cotton.jpg] [Free] (default)
  • Linen [Image: linen.jpg] [Free] (default)
  • Silk [Image: silk.jpg] (+$10.00)
  • Velvet [Image: velvet.jpg] (+$15.00)

Result: Multiple fabric selections with common ones pre-selected

Piping Color Options ​

Label: Add Piping Colors Required: No Swatches:

  • Navy [Color: #000080]
  • White [Color: #FFFFFF]
  • Red [Color: #FF0000]
  • Gold [Color: #FFD700] (+$3.00)

Result: Optional multiple piping color selections

Multi-Tone Combinations ​

Label: Select Color Schemes Required: Yes Swatches:

  • Sunset Blend [Colors: #FF6B6B, #FFA500, #FFD700] (3-tone)
  • Ocean Mix [Colors: #0077BE, #00C9FF] (2-tone)
  • Forest Combo [Colors: #228B22, #90EE90, #006400] (3-tone)
  • Monochrome [Color: #000000]

Result: Multiple solid color selections

Customer Experience ​

Swatch interaction:

  1. Customer sees label and visual swatches
  2. All swatches displayed as squares/circles
  3. Clicks swatches to select (multiple allowed)
  4. Selected swatches highlighted with border/checkmark
  5. Can select/deselect any combination
  6. Hover shows value name as tooltip
  7. If priced, sees price below or near each swatch

Visual feedback:

  • Selected swatches have checkmarks (✓)
  • Selected swatches highlighted/bordered
  • Multiple selections clearly indicated
  • Easy to add/remove selections

Price display:

  • Prices shown near swatches
  • Multiple prices add up in cart
  • Each selected swatch listed at checkout

Styling ​

Swatches inherit size and styling from customization settings:

Best Practices ​

Swatch organization:

  • Order by popularity or color spectrum
  • Use drag handles to reorder easily
  • Group similar colors/styles together
  • Consider limiting selection quantity in Help Text

Use clear value names:

  • Descriptive: "Navy Blue" vs "Blue"
  • Names appear on hover/tooltip
  • Important for accessibility
  • Used in cart/checkout

Color swatch tips:

  • Use accurate hex codes
  • Multi-tone for split colors
  • Test colors on different screens
  • Consider color blindness accessibility

Image swatch tips:

  • Use high-quality images
  • Keep consistent image dimensions
  • Show pattern/texture clearly
  • Optimize file sizes for loading speed

Pre-selection strategy:

  • Pre-select popular combinations
  • Can pre-select multiple swatches
  • Test impact on conversions
  • Consider upsell opportunities

Pricing best practices:

  • Per-swatch pricing adds up transparently
  • Show prices clearly near each swatch
  • Use Add Fee for fixed costs per selection
  • Use Link Variant for variant products

Consider swatch (multi) vs other types:

  • Use Swatch (Multi) for: Multiple visual selections, color combinations
  • Use Swatch (Single) for: One visual choice only
  • Use Checkbox (Multi) for: Text-based multiple selections
  • Multi swatches best for visual combination choices

Mobile optimization:

  • Swatches work well on mobile
  • Ensure adequate tap target size
  • Test swatch size on small screens
  • Verify images load quickly

Communicate selection limits:

  • Use Help Text for quantity guidance ("Choose up to 3")
  • "Required" means at least one must be selected
  • Test selection experience
  • Provide clear feedback

Accessibility:

  • Always include value names
  • Test with screen readers
  • Provide text alternatives
  • Consider color contrast