Keystone Documentation

Appearance

Slider ​

Let customers pick a number by dragging a handle along a track — bounded by a lowest and highest value, snapping to a step increment, with an optional unit suffix.

Overview ​

Slider is an input option type that renders a numeric range control. Instead of typing into a field, the customer drags the handle (or types into an optional number box) to choose a value between the bounds you configure.

Use Slider for:

  • Measurements and dimensions (length, width, height)
  • Weights and volumes
  • Quantities within a known range
  • Percentages, intensities, or ratings
  • Any numeric choice where the valid range is fixed and worth showing

Key characteristics:

  • Range configured by the merchant: lowest, highest, step, default, and unit
  • The handle snaps to the step increment — every reachable value is on the grid
  • Always has a value, so there's no Required toggle (see the note below)
  • Cart line shows the chosen number with its unit — e.g. 42 cm
  • Fully stylable via per-type templates (see Slider Styling)

No "Required" checkbox

The handle can never be "unset" — a Slider always submits a number. Making it required would be meaningless, so the Option is required for this option set checkbox is hidden for this type, the same way it is for the display-only types (Spacing, Divider, Heading, Accordion, Tabs).

Configuration ​

Basic Settings ​

SettingDescription
LabelOption name displayed to customers (e.g., "Length")
Hide Label from storefrontIf enabled, only the slider is shown (label is hidden)

Slider Settings ​

These five fields live on the option's Slider card, below the basic settings.

SettingOptions (default)What it controls
Lowest valuenumber (0)The smallest number a customer can choose. Required
Highest valuenumber (100)The largest number a customer can choose. Required, and must be greater than Lowest
Stepnumber > 0 (1)The increment between values, e.g. 1 or 0.5. Must be positive
Default valuenumber (0)The value the slider starts on. Must be within the range and land on a step
Unittext, max 5 characters (empty)Optional text shown after the value on the storefront and in the cart, e.g. cm or kg

All four numeric fields accept negatives and decimals.

Highest must land on a step

Lowest, Highest and Default all have to sit on the step grid (Lowest + n × Step). A range like 0–10 with step 3 is rejected on save, because 10 isn't reachable — the stops are 0, 3, 6, 9. Either change Highest to 9 or change Step to something that divides the span evenly.

This is stricter than it looks at first glance, but it's deliberate: it guarantees every number the customer can see on the track is a number they can actually select.

Advanced Settings ​

SettingDescription
Internal LabelAdmin-only identifier (replaces label in the options list)
Help TextAdditional guidance shown to customers (based on display mode)
CSS classYour own class name(s) on this option's container — see CSS Class & CSS ID
CSS IDYour own HTML ID on this option's container — see CSS Class & CSS ID

Validation ​

Saving is blocked, with a red error on the offending field, when:

MessageCause
Enter a lowest value.Lowest value is empty
Enter a highest value.Highest value is empty
Step must be greater than 0.Step is zero, negative, or empty
Highest value must be greater than the lowest value.Highest ≤ Lowest
This value isn't reachable with the current configuration. Adjust the lowest value, highest value, or step, so the highest lands on a step.Highest is off the step grid
Default value must be between the lowest and highest values.Default is outside the range
This default isn't reachable with the current configuration. Set it to a value on the step, or adjust the lowest value or step so it lands on one.Default is inside the range but off the step grid
Value must be between -2,147,483,647 and 2,147,483,647.Lowest, Highest, or Step exceeds the magnitude cap

Why the magnitude cap?

A huge Highest with a small Step describes billions of stops. The cap keeps the configuration in territory a real slider can render — anything beyond it has no practical use and used to freeze the editor.

