Keystone Documentation

Appearance

Scrollable List ​

Present customers with choices in a scrollable container for single selection.

Overview ​

Scrollable List is a selection option type that displays multiple choices in a contained, scrollable box. Customers click to select one option from the list. It's ideal for presenting many choices in a structured, space-efficient way while keeping all options easily accessible.

Use Scrollable List for:

  • Long lists of options (10+ items)
  • Country or state selections
  • Product variants with many choices
  • Size selections with extended ranges
  • Any list too long for radio buttons

Key characteristics:

  • Single selection from multiple values
  • Contained scrollable interface
  • All options accessible via scroll
  • 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., "Select Country")
Option is required for this option setIf enabled, customers must select a value before adding to cart
Hide Label from storefrontIf enabled, only the scrollable list 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)

List Items (Values) ​

Each list item can be configured with:

SettingDescription
Value NameOption text shown in the list (max 255 characters)
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 list items
  • Drag handle (⋮⋮) to reorder values
  • Chevron (⌄) to expand value settings
  • Each value can have its own pricing

Pricing Options ​

Free (Default) ​

No additional cost for this selection.

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

Add Fee ​

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

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

Example: Link "Premium" to your Premium variant 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 Scrollable List ​

  1. Navigate to Option Sets and open your option set
  2. Click Add Option
  3. Select Scrollable List from the Option Type modal
  4. Enter a Label (e.g., "Select State")
  5. Check Option is required if selection is mandatory
  6. (Optional) Click Advanced Settings to add Help Text
  7. In List Items, add your values:
    • Enter Value Name 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 ​

State Selection ​

Label: State Required: Yes Values:

  • Alabama
  • Alaska
  • Arizona
  • ... (all 50 states)

Result: Scrollable list of all states in a contained box

Extended Size Range ​

Label: Size Required: Yes Values:

  • XXS
  • XS
  • S
  • M
  • L
  • XL
  • XXL
  • 3XL
  • 4XL
  • 5XL

Result: Complete size range in scrollable container with pricing

Country Selection ​

Label: Country Required: Yes Pre-selected: United States Values:

  • United States (default)
  • Canada (+$5.00)
  • United Kingdom (+$8.00)
  • Australia (+$12.00)
  • ... (additional countries)

Result: Scrollable country list with international shipping costs

Product Variant List ​

Label: Select Model Required: Yes Values:

  • Basic Model [Free]
  • Standard Model (+$50.00)
  • Premium Model (+$100.00)
  • Professional Model (+$200.00)
  • Enterprise Model (+$500.00)

Result: Scrollable model selection with tiered pricing

Service Package ​

Label: Choose Package Required: Yes Values:

  • Starter Package [Free]
  • Growth Package (+$29.00)
  • Business Package (+$79.00)
  • Enterprise Package (+$199.00)
  • Custom Package [Link Variant: Custom Product]

Result: Service tiers in scrollable list

Customer Experience ​

Scrollable list interaction:

  1. Customer sees label and scrollable container
  2. All values displayed in bounded box
  3. Scrolls to view more options if list is long
  4. Clicks item to select
  5. Selected item highlighted with checkmark
  6. If priced, sees price next to option (e.g., "Premium (+$50.00)")

Visual feedback:

  • Selected item has checkmark (✓)
  • Selected item highlighted/colored
  • Scroll bar indicates more options
  • Clear selection state

Price display:

  • Prices shown inline: "Premium (+$50.00)"
  • Total updates in cart
  • Selection listed at checkout

Styling ​

Scrollable List inherits styling from your theme and customization settings:

Best Practices ​

Value organization:

  • Order alphabetically for easy scanning (states, countries)
  • Order by popularity for products/services
  • Use drag handles to reorder as needed
  • Logical ordering helps customers find options quickly

Use clear value names:

  • Specific: "California (CA)" vs just "CA"
  • Include prices if varied: "Express (+$10)"
  • Be consistent in naming format
  • Keep names scannable

Set appropriate defaults:

  • Pre-select most common choice
  • Consider geographic defaults (user's country)
  • Test default impact on conversions
  • Ensure default makes sense

Pricing best practices:

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

Consider scrollable list vs other types:

  • Use Scrollable List for: 10+ options, need visibility, single choice
  • Use Dropdown for: 5-15 options, save space with collapse
  • Use Radio for: 2-6 options, all immediately visible
  • Scrollable List balances visibility with space efficiency

Container height considerations:

  • List auto-adjusts but has max height
  • Long lists scroll within container
  • Test visibility of all options
  • Ensure scroll is obvious to users

Mobile optimization:

  • Scrollable lists work well on mobile
  • Touch-friendly scrolling
  • Adequate item tap targets
  • Test container height on small screens

Accessibility:

  • Scrollable lists are keyboard navigable
  • Screen reader friendly
  • Clear selection indicators
  • Test with assistive technologies