Fields 10 fields you can set on a picker 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 choice change animates
Sets how the shown choice transitions when the value changes, from 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 change instant swaps with no transition Choice symbols optionIconslist — A small picture beside each choice
Shows the SF Symbol at the same position next to each choice, in every look; a blank or missing entry shows no icon.
Choice names optionLabelslist — Display names for the choices, in the same order
Shows these names instead of the stored values; the original value is still what is saved and sent.
Empty text placeholdertext — What shows when nothing is chosen
Writes this text when the list is empty (default No options) or nothing is selected (default Choose…).
Choices optionslist — The list of things you can pick
Fills the menu, wheel or list with one row per entry; the picked entry is the value stored and sent.
Look pickerStylechoice one of 3 menuHow the list is shown
Switches between a compact dropdown, a spinning wheel, or a list shown in full.
menu default a compact button that opens a dropdown wheel a spinning drum you scroll to a choice inline every choice shown as a tappable list Label labeltext — The name shown with the picker
Writes this text as the picker title.
Color tintcolor #667eeaThe highlight color
Colors the selected choice and the picker accent with this color.
Starting choice defaultValuetext — Which choice is picked at first
Selects this choice when the layout first appears; it should match one of the stored values.
Tap feel hapticchoice one of 7 selectionThe buzz felt when you change the choice
Shows a pill naming the change with an Undo button for 3 seconds after you pick a choice.
light a faint tap medium a firm tap heavy a strong thud success a happy double tap warning a cautionary buzz error a sharp triple buzz selection default a tiny tick like scrolling a wheel
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 Corner roundness theme.cornerRadiusnumber 0–30 pt step 1 12The highlight color
Colors the quieter text such as the placeholder and value.
Border thickness theme.borderWidthnumber 0–5 pt step 0.5 1How big the label is
Sets the label text size from 8 to 24 points.
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 an option valuepick string the option you picked, as its stored value
Picking the option already chosen sends nothing
Example: Item 1
Receives Receives Takes From Type What it does value followhub, mqtt, http, store, default string the stored value of the option to select
that option becomes the selected one without sending; your next pick replaces it
Example: Item 1
Sample The placeholder value the editor shows before real data arrives.
Examples 6 examples, each one a control you can paste into a layout.
Shows optionLabels and optionIcons: the menu reads Economy, Comfort and Sport with a symbol each, while eco, comfort or sport is what is stored and sent.
JSON 6 lines Copy {
"type": "picker", "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 menu look with an action: picking a room broadcasts a switch_room message carrying the chosen name.
JSON 10 lines Copy {
"type": "picker",
"id": "room-select",
"position": [0, 0],
"span": [1, 2],
"options": ["Living Room", "Bedroom", "Kitchen", "Bathroom", "Office", "Garage", "Patio"],
"defaultValue": "Living Room",
"label": "Room",
"action": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "switch_room", "room": "{{value}}" } }
}Open in CAR-TER ↗
Rendered by the app Light Dark Shows the wheel look: a spinning drum you scroll to a playlist, starting on Chill.
JSON 10 lines Copy {
"type": "picker",
"id": "playlist",
"position": [0, 0],
"span": [2, 4],
"options": ["Chill", "Focus", "Workout", "Party", "Sleep", "Jazz", "Classical"],
"pickerStyle": "wheel",
"defaultValue": "Chill",
"label": "Playlist"
}Open in CAR-TER ↗
Rendered by the app Light Dark Shows the inline look: every choice is visible as a tappable list, with a custom tint and a success haptic on change.
JSON 5 lines Copy {
"type": "picker", "id": "fan-mode", "position": [0, 0], "span": [2, 3],
"options": ["Auto", "Low", "Medium", "High"], "pickerStyle": "inline",
"label": "Fan", "tint": "#34C759", "haptic": "success", "defaultValue": "Auto"
}Open in CAR-TER ↗
Rendered by the app Light Dark Shows placeholder and confirm: with no starting choice the picker reads "Pick a scene", and each pick shows an Undo pill for 3 seconds.
JSON 5 lines Copy {
"type": "picker", "id": "scene", "position": [0, 0],
"options": ["Movie", "Dinner", "Reading"], "placeholder": "Pick a scene",
"label": "Scene", "confirm": true, "animation": "snappy"
}Open in CAR-TER ↗
Rendered by the app Light Dark Shows theme overrides: rounder corners, more padding and a thicker border in a custom accent for a bolder card.
JSON 5 lines Copy {
"type": "picker", "id": "themed-pick", "position": [0, 0],
"options": ["Day", "Night"], "label": "Mode",
"theme": { "cornerRadius": 24, "controlPadding": 14, "borderWidth": 2, "borderColor": "#667eea", "accentColor": "#FF9500", "labelFontSize": 16 }
}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 picker --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
Value
Description
"menu"
Dropdown menu (compact, default)
"wheel"
Spinning wheel picker
"inline"
Inline scrollable list
Notes
haptic and animation have no visible effect in the wheel look beyond the system wheel feel; the picker has no long-press or detail view
For 2-5 options, prefer Choices for better space efficiency
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/picker.md. Something unclear or missing? Tell me .