Button

The Button widget is a fundamental interactive element that allows users to trigger actions within your application. It provides extensive customization options for appearance, states, and behavior, making it suitable for various use cases from simple navigation to complex form submissions.

Adding a Button Widget

The Button widget is located in the Base Elements section of the Widget Palette. Once added, you can configure its properties from the Widget Properties Panel.

The Button widget is a versatile component for creating interactive elements.

Use Cases

You’ll typically use Button for:

• Primary Actions

  • Submit a form (Sign Up, Log In, Save)

  • Proceed in a flow (Next, Continue, Get Started)

  • Main CTA on a screen (Checkout, Book Now, Start Free Trial)

• Secondary / Tertiary Actions

  • Cancel, Skip, Dismiss, Close

  • “Maybe later”, “Remind me”, “View details”

  • Less-important side actions next to the main CTA

• Navigation

  • Go to another screen (View All, See More, Open Settings)

  • Open modals, sheets, or overlays

  • Trigger deep links, external URLs, or app sections

• State-Changing Actions

  • Add to Cart, Add to Wishlist, Follow / Unfollow

  • Enable / Disable a setting

  • Start / Stop / Retry an operation

• Contextual Quick Actions

  • Apply filters, Refresh data, Retry on error

  • Download, Share, Copy, Edit, Delete

Core Concept: Button States

A button's appearance and behavior change based on its state. Understanding these states is key to creating a good user experience.

• Default State: The normal, interactive state of the button. This is how it appears most of the time.

• Disabled State: A non-interactive state, visually indicating that the button cannot be pressed. This is controlled by the Is Disabled boolean property. For example, you can disable a "Submit" button until all required form fields are filled.

Visual difference between the Default and Disabled states of a button.

Previewing States in the Builder: The properties panel includes a Button State toggle. This is a design-time tool only; it has no effect on your running app. Use it to switch the view on the canvas between the Default and Disabled styles while you are designing.

Use the Button State toggle to preview different states in the builder.

---

Properties

The Button's properties are grouped by function.

Interaction & State

Property	Description
On Click	Defines the action that executes when a user clicks the button. This is the most important property for making the button functional.
Is Disabled	A boolean (true/false) that controls the button's state. When true, the button will be non-interactive and use the Disabled State styling. This can be bound to an expression, e.g., ${not(form.isValid)}.

Important Note: The Button widget is stateless. This means it does not manage its own disabled state internally. You are responsible for controlling the Is Disabled property using an external state variable (e.g., from App State or a State Container).

Content

These properties define what is displayed inside the button.

Property	Description
Text	The text label displayed on the button. Can be a static value or a dynamic expression.
Leading Icon	An icon displayed before the text. See the Icon documentation for configuration options.
Trailing Icon	An icon displayed after the text. See the Icon documentation for configuration options.

Styling

Styling is configured separately for the Default and Disabled states, allowing you to provide clear visual feedback to the user.

Default State Styling

These properties control the button's appearance in its normal, interactive state.

Property	Description
Button Color	The background color of the button.
Elevation	Creates a shadow effect to give the button depth.
Shadow Color	The color of the elevation shadow.
Text Style	Controls the font styling for the button's text. This works exactly like the Text widget's styling (Linked vs. Unlinked).

Disabled State Styling

These properties are applied when Is Disabled is true.

Property	Description
Button Color	The background color of the button when disabled. Typically a lighter or grayer version of the default color.
Text Color	The color of the button's text when disabled.
Icon Color	The color of the button's icons when disabled.

Shape & Layout

These properties control the button's overall shape and internal spacing.

Property	Description
Shape	Defines the button's geometric shape. Options include Stadium, Circle, and RoundedRect.
Border Radius	Controls corner rounding when Shape is set to RoundedRect.
Border Style	Defines the border appearance (e.g., Solid or None).
Border Color	Sets the color of the border.
Border Width	Controls the thickness of the border.
Width / Height	The dimensions of the button. Can be fixed (px) or responsive (%).
Padding	Internal spacing around the button's content (text and icons).
Alignment	Controls how the content (text and icons) is aligned within the button.

---

Common Button Variants

The Button widget is flexible enough to create all standard button types by combining its styling properties.

• Solid Button (Default): This is the standard appearance. Set a Button Color and a Text Style with a contrasting color.

• Outline Button: To create a button with a transparent background and a colored border, set the Button Color to transparent, and define the Border Style, Border Color, and Border Width.

• Text Button: For a button that looks like a simple text link, set the Button Color to transparent and set Border Style to None. The clickable area will still be defined by the button's Padding and dimensions.

Examples of Solid, Outline, and Text button variants created using the Button widget.

---

Default Properties

The Button widget supports all Default Properties.