# 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.

{% embed url="<https://www.youtube.com/watch?v=1YTW48viT_0>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=1YTW48viT_0>

#### 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**.

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-b8eec687880ffac9269241c7d83b0a93ac340f30%2Fbutton_hero_image.jpg?alt=media" alt="A hero image showing various styled buttons in an application UI."><figcaption><p>The Button widget is a versatile component for creating interactive elements.</p></figcaption></figure>

### 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.

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-adf3e210ebc8b2ec49ed1e82f7a85a0be4114ac2%2Fbutton_default_vs_disabled.jpg?alt=media" alt="A side-by-side comparison of a button in its default (enabled) and disabled states."><figcaption><p>Visual difference between the <code>Default</code> and <code>Disabled</code> states of a button.</p></figcaption></figure>

{% hint style="info" %}
**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.
{% endhint %}

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-ef3efaaeab0b21c3666d70b973ebdbe7f5f0f4cf%2Fbutton_preview_state.gif?alt=media" alt="A GIF showing how to use the &#x27;Button State&#x27; toggle in the properties panel to preview the disabled state."><figcaption><p>Use the <code>Button State</code> toggle to preview different states in the builder.</p></figcaption></figure>

***

### Properties

The Button's properties are grouped by function.

#### Interaction & State

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

{% hint style="warning" %}
**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).
{% endhint %}

#### Content

These properties define what is displayed inside the button.

<table><thead><tr><th width="176.25390625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Text</code></td><td>The text label displayed on the button. Can be a static value or a dynamic expression.</td></tr><tr><td><code>Leading Icon</code></td><td>An icon displayed before the text. See the <a href="broken-reference">Icon documentation</a> for configuration options.</td></tr><tr><td><code>Trailing Icon</code></td><td>An icon displayed after the text. See the <a href="broken-reference">Icon documentation</a> for configuration options.</td></tr></tbody></table>

#### 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.

<table><thead><tr><th width="176.25390625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Button Color</code></td><td>The background color of the button.</td></tr><tr><td><code>Elevation</code></td><td>Creates a shadow effect to give the button depth.</td></tr><tr><td><code>Shadow Color</code></td><td>The color of the elevation shadow.</td></tr><tr><td><code>Text Style</code></td><td>Controls the font styling for the button's text. This works exactly like the <a href="broken-reference">Text widget's styling</a> (Linked vs. Unlinked).</td></tr></tbody></table>

#### Disabled State Styling

These properties are applied when `Is Disabled` is `true`.

<table><thead><tr><th width="176.25390625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Button Color</code></td><td>The background color of the button when disabled. Typically a lighter or grayer version of the default color.</td></tr><tr><td><code>Text Color</code></td><td>The color of the button's text when disabled.</td></tr><tr><td><code>Icon Color</code></td><td>The color of the button's icons when disabled.</td></tr></tbody></table>

#### Shape & Layout

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

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

***

### 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.

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-f02e78bbca1080a57075204c627d21beebf81cde%2Fbutton_variants.jpg?alt=media" alt="Examples of different button styles: Solid, Outline, and Text-only."><figcaption><p>Examples of Solid, Outline, and Text button variants created using the Button widget.</p></figcaption></figure>

***

### Default Properties

The Button widget supports all [default-properties](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention").

### 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