Keystone Documentation

Appearance

Buttons (Multi) ​

Allow customers to select multiple options from a list using button-style selections.

Overview ​

Buttons (Multi) is a selection option type that displays multiple choices as always-visible buttons. Customers can click multiple buttons to select several options simultaneously. Buttons are arranged horizontally and automatically wrap to the next row when horizontal space is full. It's ideal when customers should be able to choose more than one item with a modern button interface.

Use Buttons (Multi) for:

  • Add-ons or extras (gift wrapping, rush processing)
  • Multiple features or services
  • Toppings or ingredients
  • Accessory bundles
  • Multiple upgrades
  • Any scenario requiring multiple selections with button interface

Key characteristics:

  • Multiple selections allowed
  • All options always visible
  • Values displayed as buttons
  • Buttons arranged horizontally, wrap to next row when space is full
  • Each button independent
  • 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 (multiple buttons can be pre-selected)
  • Functionally similar to Checkbox (Multi) but with button appearance

Configuration ​

Basic Settings ​

SettingDescription
LabelOption name displayed to customers (e.g., "Select Add-Ons")
Option is required for this option setIf enabled, customers must select at least one button before adding to cart
Hide Label from storefrontIf enabled, only the buttons 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)

Button Options (Values) ​

Each button value can be configured with:

SettingDescription
Value NameOption text shown on the button (max 255 characters)
Pre-selected by defaultIf enabled, this button is selected when page loads
PricingThree options: Free (default), Add fee, Link variant

Managing values:

  • Add Value button creates new button options
  • Drag handle (⋮⋮) to reorder values
  • Chevron (⌄) to expand value settings
  • Each value can have its own pricing
  • Multiple buttons can be pre-selected

Pricing Options ​

Free (Default) ​

No additional cost for this selection.

When to use: Included choices, informational selections, non-priced options

Add Fee ​

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

Example: Gift Wrapping (+$5.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 "Protective Case" to your Case 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 Buttons (Multi) ​

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

Use Cases ​

Add-On Services ​

Label: Add Extra Services Required: No Values:

  • Gift wrapping (+$5.00) [Add Fee: $5]
  • Express processing (+$10.00) [Add Fee: $10]
  • Personal note card [Free]

Result: Customers can select multiple add-on services using buttons

Toppings Selection ​

Label: Choose Your Toppings Required: No Pre-selected: Cheese (first value) Values:

  • Cheese [Free] (default)
  • Pepperoni (+$2.00)
  • Mushrooms (+$1.50)
  • Extra sauce [Free]

Result: Multiple topping selection buttons with Cheese pre-selected

Product Accessories ​

Label: Recommended Accessories Required: No Values:

  • Protective Case (+$15.00) [Link Variant: Case Product]
  • Screen Protector (+$8.00) [Link Variant: Protector Product]
  • Charging Cable (+$12.00) [Link Variant: Cable Product]

Result: Multiple accessories with linked product pricing, displayed as buttons

Features Bundle ​

Label: Include These Features Required: Yes (at least one) Values:

  • Feature A [Free]
  • Feature B (+$5.00)
  • Feature C (+$10.00)
  • Feature D (+$15.00)

Result: Required to select at least one feature from button options

Upgrades Package ​

Label: Select Upgrades Required: No Values:

  • Premium finish (+$20.00)
  • Extended warranty (+$50.00)
  • Priority support (+$30.00)
  • Free gift [Free]

Result: Optional multiple upgrades selection with button interface

Customer Experience ​

Button interaction:

  1. Customer sees label and all button options
  2. All choices visible immediately (no clicking to expand)
  3. Buttons arranged horizontally in rows
  4. Buttons wrap to next row when horizontal space is full
  5. Clicks buttons to select (multiple allowed)
  6. Selected buttons show active/highlighted state
  7. Can click buttons again to deselect
  8. Multiple buttons can be selected simultaneously
  9. If priced, sees price on each button (e.g., "Gift wrapping (+$5.00)")

Visual display:

  • Buttons displayed side-by-side horizontally
  • Buttons automatically wrap to next row when space fills
  • Selected buttons show active/highlighted state
  • Multiple buttons can be selected at once
  • Clear button appearance with text labels
  • Modern, clickable button interface

Price display:

  • Prices shown on buttons: "Express (+$10.00)"
  • Multiple selections add up in cart
  • Each selected item listed at checkout

Styling ​

Buttons inherit styling from your theme and customization settings:

Best Practices ​

Value organization:

  • Order by popularity or importance
  • Use drag handles to reorder easily
  • Group related options together
  • Consider how buttons will wrap on different screen sizes
  • Consider limiting to 5-10 options

Use clear value names:

  • Descriptive: "Gift wrapping with ribbon" vs "Wrapping"
  • Include details: "Express processing (2 days)"
  • Show prices clearly: "Premium finish (+$20)"
  • Keep names concise to fit button width
  • Consider button text length for wrapping

Pre-selection strategy:

  • Pre-select recommended or popular items
  • Can pre-select multiple buttons
  • Test impact on conversions
  • Consider upsell opportunities

Pricing best practices:

  • Show prices clearly on each button
  • Multiple prices add up transparently
  • Use Add Fee for fixed costs
  • Use Link Variant for existing products

Consider buttons (multi) vs other types:

  • Use Buttons (Multi) for: Multiple selections, modern button interface, add-ons
  • Use Checkbox (Multi) for: Multiple selections, traditional checkbox interface
  • Use Buttons (Single) for: Single choice only
  • Use Radio for: Single choice only
  • Buttons provide modern, prominent interface for multiple selections

Mobile optimization:

  • Buttons work well on mobile
  • Ensure adequate tap target size
  • Buttons wrap naturally on small screens
  • Verify spacing between buttons
  • Test that price text displays clearly
  • Consider button width on mobile devices

Button layout:

  • Buttons arrange horizontally automatically
  • Wrap to next row when horizontal space fills
  • Consider number of buttons and screen width
  • Test layout on different screen sizes
  • Ensure buttons are easily tappable

Communicate requirements:

  • "Required" means at least one button must be selected
  • Use Help Text to clarify selection rules
  • Test required validation
  • Provide clear error messages

Button text length:

  • Keep button text concise
  • Long text may cause awkward wrapping
  • Test with your actual button labels
  • Consider abbreviation for long names

Limit option count:

  • Works well with 3-10 options
  • More options create multiple rows
  • Consider screen space and scrolling
  • Test with your specific button count