Links

button

Overview

Buttons allow users to perform actions and navigate with a single click.
Version Compatibility
button v3 was introduced in version 4.70.0 of the JourneyApps Runtime.
button v3 replaces button v1 and v2, which have been deprecated.
Note that button v1 styling will be applied to menu buttons if the Buttons 2.0 feature flag is not enabled.

Basic Example

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

Standard Attributes

label

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. The icon can be a Font Awesome icon, an Ionicons icon or an icon or image asset.
<button label="Button with Icon" icon="fa-star" on-press="$:doSomething()"/>

on-press

validate

Optional
Type: boolean
Default: false
Set to true to ensure that no required input fields in the current view are empty before performing the on-press action.

Advanced Attributes

align-content

color

Optional
Type: string
Default: primary
The main color of the button.
The color attribute can be a named color or #HEX value.
For named colors, the corresponding named text-color will be used. In other cases a high contrasting color will be automatically selected. To override, set the text-color.
<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
}

icon-color

Optional
Type: string
Default: button's text-color
Specify the color of the button's icon. The icon-color attribute can be a named text-color or #HEX value.
When using icon-color with image assets, a color mask will be applied to the icon will remove any color variation in the image.

icon-position

label-case

loading

Optional
Type: boolean
Default: unset
This feature requires asynchronous state management, take care when using it.
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:
main.view.xml
<button label="Submit" on-long-press="$:submitForm(current_form)" />
main.js
function submitForm(currentForm) {
// Add logic here
// Could be a navigation call, e.g.
// navigate.link("submit_form", currentForm)
}
Note: The on-long-press function will call validation (as specified by the validate attribute) if set.

outline-button-background-color

Version compatibility
outline-button-background-color was introduced in version 4.86.1 of the JourneyApps Runtime.
Optional
Type: string
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

style

Optional
Type: solid | outline
Default: solid
Button style conveys importance of a button to the user, and can be set to solid or outline.
Good UX practice is to only have one primary call-to-action on a view. Carefully select the most important action on your view and make that a `solid` button, for example the Submit action on a confirm dialog.

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

If the Buttons v2 feature flag is not enabled, menu buttons will keep their old style.
<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
Default: If named color, defaults to the -text counterpart of the named color, or for custom colors the best contrasting color.
Specify the color of the button's label and sub-text. The text-color attribute can be a named text-color, e.g. text-color="negative-text" or a #HEX value.

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" />