Button
The Button block renders a clickable button that runs actions when pressed. It has three behaviors — Default (runs your wired interactions), Submit, and Reset (which act on a Form block you select). Its label is bindable and translatable, with full appearance control: color, size, variant, start/end icons, and reactive Loading and Disabled conditions. Two add-ons extend it — a Tooltip on hover and Google reCAPTCHA verification.
Tip: When to use Button: Trigger any action on click — API call, modal, navigation, automation — with Behavior = Default. To submit or reset a form, set Behavior = Submit or Reset. For icon-only controls, use Icon Button. For related actions as one unit, use Button Group.
Properties
Content
| Property | Type | Default | Description |
value | string | Button | The text shown on the button. Bindable, translatable, expression-friendly. |
type | "default" | "submit" | "reset" | default | The button's behavior. Default runs your interactions; Submit and Reset act on a Form block. |
formBlockId | block reference | — | Appears when type = submit or reset. (optional) The Form block this button submits or resets. |
interactions | event → action list | — | Appears when type = default. (optional) Events and actions to run on click. |
addOns.tooltip | string | — | Text shown in a tooltip when the user hovers the button. |
addOns.reCaptchaSiteKey | string | — | Site key from Google reCAPTCHA admin console. Gates the click behind a challenge. |
addOns.reCaptchaVersion | "reCaptchaV3" | "reCaptchaV2" | reCaptchaV3 | V3 runs invisibly; V2 may show a challenge on failure. |
Appearance
| Property | Type | Default | Description |
color | button color token | brand | The button's color scheme. |
size | button size token | md | The button's size. |
variant | button variant token | solid | The button's fill style — solid, outline, or theme-defined styles. |
startDecorator | icon name | — | Icon at the start (left) of the label. Bindable and conditional. |
endDecorator | icon name | — | Icon at the end (right) of the label. Bindable and conditional. |
loading | condition | — | When true, shows a spinner and disables clicking. |
disabled | condition | — | When true, the button is greyed out and not clickable. |
styles | style set | w-fit | Width, flex layout, margin, radius, visibility, rotation. |
Events
| Event | Trigger | Available when |
On Click | User clicks or taps the button | Always |
On Mouse Enter | Pointer enters the button | Web / desktop only |
On Long Press | User presses and holds | Mobile / tablet only |
Methods
| Method | Payload | Effect |
Set Disabled | { disabled: boolean } | Enables or disables the button at runtime, overriding the Disabled condition. |
Exposed State
| State key | Type | Description |
{{ id.content.value }} | string | The button label after bindings resolve. |
{{ id.content.type }} | string | The active behavior (default, submit, reset). |
{{ id.appearance.* }} | object | Color, size, variant, disabled, loading, and other appearance values. |
{{ id.reCaptchaToken }} | string | The verification token — populated only after a successful reCAPTCHA challenge. |
Behavior & Gotchas
Warning: reCAPTCHA, hover, and long press don't work in a mobile app. On native mobile, the button falls back to a plain click. On Mouse Enter, On Long Press, the Tooltip add-on, and reCAPTCHA are web-only.
Warning: Set Disabled wins over your Disabled condition. Once Set Disabled runs, the button's disabled state is fixed to that boolean and ignores the Disabled condition until Set Disabled is called again.
Note: With reCAPTCHA on, the first click verifies — it does not run your action yet. The button shows a spinner, the challenge runs, and only after a token is returned does On Click fire. Later clicks fire immediately using the cached token.
Note: Submit and Reset do nothing until you pick a form. Without a form selected in "Form to submit / reset," clicking submits or resets nothing.
Note: A long press swallows the following click. On mobile, after a long press fires, the click that would follow is suppressed — you won't get both events from one gesture.
Examples
Button Group
The Button Group block renders a set of related buttons as one unit, in one of three types: Default (buttons side by side, each with its own click action), Dropdown (a single button that opens a menu of options), and Toggle (a segmented control where exactly one option stays selected). Buttons come from a Manual list or are Mapped from a data source.
Tip: When to use Button Group: Offer a small set of related actions together (approve / reject / escalate), collapse many actions behind one dropdown button, or build a view switcher toggle. For a single action, use the Button block.
Properties
Content
| Property | Type | Default | Description |
mode | "manual" | "mapped" | manual | Manual builds buttons by hand; Mapped generates them from bound data. |
type | "default" | "dropdown" | "toggle" | default | Side-by-side, a dropdown menu, or a toggle (segmented) control. |
text | string | Menu | Dropdown only. (optional) The label on the dropdown trigger button. |
options (Buttons) | button list | data binding | Three sample buttons | Manual: a list you add to; Mapped: a data source with Id and Label mappings. |
initialSelectedItemId | string | — | Toggle only. (optional) Which toggle option starts selected. Falls back to the first button. |
Per-Button Settings (Manual mode)
Each button in the Manual list opens its own detail panel with: Label, Start/End Icons, Tooltip, Loading and Disabled conditions, On Click interactions, Visibility, and Permissions.
Appearance
| Property | Type | Default | Description |
color | color | brand | Button color for the whole group. |
size | size | md | Button size for the whole group. |
variant | variant | solid | Visual style; Toggle type offers solid and outline only. |
popup.styles | style set | max-h 400px, scroll | Dropdown only. (optional) Width/height/overflow of the dropdown menu. |
styles | style set | w-fit | Width/height, flex layout, visibility. |
Events
| Event | Trigger | Available when |
On Click (per button) | That button is clicked | Manual mode — on each button's detail panel |
On Click (block) | Any button in the group is clicked | Mapped mode — under Content → Interactions |
Methods
| Method | Params | Effect | Available when |
toggleButton | buttonId | Selects the given toggle option programmatically | type = toggle |
Exposed State
| State key | Type | Description |
{{ id.selectedOptionId }} | string | Id of the last-clicked button or current toggle selection. |
{{ id.selectedOption.label }} | string | Label of the last-clicked button. |
{{ id.context.item }} | object | The data item behind the clicked button (Mapped mode). |
Behavior & Gotchas
Warning: A toggle group selects a button on page load — and fires its On Click. The auto-selection fires the first button's On Click actions on every page load. Avoid placing load-sensitive logic (navigation, mutations) on the first toggle button.
Warning: The whole block disappears when no buttons survive. If every button is hidden by visibility or permissions, or a Mapped group's data is empty, the block renders nothing at all.
Note: Mapped buttons render only after you map the Id. Binding data alone is not enough — until the Id mapping is set, the block treats the list as empty. Map both Id and Label.
Note: The toggleButton method changes selection silently. It updates state but does not fire that button's On Click actions. It also records the button's id as the selectedOption.label until the user clicks.
Examples
Related Blocks
| Block | Relationship |
| Icon Button | An icon-only button — use when there's no text label. |
| Menu | Richer standalone menu when you need sections or nesting. |
| Link | Navigational text styled as an anchor rather than a button. |
| Floating Action Button | A persistent floating primary action, typically on mobile. |
| Swipeable Button | A slide-to-confirm control for deliberate or destructive actions. |
Frequently Asked Questions
What is the difference between a Default and Submit button type?
A Default button fires its On Click event when pressed — it has no special relationship to a form. A Submit button, when paired with a Form block via the formBlockId property, triggers that form's validation before firing On Submit. If the form is invalid, the submit is blocked and validation errors are shown. Use Submit inside forms and Default for standalone actions like opening a modal or calling a data source.
Can I enable or disable a button from an automation?
Yes. The Button block exposes a Set Disabled method callable via the Control Block Method action. Pass true to disable it, false to re-enable. You can also drive disabled state reactively by binding the Disabled property to a boolean expression like {{ !form1.isValid }}.
How do I make a Button Group behave like a tab selector?
Set the Button Group Type to Toggle (Segmented) and Mode to Manual. Add the option items you want as tabs. The {{ id.selectedToggleButton }} state exposes the currently selected option's value, which you can use to conditionally show sections or drive a Navigation Container.
When should I use a Dropdown button group instead of a plain Menu block?
Use a Dropdown button group when you want a primary action with secondary overflow actions, all grouped under one trigger button with a chevron. Use a Menu block when you need a standalone list of actions independent of any button — for example, a contextual right-click menu or an actions column in a table row.
What does the reCAPTCHA token state expose, and when does it update?
When the reCAPTCHA add-on is enabled, clicking the button triggers a reCAPTCHA challenge. On successful completion, {{ id.reCaptchaToken }} is populated with a token string. This token is reset when the button is clicked again. Pass it to your backend via the On Click or On reCAPTCHA Verified event to verify the challenge server-side before processing the action.