Guide / Controls / Inputs

Switch

Turns something on or off

When to use it. A boolean on/off control. Stores a .bool value.

Type
toggle
Also titled
Toggle
Default size
1 row × 1 column
Symbol
switch.2
Docs
Docs complete
Search for it as
  • switch
  • on off
  • checkbox
  • enable
  • flip
  • boolean
Switch: Standard switch
Rendered by the app

Fields

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

Fields
FieldTypeDefaultWhat it does
Motionanimationchoiceone of 5—

How the switch moves when it flips

Sets the speed and feel of the knob's travel between off and on, from instant to a slow ease.

  • smoothan even natural glide
  • snappyquick with a crisp stop
  • bouncyovershoots slightly and settles
  • gentleslow and soft
  • instantno travel, it jumps straight to the new state
Titlelabeltext—

The name shown with the switch

Shows this text above the switch in the label font size (8-24 pt, default 12).

Symbolicontext—

A small picture beside the name

Draws this SF Symbol beside the label; leave it empty for no icon.

Lookstylechoiceone of 3switch

What the control looks like

Switches the whole control between an iOS-style sliding switch, a tappable button and a single icon that swaps.

  • switch defaulta sliding track with a round knob
  • buttona tappable tile that glows in the on color when on
  • icon-toggleone symbol that swaps between the on and off icons
Initial on/off statedefaultValueon / offfalse (off)

Whether it starts on or off

Starts the control on (true) or off (false) until the first tap or live update.

Symbol when ononIcontext—

The picture shown when it is on

Shows this SF Symbol while the control is on, replacing the main icon in button and icon-toggle looks.

Symbol when offoffIcontext—

The picture shown when it is off

Shows this SF Symbol while the control is off, replacing the main icon in button and icon-toggle looks.

Color when ontintcolor#667eea

The color it lights up with

Colors the track, glow or icon in this color whenever the control is on.

No background cardhideBackgroundon / offfalse (off)

Whether the card behind it is drawn

Removes the frosted card behind the control so only the switch and label sit on the page.

Vibration on taphapticchoiceone of 8rigid

The buzz you feel on a tap

Plays this haptic on the phone each time the control flips.

  • lighta small soft tap
  • mediuma medium tap
  • heavya strong thud
  • rigid defaulta firm sharp click
  • successthe double tap of a success
  • warninga two-pulse warning
  • errora sharp triple buzz of an error
  • selectionthe faint tick of picking an item
Track lengthtrackLengthnumber31–400step 151

How long the switch track is

Stretches the track tip to tip along its path from 31 to 400 pt (default 51).

Track curvetrackCurvaturenumber-180–180step 50

How much the switch bends

Bends the track from -180 to 180 degrees; 0 is straight, positive bows up and negative bows down.

Track roundnesstrackRadiusnumber0–20step 0.515.5

How round the switch ends are

Rounds the track corners from 0 (square) to 20 pt (fully round at default thickness).

Knob roundnessknobRadiusnumber0–13.5step 0.513.5

How round the sliding knob is

Rounds the knob corners from 0 (square) to 13.5 pt (a circle).

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

The switch color when off

Fills the empty switch track with this color while off, default dark grey.

Track color when ontheme.trackActiveColorcolor#667eea

The switch color when on

Fills the switch track with this color while on, default the accent purple.

Track roundnesstheme.trackRadiusnumber0–30step 0.515.5

How round the track ends are in the theme

Rounds the track corners from 0 to 30 pt as a theme default (15.5 is a full pill).

Track heighttheme.trackHeightnumber16–60step 131

How tall the switch is

Sets the track thickness from 16 to 60 pt (default 31); the knob scales with it.

Track widththeme.trackWidthnumber30–100step 151

How wide the switch is

Sets the track width from 30 to 100 pt (default 51).

Knob color when ontheme.knobActiveColorcolor—

The knob's color when the switch is on

Blends the knob to this color as the switch turns on; leave it empty to keep one knob color.

Knob colortheme.knobColorcolor#FFFFFF

The color of the sliding knob

Fills the knob with this color, default white.

Knob roundnesstheme.knobRadiusnumber0–30step 0.513.5

How round the knob is in the theme

Rounds the knob corners from 0 to 30 pt as a theme default (13.5 is a circle).

Knob shadowtheme.knobShadowon / offtrue (on)

Whether the knob casts a shadow

Colors the dimmer supporting text, default a soft translucent white.

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 flip itvaluechangebool

true when it is now on, false when it is now off

A tap flips it, and a drag across the track sends once when you let go past halfway

Example: true

Receives

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

on or off; text such as "on", "yes", "true" or "1" and any number except 0 count as on

the switch slides to match without sending anything; your next flip replaces it

Example: true

Sample

The placeholder value the editor shows before real data arrives.

  • true then false

Examples

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

Standard switch

Shows the default look wired both ways: flipping it sends the new on/off value to a light, and the switch follows the light's live state. Intended effect: the living-room light turns on or off with a tap, and the switch stays correct when someone else changes it.

