Digia StudioDiscordLinkedIn

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.

A hero image showing various styled buttons in an application UI.
The Button widget is a versatile component for creating interactive elements.

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.

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.

A side-by-side comparison of a button in its default (enabled) and disabled states.
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.

A GIF showing how to use the 'Button State' toggle in the properties panel to preview the disabled state.
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., ${!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 different button styles: Solid, Outline, and Text-only.
Examples of Solid, Outline, and Text button variants created using the Button widget.

Default Properties

The Button widget supports all Default Properties, such as Visibility and Alignment (for positioning the button itself within a parent).

Best Practices

  • Clear Call to Action: Use a concise and action-oriented label for the Text property (e.g., "Sign Up", "Add to Cart").

  • Provide Visual Feedback: Always define distinct styles for the Disabled State to clearly communicate when a button is not interactive.

  • Use Icons Wisely: Add icons to reinforce meaning (e.g., a trash can icon on a "Delete" button), but don't rely on them alone without a text label.

  • Dynamic Disabling: Bind the Is Disabled property to expressions to create robust forms. For example, disable a login button with ${email.value.isEmpty || password.value.isEmpty}.

PreviousRich TextNextImage

Last updated