How to Add a Slider ​

  1. Navigate to Option Sets and open your option set
  2. Click Add Option
  3. Select Slider from the Option Type modal (it's under the Input category)
  4. Enter a Label (e.g., "Length")
  5. On the Slider card, set Lowest value, Highest value, Step, Default value, and (optionally) a Unit
  6. (Optional) Click Advanced Settings to add an Internal Label or Help Text
  7. (Optional) Expand Style settings to assign a Slider template
  8. Click Save in the contextual save bar

In the options list, a saved Slider shows its configuration as two chips — the range (e.g. 0–100 cm) and the increment (e.g. Step 5).

On the Storefront ​

How customers interact with it:

  • Drag the handle, or click anywhere on the track to jump the handle there
  • Keyboard: arrow keys move by one step, Page Up / Page Down move by ten steps, Home jumps to the lowest value and End to the highest
  • Number box (when the Value Display setting is set to it): type a value and press Enter or click away. Out-of-range or off-step entries snap to the nearest valid value rather than being rejected

Every displayed value — the tooltip, the min/max labels, the step labels, the cart line — automatically composes as {value} {unit}. You never type the unit twice.

Changing the range later re-seeds existing sessions

The slider follows its configured default until the customer moves the handle. If you change Default value while a customer hasn't touched the control, they see the new default.

Cart Properties ​

The chosen number is submitted as a normal line-item property named after the option's label, with the unit appended:

  • Option Length, value 42, unit cm → cart line property Length: 42 cm
  • Option Length, value 42, no unit → cart line property Length: 42

Edit in Cart reads the number back out of that property, so returning to the product page restores the customer's chosen value rather than resetting to the default.

Conditions ​

A Slider can be used as the source of a condition, with four comparators:

ComparatorMeaning
isThe chosen value equals this number
is notThe chosen value is anything but this number
is more thanThe chosen value is greater than this number
is less thanThe chosen value is less than this number

Comparisons are numeric, not text — 10 is correctly treated as greater than 9.

No "is empty" / "is not empty"

Those two comparators aren't offered for a Slider. Since the control always has a value, is empty would never match and is not empty would always match — neither builds a useful rule.

The condition's value box accepts negatives and decimals, and is checked against the slider's configuration:

  • This isn't a selectable slider value — it must be within the range and land on a step. The condition could never match. — for is / is not, when the number isn't a reachable stop
  • This threshold is outside the slider's range, so the condition always (or never) matches. Choose a value within the range. — for is more than / is less than, when the threshold sits outside the range

Styling ​

Slider has its own dedicated styling — track, handle, ticks, labels, and the current-value display are all configurable via named templates, the same way Accordion, Checkbox, Radio, Swatches, Tabs, and File Upload work.

See Slider Styling for the full settings reference, and Sandbox & Live Preview for how to preview a range while you style.

Use Cases ​

Custom Length ​

Label: Length Lowest / Highest: 10 / 200 Step: 5 Default: 50 Unit: cm

Result: Customers pick a length in 5 cm increments; the cart line reads "Length: 50 cm"

Engraving Font Size ​

Label: Font Size Lowest / Highest: 8 / 24 Step: 2 Default: 12 Unit: pt

Result: A tight, well-labelled range that suits the Stepped style with step labels turned on

Fill Percentage ​

Label: Fill Level Lowest / Highest: 0 / 100 Step: 10 Default: 50 Unit: %

Result: Eleven evenly spaced stops — ideal for the Stepped preset, which draws a tick at each one

Fine Adjustment ​

Label: Thickness Lowest / Highest: 0 / 5 Step: 0.5 Default: 2.5 Unit: mm

Result: Decimal steps for precise sizing, with the number box enabled so customers can type an exact figure

Best Practices ​

Keep the range meaningful:

  • Set Lowest and Highest to what you can actually produce, not an arbitrary 0–100
  • Pick a Step that divides the span evenly, so the Highest value is reachable
  • Use a Default that represents your most common order

Always set a Unit when there is one:

  • It appears on the handle tooltip, the end labels, and the cart line
  • Keep it short — the field caps at 5 characters
  • Put the unit in the Unit field, not in the Label, so it follows the value everywhere

Choose the right value display:

  • Tooltip keeps the widget compact and reads well for coarse ranges
  • Number box is better when customers need to enter an exact figure
  • See Current Value

Mind the step count:

  • Very fine steps over a wide range produce hundreds of stops; the Stepped preset thins its ticks and labels so they stay readable
  • If you want a tick per value, keep the number of stops small (roughly 20 or fewer)

Guide with Help Text:

  • Explain what the number means and how it's used
  • Mention tolerances or rounding if they apply

Troubleshooting ​

Can't save — "This value isn't reachable": Highest doesn't land on a step. Adjust Highest or Step so (Highest − Lowest) divides evenly by Step

Can't save — "This default isn't reachable": Default is on the right side of the range but between two stops. Move it onto a stop

The handle won't reach the highest value: The configuration is off-grid; the top reachable value is the largest stop at or below Highest

No tick marks on a Stepped slider: The range has too many stops, so ticks are thinned. Increase Step or narrow the range — see Slider Style

Step labels overlap or some are missing: Labels are thinned to fit the measured track width. Shorten the Unit, reduce the font size, or use fewer stops