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

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

label

pagelabel

on-press

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

pagealign-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 text color

When using named colors (i.e. primary, secondary, positive, negative, etc) the corresponding named _text color will be used as the button's text color.

For example, this button:

<button label="My button" color="secondary" on-press="$:doSomething()"/>

Will use the theme's secondary_text named color for the button text.

When using a #HEX value, a high contrasting color will automatically be selected for the button's text color.

To override the button's text color, set the text-color attribute.

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

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

disabled

pagedisabled

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

pageid

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.

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

pageicon-position

label-case

pagelabel-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:

pageJS/TS Events

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

pageshow-ifpagehide-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.

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