Guide / Controls / Inputs

Plus / minus

Count up or down one step at a time

When to use it. An increment/decrement numeric control. Stores a .number value.

Type
stepper
Also titled
Stepper
Default size
1 row × 2 columns
Symbol
plus.forwardslash.minus
Docs
Docs complete
Search for it as
  • plus minus
  • increment
  • counter
  • quantity
  • spinner
  • number input
Plus / minus: Value shown with a title and symbol
Rendered by the app

Fields

12 fields you can set on a stepper control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
Motionanimationchoiceone of 5—

How the number changes when it steps

Sets how the readout animates between values, from an instant swap to a soft glide.

  • smoothan even natural transition
  • snappya quick firm change
  • bouncyovershoots slightly then settles
  • gentlea slow soft transition
  • instantchanges with no animation
Lowest valueminnumber0

The count never goes below this

Sets the lowest number reachable; the minus button dims there.

Highest valuemaxnumber100

The count never goes above this

Sets the highest number reachable; the plus button dims there.

Step sizestepnumber1

How 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 heldrepeatOnHoldon / offfalse (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 endswrapson / offfalse (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 numberhideValueon / offfalse (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.

Titlelabeltext—

The name shown on the control

Writes this text as the title of the stepper.

Symbolicontext—

A small picture beside the number

Shows this SF Symbol before the value.

Number formatformatValuechoiceone of 18decimal

How 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 valuedefaultValuenumber—

Where the count starts

Shows this number (within lowest to highest) until something else sets it.

Vibration on taphapticchoiceone of 7light

The buzz you feel on each tap

Shows a pill naming the change with an Undo button for 3 seconds after you step.

  • light defaulta soft tap
  • mediuma firmer tap
  • heavya strong thump
  • successa pleasant double tap
  • warninga cautionary buzz
  • errora sharp failure buzz
  • selectiona 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
FieldTypeDefaultWhat it does
Number text sizetheme.valueFontSizenumber8–28step 114

How big the number is

Sets the number text size from 8 to 28 points.

Button colortheme.buttonColorcolor#667eea

The color of the plus and minus buttons

Fills both round buttons with this color.

Button roundnesstheme.buttonRadiusnumber0–30 ptstep 18

How round the buttons are

Rounds the button corners from 0 (square) to 30 points.

Button sizetheme.buttonSizenumber12–50 ptstep 132

How big the buttons are

Sets the button diameter from 12 to 50 points.

Symbol colortheme.iconColorcolor#FFFFFF

The 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
SendsWhenTypeWhat it sends
When you tap plus or minusvaluechangenumber

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
TakesFromTypeWhat it does
valuefollowhub, mqtt, http, store, defaultnumber

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.

  • 5 then 6

Examples

7 examples, each one a control you can paste into a layout.

Value shown with a title and symbol

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
{
  "type": "stepper", "id": "guests", "position": [0, 0],
  "label": "Guests", "icon": "person.2", "min": 0, "max": 10, "step": 1,
  "defaultValue": 3
}

Open in CAR-TER

Plus / minus: Value shown with a title and symbol
Rendered by the app

Cyclic selector with hold-to-repeat

Cycles through presets 1 to 8: holding a button keeps stepping, and stepping past either end jumps to the other end.

JSON 5 lines
{
  "type": "stepper", "id": "preset", "position": [0, 1],
  "label": "Preset", "min": 1, "max": 8, "step": 1,
  "repeatOnHold": true, "wraps": true
}

Open in CAR-TER

Plus / minus: Cyclic selector with hold-to-repeat
Rendered by the app

Number formats

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
{
  "type": "stepper", "id": "volume-pct", "position": [0, 2],
  "label": "Volume", "min": 0, "max": 100, "step": 5,
  "formatValue": "percent", "defaultValue": 40
}

Open in CAR-TER

Plus / minus: Number formats
Rendered by the app

Hidden number

Keeps the buttons and title but hides the number, for a stepper whose value is shown elsewhere; VoiceOver still announces it.

JSON 4 lines
{
  "type": "stepper", "id": "silent-count", "position": [1, 0],
  "label": "Adjust", "min": 0, "max": 20, "hideValue": true
}

Open in CAR-TER

Plus / minus: Hidden number
Rendered by the app

Haptic and confirmation

Gives a heavy vibration on each tap and shows an Undo pill for 3 seconds after every change.

JSON 4 lines
{
  "type": "stepper", "id": "servings", "position": [1, 1],
  "label": "Servings", "min": 1, "max": 12, "haptic": "heavy", "confirm": true
}

Open in CAR-TER

Plus / minus: Haptic and confirmation
Rendered by the app

Restyled buttons

Makes large, fully round orange buttons with a dark symbol and bigger numbers, set through the theme.

JSON 5 lines
{
  "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

Plus / minus: Restyled buttons
Rendered by the app

Thermostat target

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
{
  "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

Plus / minus: Thermostat target
Rendered by the app

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.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Value shown with a title and symbol” on your phone.

    carterkit demo stepper --example 'Value shown with a title and symbol'
  3. 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.