Keystone Documentation

Appearance

Image Dropdown ​

Present customers with image-based choices in a compact dropdown menu format for single selection.

Overview ​

Image Dropdown is a selection option type that displays multiple image choices in a collapsible dropdown menu. Each option includes an image and a name. Customers click to open the menu and select one image option from the list. It's ideal for visual choices where you want the space efficiency of a dropdown combined with the visual clarity of images.

Use Image Dropdown for:

  • Visual product variants (styles, finishes, materials)
  • Pattern or texture selections
  • Design or style choices
  • Material or finish options
  • Any selection where images help customers decide

Key characteristics:

  • Single selection from multiple image options
  • Space-efficient (collapsed by default)
  • Each option displays an image and name
  • Can be marked as required
  • Values can have price add-ons
  • Values can be reordered by dragging
  • Supports default selection
  • Similar to Swatch but in dropdown format

Configuration ​

Basic Settings ​

SettingDescription
LabelOption name displayed to customers (e.g., "Select Style")
Option is required for this option setIf enabled, customers must select a value before adding to cart
Hide Label from storefrontIf enabled, only the dropdown is 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)
PlaceholderText shown in dropdown before selection (e.g., "Select style")

Image Dropdown Options (Values) ​

Each image dropdown value can be configured with:

SettingDescription
Value NameOption name displayed to customers (max 255 characters)
ImageUpload image file for this option (recommended size controlled in customization settings)
Pre-selected by defaultIf enabled, this value is selected when page loads
PricingThree options: Free (default), Add fee, Link variant

Managing values:

  • Add Value button creates new image dropdown options
  • Drag handle (⋮⋮) to reorder values
  • Chevron (⌄) to expand value settings
  • Upload image for each value
  • Each value can have its own pricing

Pricing Options ​

Free (Default) ​

No additional cost for this selection.

When to use: Included choices, standard style variations, non-priced options

Add Fee ​

Manually set a specific price that's added to the base product.

Example: Premium Finish (+$15.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 value to an existing Shopify product for automatic price syncing.

Example: Link "Premium Style" to your Premium Style 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 Image Dropdown ​

  1. Navigate to Option Sets and open your option set
  2. Click Add Option
  3. Select Image Dropdown from the Option Type modal
  4. Enter a Label (e.g., "Select Style")
  5. Check Option is required if selection is mandatory
  6. (Optional) Click Advanced Settings to add Placeholder or Help Text
  7. In Image Dropdown Options, add your values:
    • Enter Value Name for each option
    • Upload Image for each option
    • Click Add Value for more options
    • Drag to reorder values
    • Expand (⌄) to set pricing or default selection
  8. Click Save in the contextual save bar

Use Cases ​

Style Selection ​

Label: Choose Style Required: Yes Placeholder: Select a style Values:

  • Modern [Image: modern.jpg] [Free]
  • Classic [Image: classic.jpg] [Free]
  • Vintage [Image: vintage.jpg] (+$10.00)
  • Premium [Image: premium.jpg] (+$20.00)

Result: Required style dropdown with images showing each style option

Material Finish ​

Label: Select Finish Required: Yes Pre-selected: Matte Values:

  • Matte [Image: matte.jpg] (default)
  • Glossy [Image: glossy.jpg] (+$5.00)
  • Metallic [Image: metallic.jpg] (+$15.00)
  • Textured [Image: textured.jpg] (+$12.00)

Result: Material finish dropdown with Matte pre-selected

Pattern Selection ​

Label: Choose Pattern Required: No Placeholder: Select pattern (optional) Values:

  • Solid [Image: solid.jpg] [Free]
  • Stripes [Image: stripes.jpg] [Free]
  • Floral [Image: floral.jpg] (+$8.00)
  • Geometric [Image: geometric.jpg] (+$8.00)

Result: Optional pattern dropdown with free and priced options

Design Variant ​

Label: Design Option Required: Yes Values:

  • Standard Design [Image: standard.jpg] [Free]
  • Custom Design A [Image: design-a.jpg] (+$25.00)
  • Custom Design B [Image: design-b.jpg] (+$25.00)
  • Premium Design [Image: premium-design.jpg] (+$50.00)

Result: Design variant dropdown with images showing each design option

Texture Option ​

Label: Texture Required: No Pre-selected: Smooth Values:

  • Smooth [Image: smooth.jpg] (default)
  • Rough [Image: rough.jpg] (+$10.00)
  • Embossed [Image: embossed.jpg] (+$15.00)

Result: Texture dropdown with Smooth pre-selected

Customer Experience ​

Image dropdown interaction:

  1. Customer sees label and dropdown field
  2. Clicks dropdown to open menu
  3. Views all available image options with names
  4. Each option displays image thumbnail and name
  5. Clicks to select one value
  6. Selected value displays in field (image + name)
  7. If priced, sees price in value name (e.g., "Premium (+$20.00)")

Visual display:

  • Images shown as thumbnails in dropdown menu
  • Value names displayed alongside images
  • Selected option shows image and name in closed dropdown
  • Clear visual representation of each choice

Price display:

  • Prices shown inline: "Premium (+$20.00)"
  • Total updates in cart
  • Each selection listed at checkout

Styling ​

Image dropdown menus inherit styling from your theme and customization settings:

  • Colors: Dropdown background, text, border colors from Colors
  • Border: Dropdown border thickness from Borders & Shapes
  • Radius: Dropdown corner radius from Borders & Shapes
  • Spacing: Option spacing from Borders & Shapes
  • Image Size: Image thumbnail size controlled in customization settings

Best Practices ​

Value organization:

  • Order values logically (standard to premium, free to paid)
  • Use drag handles to reorder easily
  • Group similar options together
  • Most popular selections near top

Use clear value names:

  • Descriptive: "Modern Style" vs "Style 1"
  • Include relevant details: "Premium Metallic Finish"
  • Show prices in value names: "Premium (+$20)"
  • Keep names concise but descriptive

Image quality:

  • Use high-quality images that clearly show the option
  • Keep consistent image dimensions for all options
  • Optimize file sizes for fast loading
  • Show pattern/texture/finish clearly
  • Test images on different devices

Set appropriate defaults:

  • Pre-select most common choice
  • Only one default per image dropdown
  • Consider "Select..." placeholder instead
  • Test default selection UX

Pricing best practices:

  • Show prices clearly in value names
  • Use Add Fee for fixed costs
  • Use Link Variant for existing products
  • Keep pricing consistent and transparent

Consider image dropdown vs other types:

  • Use Image Dropdown for: Visual choices, space-saving needed, 5+ options
  • Use Swatch (Single) for: Visual choices, always-visible preferred, fewer options
  • Use Dropdown for: Text-based options without images
  • Use Radio for: Text-based options, always-visible preferred
  • Image Dropdown combines visual clarity with space efficiency

Mobile optimization:

  • Image dropdowns work well on mobile (native select)
  • Ensure images are visible and clear on small screens
  • Test tap targets for easy selection
  • Verify image thumbnails display properly
  • Ensure pricing displays clearly

Image consistency:

  • Use consistent image dimensions across all options
  • Maintain similar lighting/background for comparison
  • Show options from similar angles
  • Ensure images accurately represent the option

Accessibility:

  • Always include descriptive value names
  • Images should complement, not replace, text
  • Test with screen readers
  • Ensure sufficient color contrast