Buttons & Actions
Button
A simple rectangular button used across builder screens. It supports five action modes and intentionally executes actions only in preview/runtime so the builder canvas remains safe for selecting and dragging components.
One component covers static, messaging, routing, external link, and back behaviors.
Actions run only when isPreview=true, never on static canvas editing mode.
Keep BuilderButton.tsx, registry props, and componentDimensions.ts aligned.
Four things worth knowing
Simple text-first action block
Renders a customizable rectangular button label with editable colors, border settings, typography, and sizing controls.
Five built-in action types
Supports none, alert, navigate-screen, open-url, and go-back via onPressAction.
Preview-only execution safety
Press actions are intentionally disabled in builder editing mode to prevent accidental navigation or URL opens while arranging components.
Canvas sizing must stay in sync
Drag box dimensions come from calculateComponentDimensions(‘button’, …), so sizing logic there must match the rendered button.
Code map: component logic in BuilderButton.tsx, builder-editable config in registry key button, and drag sizing in componentDimensions.ts case ‘button’.
Find it, drop it, wire the action
Where to find itAdd it to any actionable screen area
- Open the Builder component picker.
- Go to Buttons & Actions → Button.
- Drop it where the user should take the main next step.
Action wiringThree common setups
- Internal navigation:
onPressAction=navigate-screenandactionData=<targetScreenId>. - External URL:
onPressAction=open-urlandactionData=https://…. - Back behavior:
onPressAction=go-backto use runtime back stack.
Editable content, visuals, sizing, and behavior
| Prop | Type | Default | Description |
|---|---|---|---|
text | string | Registry default | Main visible button label text. |
backgroundColor, textColor, borderColor, borderWidth, borderRadius, fontFamily, fontSize | style | Registry defaults | Visual styling for fill, text, border, radius, and typography. |
widthPercent, height | number / select | 100, preset | Sizing controls for width (10–100) and preset height options. |
onPressAction, actionData | select / string | none, empty | Action type and its payload (screen ID, URL, or alert text). |
isPreview, onScreenNavigate, onGoBack | runtime | Injected | Preview guard and callbacks used by action execution logic. |
Make it yours
The button is intentionally lightweight. Most customization comes from text, colors, border styling, width percentage, and preset height selection.
| Prop | Default | What it controls |
|---|---|---|
backgroundColor, textColor | Registry defaults | Primary visual contrast and readability of the action. |
borderColor, borderWidth, borderRadius | Registry defaults | Button edge style, outline weight, and corner shape. |
fontFamily, fontSize | Registry defaults | Typography tone and emphasis for CTA label text. |
widthPercent | 100 | Button width scale from compact actions to full-width CTAs. |
height | Preset | Tap target height via allowed builder preset options. |
Common mistakes to avoid
Button press does nothing on canvas
Expected behavior: actions are intentionally disabled outside preview mode to keep builder editing safe.
navigate-screen not working
Verify actionData contains a valid target screen ID and that runtime navigation callback is available.
Visual size and drag box mismatch
Check componentDimensions.ts button width/height calculations and keep them aligned with button render sizing.
Keep code changes synced
If props change in BuilderButton.tsx, update registry defaultProps/propDefinitions and keep button dimensions logic in sync.