button

Overview

Buttons allow users to perform actions and navigate with a single click.

Basic Example

<button label="Home" on-press="$:naviateHome()" icon="fa-home" validate="false" />

Standard Attributes

icon

Optional

Type: string

Default: unset

The icon to display on the button, it will be placed on the left of the label by default. You can use icons from various sources - see iconsfor details.

<button label="Button with Icon" icon="fa-star" on-press="$:doSomething()"/>

label

on-press

validate

Optional

Type: boolean

Default: true

When set to true this attribute ensures that all required input fields in the current view are not empty before performing the on-press action.

Advanced Attributes

align-content

color

Optional

Type: string- can be a named color or #HEX value

Default: primary

The main color of the button: Background color of a solid button; border and text color of an outline button.

<button label="Custom Color" color="$:getColor()" on-press="$:doSomething()"/>

function getColor() {
    return "#ffab00";
}

disabled

disabled-message

Optional

Type: string

Default: unset

Text to display in the notification bar when the user selects this disabled button.

<button label="Save" disabled="$:isDisabled()" disabled-message="Complete all fields before saving" on-press=":$saveForm()"/>

function isDisabled() {
    // logic here for checking all input
    return true;
}

function save() {
    // save logic
}

id

icon-color

Optional

Type: string- can be a named color or #HEX value

Default: The button's text-color

Specify the color of the button's icon.

icon-position

label-case

loading

Optional

Type: boolean

Default: unset

Controls whether the button is in a loading state. A loading spinner will appear on the button and will not be clickable while in loading state.

<button label="Home" loading="true" icon="fa-home" on-press="$:naviateHome()" />

on-long-press

Optional

Default: unset

Triggered when: The user clicks and holds the button

Event parameter: Empty by default. Can be a user-defined variable or field.

Return value: undefined, or the user-defined variable or field.

on-long-press is an event that calls a JS/TS $:function or navigation. See more details:

<button label="Submit" on-long-press="$:submitForm(current_form)" />

function submitForm(currentForm) {
    // Add logic here
    // Could be a navigation call, e.g. 
    // navigate.link("submit_form", currentForm)
}

outline-button-background-color

Optional

Type: string - can be a named color or #HEX value

Default: Light theme: white; Dark theme: #1b262a

Specify the background color of the button if its style is set to outline.

show-if and hide-if

subtext

Optional

Type: string

Default: unset

Text to display below the button label.

style

Optional

Type: solid | outline

Default: solid

Set the style of the button to convey its importance to the user. style can be set to solid or outline, where solid buttons typically show a higher importance.

Example: Solid vs Outline button

<button label="Home" icon="fa-home" on-press="$:naviateHome()" validate="false" />
<button label="Home" style="outline" icon="fa-home" on-press="$:naviateHome()" validate="false" />

Example: Legacy menu button

<menu>
    <button label="Menu item 1" icon="fa-car" subtext="Subtext"  />
    <button label="Menu item 2" icon="fa-bomb" subtext="Subtext" />
    <button label="Menu item 3" icon="fa-bath" subtext="Subtext" />
</menu>

text-color

Optional

Type: string - can be a named color or #HEX value

Default: If the button's color is a named color, its text color defaults to the _text counterpart of the named color. If the button's color is a #HEX value, its text color defaults to a high contrasting color.

Example: Solid button with custom text color

<button label="Submit" text-color="#ffff00" on-press="$:doSomething()"/>

type

Optional

Type: normal | primary

Default: normal

Setting type="primary" will cause the button to be displayed at the bottom of the view regardless of where it was defined.

Example: Primary button

<button label="Home" type="primary" icon="fa-home" on-press="$:naviateHome()" validate="false" />

Component Methods

The following component methods are available when an id is assigned to the component and component.button({id:'my-id'}) is called from JS/TS:

fireAction

Programmatically fire the button action.

scrollIntoView

Programmatically scroll until the button is visible in the view.