Fields 9 fields you can set on a segmentedControl control. Every control also takes the shared fields (id, position, span, sync, action).
Fields Field Type Default What it does animation animationchoice one of 5 — How the highlight slides between choices
The selected highlight eases to a new choice; instant makes it jump with no travel.
smooth an even ease and the default snappy a quick move that settles fast bouncy overshoots slightly then springs back gentle a slow and soft glide instant jumps straight to the new choice with no travel optionLabels optionLabelslist — 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.
placeholder placeholdertext — 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.
Choices optionslist — The choices you can tap
Creates one segment per entry, in order; two to five fit best.
optionIcons optionIconslist — Small pictures on the choices
Draws an SF Symbol on each segment at the same position as its option; missing entries show none.
style stylechoice one of 3 defaultPlain bar, round pills or stars
Switches between the system segmented bar, separate capsule buttons and a row of tappable stars.
default default the standard iOS segmented bar pills separate capsule buttons with the chosen one tinted stars a row of stars where tapping one fills up to it and sends its number tint tintcolor #667eeaThe highlight colour on pills
Colours the selected pill background and the filled stars; the default bar ignores it.
defaultValue defaultValuetext — Which choice starts selected
The segment matching this option is highlighted when the control first appears.
haptic hapticchoice one of 7 selectionThe tap feel when you change choice
After each change a pill naming it with an Undo button shows for 3 seconds.
light a small soft tap medium a medium tap heavy a strong thump success a confirming double pulse warning an alert pulse error a sharp failure buzz selection default a 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 Field Type Default What it does trackColor theme.trackColorcolor #39393DThe colour behind the segments
Fills the strip the segments sit on with this colour.
selectedColor theme.selectedColorcolor #636366The colour of the chosen segment
Fills the selected segment with this colour.
selectedRadius theme.selectedRadiusnumber 0–30 pt step 1 6How round the chosen segment is
Rounds the corners of the highlighted segment, 0 to 30 points.
selectedShadow theme.selectedShadowon / off true (on) A shadow under the chosen segment
Turns on a soft drop shadow beneath the highlighted segment; off leaves it flat.
textColor theme.textColorcolor #FFFFFF99The words of choices not picked
Colours the labels of segments that are not selected.
selectedTextColor theme.selectedTextColorcolor #FFFFFFThe 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 Sends When Type What it sends When you pick a choice valuepick string 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 Takes From Type What it does value followhub, mqtt, http, store, default string 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.
Examples 8 examples, each one a control you can paste into a layout.
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 Copy {
"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 ↗
Rendered by the app Light Dark Shows the default bar with an action: tapping a mode sends that mode's text to the thermostat, starting on Auto.
JSON 9 lines Copy {
"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 ↗
Rendered by the app Light Dark Shows the pills look: three separate capsule buttons with a wind icon on each, the chosen one tinted.
JSON 11 lines Copy {
"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 ↗
Rendered by the app Light Dark Shows the stars look: five tappable stars where tapping the fourth fills four and sends the number 4.
JSON 6 lines Copy {
"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 ↗
Rendered by the app Light Dark Shows sync: the highlighted choice follows the mode the device reports, and tapping still sends a change.
JSON 6 lines Copy {
"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 ↗
Rendered by the app Light Dark 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 Copy {
"type": "segmentedControl", "id": "garage-door", "position": [0, 0],
"options": ["Open", "Closed"], "defaultValue": "Closed",
"confirm": true, "haptic": "heavy", "animation": "snappy"
}Open in CAR-TER ↗
Rendered by the app Light Dark Shows placeholder: with no options yet, the control reads "Nothing to pick" instead of the default "No options".
JSON 4 lines Copy {
"type": "segmentedControl", "id": "empty-choice", "position": [0, 0],
"options": [], "placeholder": "Nothing to pick"
}Open in CAR-TER ↗
Rendered by the app Light Dark Shows theme overrides: a rounder bar with a bold border, a bright selected segment with no shadow and larger text.
JSON 5 lines Copy {
"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 ↗
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 “Friendly labels with stable server values” on your phone.
Copy carterkit demo segmentedControl --example 'Friendly labels with stable server values' 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 .