Keystone Documentation

Appearance

Swatch (Single) ​

Present visual choices using color or image swatches for single selection.

Overview ​

Swatch (Single) is a selection option type that displays choices as visual swatches - either colors or images. Customers click a swatch to select one option. It's ideal for visual decisions like colors, patterns, materials, or styles where seeing the option is more helpful than reading text.

Use Swatch (Single) for:

  • Color selections
  • Fabric or material patterns
  • Texture options
  • Style variations
  • Visual product variants

Key characteristics:

  • Single selection from multiple swatches
  • Visual representation (color or image)
  • Color swatches support multi-tone (up to 4 colors)
  • Image swatches show uploaded images
  • Can be marked as required
  • Values can have price add-ons
  • Values can be reordered by dragging
  • Supports default selection

Configuration ​

Basic Settings ​

SettingDescription
LabelOption name displayed to customers (e.g., "Color")
Option is required for this option setIf enabled, customers must select a 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 selected 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 premium options.

Example: Premium Color (+$10.00)

How it works:

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

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 variant for automatic price syncing.

Example: Link "Red" swatch to Red product variant

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 (Single) ​

  1. Navigate to Option Sets and open your option set
  2. Click Add Option
  3. Select Swatch (Single) from the Option Type modal
  4. Enter a Label (e.g., "Color")
  5. Check Option is required if 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 default selection
  8. Click Save in the contextual save bar

Use Cases ​

Color Selection ​

Label: Choose Color Required: Yes Swatches:

  • Red [Color: #FF0000]
  • Blue [Color: #0000FF]
  • Green [Color: #00FF00]
  • Black [Color: #000000]
  • Two-Tone Blue/White [Colors: #0000FF, #FFFFFF]

Result: Color swatches with single and multi-tone options

Fabric Pattern ​

Label: Select Pattern Required: Yes Swatches:

  • Solid [Color: #CCCCCC]
  • Stripes [Image: stripes.jpg]
  • Polka Dots [Image: dots.jpg]
  • Floral [Image: floral.jpg]

Result: Mix of color and image swatches for patterns

Material Finish ​

Label: Finish Required: No Swatches:

  • Matte Black [Color: #1A1A1A] [Free]
  • Glossy White [Color: #FFFFFF] [Free]
  • Metallic Silver [Image: silver.jpg] (+$15.00)
  • Gold [Image: gold.jpg] (+$25.00)

Result: Material swatches with premium finish pricing

Wood Stain ​

Label: Wood Stain Required: Yes Pre-selected: Natural Swatches:

  • Natural [Image: natural-wood.jpg] (default)
  • Dark Walnut [Image: walnut.jpg] (+$20.00)
  • Espresso [Image: espresso.jpg] (+$20.00)
  • White Wash [Image: whitewash.jpg] (+$15.00)

Result: Wood stain image swatches with Natural pre-selected

Customer Experience ​

Swatch interaction:

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

Visual display:

  • Color swatches show as solid or multi-tone
  • Image swatches show uploaded images
  • Selected swatch has visual indicator
  • Clear clickable appearance

Price display:

  • Prices shown near swatches
  • Total updates in cart
  • Selection 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
  • Limit to 8-12 swatches for best UX

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

Set appropriate defaults:

  • Pre-select most popular option
  • Only one default per swatch group
  • Test impact on conversions
  • Ensure default makes sense

Pricing best practices:

  • Charge for premium finishes/materials
  • Standard colors typically free
  • Use Add Fee for fixed premiums
  • Use Link Variant for variant products

Consider swatch (single) vs other types:

  • Use Swatch (Single) for: Visual choices, colors, patterns, materials
  • Use Dropdown/Radio for: Text-based options
  • Use Swatch (Multi) for: Multiple color selections
  • Swatches make visual decisions easier

Mobile optimization:

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

Accessibility:

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