Fields 12 fields you can set on a stepper control. Every control also takes the shared fields (id, position, span, sync, action).
Fields Field Type Default What it does Motion animationchoice one of 5 — How the number changes when it steps
Sets how the readout animates between values, from an instant swap to a soft glide.
smooth an even natural transition snappy a quick firm change bouncy overshoots slightly then settles gentle a slow soft transition instant changes with no animation Lowest value minnumber 0The count never goes below this
Sets the lowest number reachable; the minus button dims there.
Highest value maxnumber 100The count never goes above this
Sets the highest number reachable; the plus button dims there.
Step size stepnumber 1How much each tap adds or removes
Changes the number by this amount per tap, in the control's own units; 0 or less acts as 1.
Repeat while held repeatOnHoldon / off false (off) Keeps stepping while you hold a button
On, holding plus or minus repeats the step until you let go; off, each tap is one step.
Wrap around at the ends wrapson / off false (off) Loops around instead of stopping
On, plus at the highest value jumps to the lowest and minus at the lowest jumps to the highest; off, the buttons dim at the ends.
Hide the number hideValueon / off false (off) Takes the number off the control
Removes the visible number between the buttons; the title and buttons stay and VoiceOver still reads the value.
Title labeltext — The name shown on the control
Writes this text as the title of the stepper.
Symbol icontext — A small picture beside the number
Shows this SF Symbol before the value.
Number format formatValuechoice one of 18 decimalHow the number is written
Changes the readout from a plain number such as 72 to a time like 3:45 or a percentage like 80%; suffix:text adds a unit.
{ value: decimal since: next } { value: percent since: next } { value: time since: next } { value: duration since: next } { value: bytes since: next } { value: bytesKB since: next } { value: bps since: next } { value: relative since: next } { value: none since: next } Starting value defaultValuenumber — Where the count starts
Shows this number (within lowest to highest) until something else sets it.
Vibration on tap hapticchoice one of 7 lightThe buzz you feel on each tap
Shows a pill naming the change with an Undo button for 3 seconds after you step.
light default a soft tap medium a firmer tap heavy a strong thump success a pleasant double tap warning a cautionary buzz error a sharp failure buzz selection a tiny tick like a picker
Theme fields Restyle one control by setting these in its theme object; a layout's theme sets them for every control.
Theme fields Field Type Default What it does Number text size theme.valueFontSizenumber 8–28 step 1 14How big the number is
Sets the number text size from 8 to 28 points.
Button color theme.buttonColorcolor #667eeaThe color of the plus and minus buttons
Fills both round buttons with this color.
Button roundness theme.buttonRadiusnumber 0–30 pt step 1 8How round the buttons are
Rounds the button corners from 0 (square) to 30 points.
Button size theme.buttonSizenumber 12–50 pt step 1 32How big the buttons are
Sets the button diameter from 12 to 50 points.
Symbol color theme.iconColorcolor #FFFFFFThe softer text color
Colors the secondary text such as the title.
Emits and receives What this control sends when you use it, and what it can show or follow when data arrives.
Emits Emits Sends When Type What it sends When you tap plus or minus valuechange number the number it now shows
Each step sends once; a step that changes nothing, such as plus at the highest value, sends nothing
Example: 5
Receives Receives Takes From Type What it does value followhub, mqtt, http, store, default number a number to show; text that reads as a number works too
the number rolls to it, held between the lowest and highest value; your next step starts from there
Example: 5
Sample The placeholder value the editor shows before real data arrives.
Examples 7 examples, each one a control you can paste into a layout.
Shows the plain readout: a titled counter with an SF Symbol before the number that starts at 3 and moves one at a time between 0 and 10.
JSON 5 lines Copy {
"type": "stepper", "id": "guests", "position": [0, 0],
"label": "Guests", "icon": "person.2", "min": 0, "max": 10, "step": 1,
"defaultValue": 3
}Open in CAR-TER ↗
Rendered by the app Light Dark Cycles through presets 1 to 8: holding a button keeps stepping, and stepping past either end jumps to the other end.
JSON 5 lines Copy {
"type": "stepper", "id": "preset", "position": [0, 1],
"label": "Preset", "min": 1, "max": 8, "step": 1,
"repeatOnHold": true, "wraps": true
}Open in CAR-TER ↗
Rendered by the app Light Dark Writes the value as a percentage in steps of 5; use "time" for minutes and seconds from a total in seconds, or "suffix:text" to add a unit.
JSON 5 lines Copy {
"type": "stepper", "id": "volume-pct", "position": [0, 2],
"label": "Volume", "min": 0, "max": 100, "step": 5,
"formatValue": "percent", "defaultValue": 40
}Open in CAR-TER ↗
Rendered by the app Light Dark Keeps the buttons and title but hides the number, for a stepper whose value is shown elsewhere; VoiceOver still announces it.
JSON 4 lines Copy {
"type": "stepper", "id": "silent-count", "position": [1, 0],
"label": "Adjust", "min": 0, "max": 20, "hideValue": true
}Open in CAR-TER ↗
Rendered by the app Light Dark Gives a heavy vibration on each tap and shows an Undo pill for 3 seconds after every change.
JSON 4 lines Copy {
"type": "stepper", "id": "servings", "position": [1, 1],
"label": "Servings", "min": 1, "max": 12, "haptic": "heavy", "confirm": true
}Open in CAR-TER ↗
Rendered by the app Light Dark Makes large, fully round orange buttons with a dark symbol and bigger numbers, set through the theme.
JSON 5 lines Copy {
"type": "stepper", "id": "styled", "position": [1, 2],
"label": "Laps", "min": 0, "max": 50,
"theme": { "buttonColor": "#FF9F0A", "buttonRadius": 30, "buttonSize": 44, "iconColor": "#000000", "valueFontSize": 22 }
}Open in CAR-TER ↗
Rendered by the app Light Dark Sends the new number to a device on every step: the action substitutes {{value}} with the current count, so the thermostat follows the stepper.
JSON 12 lines Copy {
"type": "stepper",
"id": "target-temp",
"position": [2, 0],
"span": [1, 2],
"min": 60,
"max": 85,
"step": 1,
"defaultValue": 72,
"label": "Target °F",
"action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "ecobee", "type": "set_temp", "payload": { "target": "{{value}}" } } }
}Open in CAR-TER ↗
Rendered by the app Light Dark Try it on your phone carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.
Install the Python kit.
Copy pip install carterkit Show “Value shown with a title and symbol” on your phone.
Copy carterkit demo stepper --example 'Value shown with a title and symbol' Swap in any example name from this page, or leave --example off for the first one.
carterkit quickstart · Get CAR-TER
Behavior
Displays current value with animated numeric transition
With wraps: false (default), +/- buttons disable and dim at their respective limits. An unchanged value emits no action, including VoiceOver adjustments.
Buttons and VoiceOver use the same bounded increment. Zero, negative, or non-finite step falls back to 1.
Reversed min/max bounds are sorted; equal bounds disable both buttons. Incoming values outside the range are clamped for display and the next adjustment starts from that boundary.
repeatOnHold: true enables press-and-hold repetition for both buttons. Releasing or cancelling the press stops repetition. The normal bounds or wrap behavior applies to each step.
wraps: true cycles from max to min (plus) and min to max (minus), including VoiceOver. A step that overshoots first lands on the boundary; the next step wraps. Equal bounds still disable both buttons.
hideValue: true hides only the visible number; VoiceOver still announces the value.
Generated from ControlDocs/stepper.md. Something unclear or missing? Tell me .