Guide / Controls / Buttons

Button

Tap it to make something happen

When to use it. A tappable action trigger. Fires its action on press. It stores no value of its own, but a button with a sync can show server state through valueMap / iconMap / colorMap (a stateful key).

Type
button
Default size
1 row × 1 column
Symbol
hand.tap.fill
Docs
Docs complete
Search for it as
  • tap
  • press
  • click
  • trigger
  • action
  • send
Button: Simple button
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
TitlelabeltextButton

The words on the button

Sets the text shown on the button; empty shows the control id.

Symbolicontext—

A small picture beside the words

Draws the chosen SF Symbol before the label, or alone with Symbol only.

Lookstylechoiceone of 6filled

How the button is dressed

Switches the button between a solid fill, an outline, a faint tint, or just the symbol.

  • filled defaultsolid colored block with light text
  • outlinedclear inside with a colored border
  • outlinesame as outlined
  • ghostno fill or border, just the colored text
  • tintedsoft wash of the color with colored text
  • icon-onlyonly the symbol, no text or block
Sizesizechoiceone of 3default

How big the button is

Scales the button's height and text between compact, normal and large.

  • compactsmall and tight, for crowded grids
  • default defaultthe normal size
  • largetall and roomy, easy to hit
Colortintcolor#667eea

The button's main color

Recolors the fill, border or text (per Look) to the chosen color.

Symbol onlyhideLabelon / offfalse (off)

Hide the words, keep the picture

When on, the label text disappears and only the symbol remains.

Vibration on taphapticchoiceone of 7medium

How the tap feels

Plays the chosen buzz on the phone each time the button is pressed.

  • lighta faint tick
  • medium defaulta normal tap
  • heavya firm thump
  • successa short double-tap for done
  • warninga sharper alert buzz
  • errora harsh triple buzz for failure
  • selectiona tiny click like scrolling a picker
Repeat while heldrepeatOnHoldon / offfalse (off)

Keep going while held

Holding the button refires its action repeatedly, speeding up the longer you hold.

Words for valuesvalueMapobject—

Different words for different states

Replaces the label with the text matching the synced value, e.g. true shows Pause.

Symbols for valuesiconMapobject—

Different pictures for different states

Swaps the symbol to the one matching the synced value, with a replace animation.

Colors for valuescolorMapobject—

Different colors for different states

A pill naming the change appears for 3 seconds with an Undo button after each tap.

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

Color of the words and symbol

Colors the border drawn around the button.

Border thicknesstheme.borderWidthnumber0–5 ptstep 0.51

How thick the outline is

Draws the border 0 to 5 points thick; 0 hides it.

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 itpresstapstring

the button's current value if it follows one, else false

Holding it with Repeat while held on sends again on each repeat

Example: true

Receives

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

a state to show, matched against the button's value, icon and color maps

the text, symbol and color switch to the matching entry, or to the default entry when none match; a new value never presses the button

Example: true

Sample

The placeholder value the editor shows before real data arrives.

  • true then false

Examples

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

Simple button

A plain filled button that sends a scene command to a hub; tapping it fires the action once with the default medium buzz.

JSON 7 lines
{
  "type": "button",
  "id": "all-off",
  "position": [0, 3],
  "label": "All Off",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hue-bridge", "type": "scene", "payload": { "name": "all_off" } } }
}

Open in CAR-TER

Button: Simple button
Rendered by the app

Icon-only ghost button (large, for transport controls)

Shows only a large pink play symbol with no block or text, the way a media transport key looks.

JSON 12 lines
{
  "type": "button",
  "id": "btn-play",
  "position": [0, 2],
  "label": "Play",
  "icon": "playpause.fill",
  "style": "ghost",
  "size": "large",
  "hideLabel": true,
  "tint": "#FF2D55",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "player", "type": "command", "payload": { "command": "playpause" } } }
}

Open in CAR-TER

Button: Icon-only ghost button (large, for transport controls)
Rendered by the app

Hold-to-repeat arrow key

Holding this compact outlined key keeps sending Up, like holding an arrow key on a keyboard.

JSON 11 lines
{
  "type": "button",
  "id": "t-up",
  "position": [8, 2],
  "label": "Up",
  "icon": "arrow.up",
  "style": "outlined",
  "size": "compact",
  "repeatOnHold": true,
  "action": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "command", "key": "Up" } }
}

Open in CAR-TER

Button: Hold-to-repeat arrow key
Rendered by the app

Stateful play/pause key

The key's symbol swaps between play and pause to match the player's state, and tapping still sends the toggle.

JSON 14 lines
{
  "type": "button",
  "id": "btn-playpause",
  "position": [0, 2],
  "label": "Play/Pause",
  "icon": "playpause.fill",
  "size": "large",
  "hideLabel": true,
  "tint": "#FF2D55",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "cider_state" }, "valuePath": "playing" }],
  "valueMap": { "true": "Pause", "false": "Play" },
  "iconMap": { "true": "pause.fill", "false": "play.fill" },
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "player", "type": "command", "payload": { "command": "playpause" } } }
}

Open in CAR-TER

Button: Stateful play/pause key
Rendered by the app

Button with long-press detail popup

Tapping fires the Movie scene; holding opens a detail panel with brightness and two switches.

JSON 21 lines
{
  "type": "button",
  "id": "scene-movie",
  "position": [0, 0],
  "label": "Movie",
  "icon": "film",
  "style": "tinted",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "home-hub", "type": "macro", "payload": { "name": "movie_mode" } } },
  "longPressGroup": {
    "position": [0, 0],
    "span": [2, 2],
    "id": "movie-detail",
    "label": "Movie Mode Settings",
    "grid": { "columns": 2, "rows": 2 },
    "children": [
      { "type": "slider", "id": "movie-brightness", "position": [0, 0], "span": [1, 2], "min": 0, "max": 100, "label": "Brightness" },
      { "type": "toggle", "id": "movie-auto-screen", "position": [1, 0], "label": "Auto Screen" },
      { "type": "toggle", "id": "movie-auto-audio", "position": [1, 1], "label": "Auto Audio" }
    ]
  }
}

