Guide / Controls / Inputs

Menu

Pick one from a list

When to use it. A scrollable selection for long option lists. Stores a .string value.

Type
picker
Also titled
Picker
Default size
1 row × 2 columns
Symbol
list.bullet
Docs
Docs complete
Search for it as
  • dropdown
  • select
  • menu
  • choose
  • options
  • combo box
Menu: Friendly labels with stable server values
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
Motionanimationchoiceone of 5—

How the choice change animates

Sets how the shown choice transitions when the value changes, from instant swap to a soft glide.

  • smoothan even natural transition
  • snappya quick firm change
  • bouncyovershoots slightly then settles
  • gentlea slow soft change
  • instantswaps with no transition
Choice symbolsoptionIconslist—

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 namesoptionLabelslist—

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 textplaceholdertext—

What shows when nothing is chosen

Writes this text when the list is empty (default No options) or nothing is selected (default Choose…).

Choicesoptionslist—

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.

LookpickerStylechoiceone of 3menu

How the list is shown

Switches between a compact dropdown, a spinning wheel, or a list shown in full.

  • menu defaulta compact button that opens a dropdown
  • wheela spinning drum you scroll to a choice
  • inlineevery choice shown as a tappable list
Labellabeltext—

The name shown with the picker

Writes this text as the picker title.

Colortintcolor#667eea

The highlight color

Colors the selected choice and the picker accent with this color.

Starting choicedefaultValuetext—

Which choice is picked at first

Selects this choice when the layout first appears; it should match one of the stored values.

Tap feelhapticchoiceone of 7selection

The 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.

  • lighta faint tap
  • mediuma firm tap
  • heavya strong thud
  • successa happy double tap
  • warninga cautionary buzz
  • errora sharp triple buzz
  • selection defaulta 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
FieldTypeDefaultWhat it does
Corner roundnesstheme.cornerRadiusnumber0–30 ptstep 112

The highlight color

Colors the quieter text such as the placeholder and value.

Border thicknesstheme.borderWidthnumber0–5 ptstep 0.51

How 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
SendsWhenTypeWhat it sends
When you pick an optionvaluepickstring

the option you picked, as its stored value

Picking the option already chosen sends nothing

Example: Item 1

Receives

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

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.

  • Item 1

Examples

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

Friendly labels with stable server values

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

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

Room selector (menu)

Shows the default menu look with an action: picking a room broadcasts a switch_room message carrying the chosen name.

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

Menu: Room selector (menu)
Rendered by the app

Playlist picker (wheel)

Shows the wheel look: a spinning drum you scroll to a playlist, starting on Chill.

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

Menu: Playlist picker (wheel)
Rendered by the app

Inline list

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

Menu: Inline list
Rendered by the app

Placeholder with undo

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

Menu: Placeholder with undo
Rendered by the app

Themed picker

Shows theme overrides: rounder corners, more padding and a thicker border in a custom accent for a bolder card.

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

Menu: Themed picker
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 picker --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

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.