Guide / Controls / Inputs

Choice

Pick one of a few options

When to use it. A short option list displayed as inline segments. Stores a .string value.

Type
segmentedControl
Also titled
Segmented Control
Default size
1 row × 2 columns
Symbol
rectangle.split.3x1
Docs
Docs complete
Search for it as
  • tabs
  • tab bar
  • choice
  • options
  • radio
  • switcher
Choice: Friendly labels with stable server values
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
animationanimationchoiceone of 5—

How the highlight slides between choices

The selected highlight eases to a new choice; instant makes it jump with no travel.

  • smoothan even ease and the default
  • snappya quick move that settles fast
  • bouncyovershoots slightly then springs back
  • gentlea slow and soft glide
  • instantjumps straight to the new choice with no travel
optionLabelsoptionLabelslist—

Display names for the choices, in the same order

Each segment shows this text in place of its stored value; a blank entry falls back to the value.

placeholderplaceholdertext—

Words shown when there is nothing to pick

Shows this text, e.g. No options, where the segments would be when the list is empty.

Choicesoptionslist—

The choices you can tap

Creates one segment per entry, in order; two to five fit best.

optionIconsoptionIconslist—

Small pictures on the choices

Draws an SF Symbol on each segment at the same position as its option; missing entries show none.

stylestylechoiceone of 3default

Plain bar, round pills or stars

Switches between the system segmented bar, separate capsule buttons and a row of tappable stars.

  • default defaultthe standard iOS segmented bar
  • pillsseparate capsule buttons with the chosen one tinted
  • starsa row of stars where tapping one fills up to it and sends its number
tinttintcolor#667eea

The highlight colour on pills

Colours the selected pill background and the filled stars; the default bar ignores it.

defaultValuedefaultValuetext—

Which choice starts selected

The segment matching this option is highlighted when the control first appears.

haptichapticchoiceone of 7selection

The tap feel when you change choice

After each change a pill naming it with an Undo button shows for 3 seconds.

  • lighta small soft tap
  • mediuma medium tap
  • heavya strong thump
  • successa confirming double pulse
  • warningan alert pulse
  • errora sharp failure buzz
  • selection defaulta tiny tick like scrolling a picker and the default

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
trackColortheme.trackColorcolor#39393D

The colour behind the segments

Fills the strip the segments sit on with this colour.

selectedColortheme.selectedColorcolor#636366

The colour of the chosen segment

Fills the selected segment with this colour.

selectedRadiustheme.selectedRadiusnumber0–30 ptstep 16

How round the chosen segment is

Rounds the corners of the highlighted segment, 0 to 30 points.

selectedShadowtheme.selectedShadowon / offtrue (on)

A shadow under the chosen segment

Turns on a soft drop shadow beneath the highlighted segment; off leaves it flat.

textColortheme.textColorcolor#FFFFFF99

The words of choices not picked

Colours the labels of segments that are not selected.

selectedTextColortheme.selectedTextColorcolor#FFFFFF

The colour of supporting words

Colours the quieter supporting text in the control.

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 pick a choicevaluepickstring

the stored value of the choice you tapped (not its friendly label)

Tapping the choice that is already selected sends nothing

Example: One

Receives

Receives
TakesFromTypeWhat it does
valuefollowhub, mqtt, http, store, defaultstring

the stored value of the choice to select

that segment lights up without sending anything; a value that matches no choice stays shown until you pick one

Example: One

Sample

The placeholder value the editor shows before real data arrives.

  • One then Two

Examples

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

Friendly labels with stable server values

Shows optionLabels and optionIcons: the segments read Economy, Comfort and Sport with icons, while the stored and sent values stay eco, comfort and sport.

JSON 6 lines
{
  "type": "segmentedControl", "id": "drive-mode", "position": [0, 0],
  "options": ["eco", "comfort", "sport"],
  "optionLabels": ["Economy", "Comfort", "Sport"],
  "optionIcons": ["leaf", "car", "bolt"], "defaultValue": "eco"
}

Open in CAR-TER

Choice: Friendly labels with stable server values
Rendered by the app

HVAC mode selector

Shows the default bar with an action: tapping a mode sends that mode's text to the thermostat, starting on Auto.

JSON 9 lines
{
  "type": "segmentedControl",
  "id": "hvac-mode",
  "position": [1, 2],
  "span": [1, 2],
  "options": ["Heat", "Cool", "Auto", "Off"],
  "defaultValue": "Auto",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "ecobee", "type": "set_mode", "payload": { "mode": "{{value}}" } } }
}

