What's NewDeveloper CommunitySupportStatus
Search
⌃K
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

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

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

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.
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 - 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.
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.
Previous
actionSheet
Next
button-group
Last modified 3mo ago