Open in CAR-TER

Button: Button with long-press detail popup
Rendered by the app

Filled look (the default)

A solid colored block with light text; the strongest look, for the main action.

JSON 9 lines
{
  "type": "button",
  "id": "b-filled",
  "position": [0, 0],
  "label": "Lights On",
  "style": "filled",
  "tint": "#34C759",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hue-bridge", "type": "scene", "payload": { "name": "lights_on" } } }
}

Open in CAR-TER

Button: Filled look (the default)
Rendered by the app

Outlined look

A clear button with a colored border, for a quieter secondary action.

JSON 9 lines
{
  "type": "button",
  "id": "b-outlined",
  "position": [1, 0],
  "label": "Dim",
  "style": "outlined",
  "tint": "#FF9500",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hue-bridge", "type": "scene", "payload": { "name": "dim" } } }
}

Open in CAR-TER

Button: Outlined look
Rendered by the app

Ghost look

Only colored text with no block or border, for a low-key action in a busy panel.

JSON 8 lines
{
  "type": "button",
  "id": "b-ghost",
  "position": [2, 0],
  "label": "More",
  "style": "ghost",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hue-bridge", "type": "scene", "payload": { "name": "more" } } }
}

Open in CAR-TER

Button: Ghost look
Rendered by the app

Tinted look

A soft wash of the color behind colored text, a calm middle ground between filled and outlined.

JSON 10 lines
{
  "type": "button",
  "id": "b-tinted",
  "position": [3, 0],
  "label": "Night",
  "icon": "moon.fill",
  "style": "tinted",
  "tint": "#5856D6",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hue-bridge", "type": "scene", "payload": { "name": "night" } } }
}

Open in CAR-TER

Button: Tinted look
Rendered by the app

Icon-only look

The symbol alone with no text or block, for tight spaces; the label is still used for accessibility.

JSON 9 lines
{
  "type": "button",
  "id": "b-icon",
  "position": [4, 0],
  "label": "Lamp",
  "icon": "lightbulb.fill",
  "style": "icon-only",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hue-bridge", "type": "scene", "payload": { "name": "lamp" } } }
}

Open in CAR-TER

Button: Icon-only look
Rendered by the app

Compact and large sizes

Size changes the button's height and text: a compact key fits dense grids while a large one is easy to hit with a thumb.

JSON 10 lines
{
  "type": "button",
  "id": "b-large",
  "position": [0, 1],
  "span": [2, 1],
  "label": "Big Red",
  "size": "large",
  "tint": "#FF3B30",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hue-bridge", "type": "scene", "payload": { "name": "big_red" } } }
}

Open in CAR-TER

Button: Compact and large sizes
Rendered by the app

Strong haptic on tap

Plays a firm thump when pressed, so a risky action feels deliberate.

JSON 8 lines
{
  "type": "button",
  "id": "b-haptic",
  "position": [2, 1],
  "label": "Lock Down",
  "haptic": "heavy",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hue-bridge", "type": "scene", "payload": { "name": "lock_down" } } }
}

Open in CAR-TER

Button: Strong haptic on tap
Rendered by the app

Tap with Undo confirmation

After each tap a pill names the change and offers Undo for 3 seconds, so an accidental press can be reversed.

JSON 8 lines
{
  "type": "button",
  "id": "b-confirm",
  "position": [3, 1],
  "label": "Arm",
  "confirm": true,
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hue-bridge", "type": "scene", "payload": { "name": "arm" } } }
}

Open in CAR-TER

Button: Tap with Undo confirmation
Rendered by the app

Symbol only toggle (hideLabel)

Keeps the label in the data but shows just the symbol, turning a labeled button into an icon key.

JSON 9 lines
{
  "type": "button",
  "id": "b-hide",
  "position": [4, 1],
  "label": "Fan",
  "icon": "fan.fill",
  "hideLabel": true,
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hue-bridge", "type": "scene", "payload": { "name": "fan" } } }
}

Open in CAR-TER

Button: Symbol only toggle (hideLabel)
Rendered by the app

Stateful key with colors for values

The button's words, symbol and color all follow a synced value: it reads Armed in red when true and Disarmed in green when false.

JSON 12 lines
{
  "type": "button",
  "id": "b-alarm",
  "position": [0, 2],
  "label": "Alarm",
  "icon": "shield",
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "alarm_state" }, "valuePath": "armed" }],
  "valueMap": { "true": "Armed", "false": "Disarmed", "default": "Alarm" },
  "iconMap": { "true": "shield.fill", "false": "shield" },
  "colorMap": { "true": "#FF3B30", "false": "#34C759" },
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "alarm", "type": "command", "payload": { "command": "toggle" } } }
}

Open in CAR-TER

Button: Stateful key with colors for values
Rendered by the app

Long-press action

Tapping sends the normal action; holding runs a different one, here a full reset, without opening a panel.

JSON 9 lines
{
  "type": "button",
  "id": "b-longaction",
  "position": [1, 2],
  "label": "Heat",
  "icon": "flame",
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "thermostat", "type": "command", "payload": { "command": "boost" } } },
  "longPressAction": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "thermostat", "type": "command", "payload": { "command": "off" } } }
}

Open in CAR-TER

Button: Long-press action
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 “Simple button” on your phone.

    carterkit demo button --example 'Simple button'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

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