Open in CAR-TER

Choice: HVAC mode selector
Rendered by the app

Fan speed with pills

Shows the pills look: three separate capsule buttons with a wind icon on each, the chosen one tinted.

JSON 11 lines
{
  "type": "segmentedControl",
  "id": "fan-speed",
  "position": [0, 1],
  "span": [1, 3],
  "options": ["Low", "Med", "High"],
  "optionIcons": ["wind", "wind", "wind"],
  "style": "pills",
  "tint": "#34C759",
  "defaultValue": "Med"
}

Open in CAR-TER

Choice: Fan speed with pills
Rendered by the app

Star rating

Shows the stars look: five tappable stars where tapping the fourth fills four and sends the number 4.

JSON 6 lines
{
  "type": "segmentedControl", "id": "movie-rating", "position": [0, 0],
  "options": ["1", "2", "3", "4", "5"],
  "style": "stars", "tint": "#FFCC00", "defaultValue": "3",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "media", "type": "rate", "payload": { "stars": "{{value}}" } } }
}

Open in CAR-TER

Choice: Star rating
Rendered by the app

Live selection from the network

Shows sync: the highlighted choice follows the mode the device reports, and tapping still sends a change.

JSON 6 lines
{
  "type": "segmentedControl", "id": "scene-mode", "position": [0, 0],
  "options": ["Day", "Evening", "Night"],
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "scene_state" }, "valuePath": "mode" }],
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "lights", "type": "set_scene", "payload": { "mode": "{{value}}" } } }
}

Open in CAR-TER

Choice: Live selection from the network
Rendered by the app

Quiet choice with undo and a firm tap

Shows confirm, haptic and animation: each change plays a heavy tap, snaps quickly, and shows a pill with Undo for 3 seconds.

JSON 5 lines
{
  "type": "segmentedControl", "id": "garage-door", "position": [0, 0],
  "options": ["Open", "Closed"], "defaultValue": "Closed",
  "confirm": true, "haptic": "heavy", "animation": "snappy"
}

Open in CAR-TER

Choice: Quiet choice with undo and a firm tap
Rendered by the app

Empty list placeholder

Shows placeholder: with no options yet, the control reads "Nothing to pick" instead of the default "No options".

JSON 4 lines
{
  "type": "segmentedControl", "id": "empty-choice", "position": [0, 0],
  "options": [], "placeholder": "Nothing to pick"
}

Open in CAR-TER

Choice: Empty list placeholder
Rendered by the app

Themed segmented control

Shows theme overrides: a rounder bar with a bold border, a bright selected segment with no shadow and larger text.

JSON 5 lines
{
  "type": "segmentedControl", "id": "bold-choice", "position": [0, 0],
  "options": ["A", "B", "C"], "defaultValue": "A",
  "theme": { "cornerRadius": 24, "controlPadding": 6, "trackColor": "#2C2C2E", "selectedColor": "#667eea", "selectedRadius": 18, "selectedShadow": false, "selectedTextColor": "#FFFFFF", "textColor": "#FFFFFF99", "labelFontSize": 16, "borderWidth": 2, "borderColor": "#667eea" }
}

Open in CAR-TER

Choice: Themed segmented control
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 “Friendly labels with stable server values” on your phone.

    carterkit demo segmentedControl --example 'Friendly labels with stable server values'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Styles

"default"

Standard iOS segmented picker. System-styled.

"pills"

Horizontal row of capsule-shaped buttons. Selected pill gets tinted background.

"stars"

A tap-a-star rating: options "1"…"N" show as stars, and tapping one fills up to it and sends its number.

Notes

  • Best for 2-5 options. For longer lists, use Border thickness instead.
  • Value is the string text of the selected option.

Display labels and live options

options contains the stored/server values. optionLabels supplies optional user-facing labels at the same indexes, and optionIcons supplies SF Symbols. Missing or empty labels fall back to the original value; missing icons are omitted. Duplicate option values use the first occurrence, preserving its label and icon. Labels themselves may repeat.

For example, "options": ["eco", "comfort", "sport"] with "optionLabels": ["Economy", "Comfort", "Sport"] displays “Economy” while storing and sending "eco". VoiceOver uses the friendly label too. Selecting the already-selected value sends no extra action.

Empty options show placeholder (default “No options”). A picker with an empty selection shows placeholder (default “Choose…”); an unknown nonempty selection remains visible until the user picks an available option. Live option changes never silently select or send a replacement value.

Generated from ControlDocs/segmented.md. Something unclear or missing? Tell me.