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
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
Field
Type
Default
What it does
Titlelabel
text
Button
The words on the button
Sets the text shown on the button; empty shows the control id.
Symbolicon
text
—
A small picture beside the words
Draws the chosen SF Symbol before the label, or alone with Symbol only.
Lookstyle
choiceone of 6
filled
How the button is dressed
Switches the button between a solid fill, an outline, a faint tint, or just the symbol.
filleddefaultsolid 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
Sizesize
choiceone of 3
default
How big the button is
Scales the button's height and text between compact, normal and large.
compactsmall and tight, for crowded grids
defaultdefaultthe normal size
largetall and roomy, easy to hit
Colortint
color
#667eea
The button's main color
Recolors the fill, border or text (per Look) to the chosen color.
Symbol onlyhideLabel
on / off
false(off)
Hide the words, keep the picture
When on, the label text disappears and only the symbol remains.
Vibration on taphaptic
choiceone of 7
medium
How the tap feels
Plays the chosen buzz on the phone each time the button is pressed.
lighta faint tick
mediumdefaulta 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 heldrepeatOnHold
on / off
false(off)
Keep going while held
Holding the button refires its action repeatedly, speeding up the longer you hold.
Words for valuesvalueMap
object
—
Different words for different states
Replaces the label with the text matching the synced value, e.g. true shows Pause.
Symbols for valuesiconMap
object
—
Different pictures for different states
Swaps the symbol to the one matching the synced value, with a replace animation.
Colors for valuescolorMap
object
—
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
Field
Type
Default
What it does
Corner roundnesstheme.cornerRadius
number0–30 ptstep 1
12
Color of the words and symbol
Colors the border drawn around the button.
Border thicknesstheme.borderWidth
number0–5 ptstep 0.5
1
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
Sends
When
Type
What it sends
When you tap itpress
tap
string
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
Takes
From
Type
What it does
valueshow
hub, mqtt, http, store, default
string
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.