JSON 9 lines
{
  "type": "toggle",
  "id": "lr-main",
  "position": [0, 0],
  "label": "Main Light",
  "defaultValue": true,
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "hue-bridge", "type": "light", "payload": { "room": "living", "fixture": "main", "command": "{{value}}" } } },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "room": "living", "fixture": "main" }, "valuePath": "state" }]
}

Open in CAR-TER

Switch: Standard switch
Rendered by the app

Button look

Shows the button look, a tile that glows in the tint color while on. Intended effect: a bold, thumb-sized tile for a setting you flip often, starting off.

JSON 10 lines
{
  "type": "toggle",
  "id": "porch-light",
  "position": [0, 0],
  "label": "Porch",
  "style": "button",
  "icon": "lightbulb.fill",
  "tint": "#FFCC00",
  "defaultValue": false
}

Open in CAR-TER

Switch: Button look
Rendered by the app

Icon-toggle with custom icons

Shows the icon-toggle look, where the symbol swaps between the on and off icons. Intended effect: a red microphone that shows a slashed mic when muted.

JSON 11 lines
{
  "type": "toggle",
  "id": "mic-mute",
  "position": [0, 0],
  "label": "Mic",
  "style": "icon-toggle",
  "onIcon": "mic.fill",
  "offIcon": "mic.slash.fill",
  "tint": "#FF3B30",
  "defaultValue": true
}

Open in CAR-TER

Switch: Icon-toggle with custom icons
Rendered by the app

Curved, restyled switch track

Shows the track fields: a longer track bent upward with a squarer knob. Intended effect: a 120 pt switch that bows 90 degrees, with its knob following the curve.

JSON 12 lines
{
  "type": "toggle",
  "id": "arc-switch",
  "position": [0, 0],
  "label": "Arc",
  "style": "switch",
  "trackLength": 120,
  "trackCurvature": 90,
  "trackRadius": 15.5,
  "knobRadius": 4,
  "animation": "bouncy"
}

Open in CAR-TER

Switch: Curved, restyled switch track
Rendered by the app

Confirmation with Undo and custom haptic

Shows the confirm option and a chosen haptic, with no background card. Intended effect: each flip gives a heavy buzz and a 3-second pill with Undo, so a risky switch can be reversed.

JSON 10 lines
{
  "type": "toggle",
  "id": "garage-lock",
  "position": [0, 0],
  "label": "Garage Lock",
  "haptic": "heavy",
  "confirm": true,
  "hideBackground": true,
  "action": { "method": "meshsocket", "mode": "send", "event": "route_msg_noreply", "payload": { "target_name": "garage", "type": "lock", "payload": { "command": "{{value}}" } } }
}

Open in CAR-TER

Switch: Confirmation with Undo and custom haptic
Rendered by the app

Conditionally visible toggle

Shows the visible rule: the control appears only while another control has a given value. Intended effect: the Oscillate switch is hidden until the fan power switch is on.

JSON 8 lines
{
  "type": "toggle",
  "id": "fan-oscillate",
  "position": [1, 1],
  "label": "Oscillate",
  "defaultValue": false,
  "visible": { "when": "fan-power", "operator": "eq", "value": true }
}

Open in CAR-TER

Switch: Conditionally visible toggle
Rendered by the app

Toggle with long-press detail

Shows a long-press group opening a detail panel from the toggle. Intended effect: tap flips the heater, holding it opens a small panel of extra readouts.

JSON 16 lines
{
  "type": "toggle",
  "id": "heater",
  "position": [0, 0],
  "label": "Heater",
  "longPressGroup": {
    "position": [0, 0],
    "span": [2, 1],
    "id": "heater-detail",
    "label": "Heater Detail",
    "grid": { "columns": 2, "rows": 1 },
    "children": [
      { "type": "label", "id": "heater-note", "position": [0, 0], "text": "Runs until switched off" }
    ]
  }
}

Open in CAR-TER

Switch: Toggle with long-press detail
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 “Standard switch” on your phone.

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

carterkit quickstart · Get CAR-TER

Styles

"switch" (default)

Standard iOS toggle switch with label above and optional icon beside.

"button"

Tap-to-toggle button. Background highlights when on with a tinted glow.

"icon-toggle"

Icon that swaps between onIcon and offIcon with a symbol transition animation.

Track geometry and interaction

Switch styles support trackLength (31–400 pt at the default theme), trackCurvature (−180° to 180°), trackRadius, and knobRadius. Length is measured along the path. Positive curvature bows up; negative bows down. Tight curves are limited to keep the inner track edge from collapsing. Lengthen the track to allow a larger bend.

The knob follows the curved centerline throughout taps, remote changes, and drag release; square knobs rotate with the tangent. animation applies to all toggle styles, including custom durations and instant. Reduce Motion disables travel animation.

Tap to flip, or drag and release toward an endpoint. A flick uses its projected destination; a drag released on the original side emits no action. Cancellation returns to the current state. Zero-travel tracks still respond to taps.

Knob size is always 27/31 of the themed track height. Radii clamp to half their respective sizes. Curved track caps are round when trackRadius is within 0.5 pt of half the track thickness, otherwise they have sharp radial ends; intermediate curved fillets are not supported. Straight tracks honor intermediate radii. Give long or deeply curved tracks enough grid space to avoid clipping.

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