# button

## Overview

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

{% hint style="info" %}
**Version Compatibility**

`button` v3 was introduced in version **4.70.0** of the JourneyApps Runtime.
{% endhint %}

{% hint style="success" %}
`button` v3 replaces `button` [v1](https://docs.journeyapps.com/legacy-docs/ui-components/button-v1-deprecated) and [v2](https://docs-beta.journeyapps.com/legacy-docs/ui-components/button-v2-deprecated), which have been deprecated.

Note that `button` v1 styling will be applied to [`menu`](https://docs.journeyapps.com/legacy-docs/ui-components/menu-deprecated) buttons if the *Buttons 2.0* feature flag is not enabled.
{% endhint %}

### Basic Example

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

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-04af7d6325137e804fa0b1f62e83241d35a301c1%2Fbutton-example.png?alt=media)

## 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 [icons](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/icons "mention")for details.

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

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-ca05c88313ef2ea6a56db510ca24701c5feb5c54%2Fbutton-with-icon.png?alt=media)

### `label`

{% content-ref url="../xml-fields/label" %}
[label](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label)
{% endcontent-ref %}

### `on-press`

{% content-ref url="../xml-fields/on-press" %}
[on-press](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/on-press)
{% endcontent-ref %}

### `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`](#on-press) action.

## Advanced Attributes

### `align-content`

{% content-ref url="../xml-fields/align-content" %}
[align-content](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/align-content)
{% endcontent-ref %}

### `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`](#style) button; border and text color of an [`outline`](#style) button.

{% hint style="info" %}
**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.&#x20;

For example, this button:&#x20;

`<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.&#x20;

To override the button's text color, set the [`text-color`](#text-color) attribute.

{% endhint %}

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

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

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-851cf1dd14843504bd1c498f0a8146dd75b8f405%2Fbutton-with-custom-color.png?alt=media)

### `disabled`

{% content-ref url="../xml-fields/disabled" %}
[disabled](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/disabled)
{% endcontent-ref %}

### `disabled-message`

**Optional**

**Type**: `string`

**Default:** unset

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

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

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

function save() {
    // save logic
}
```

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-c6b17077f73cd12288fd954a13a6145e92281602%2Fbutton-disabled-message.png?alt=media)

### `id`

{% content-ref url="../xml-fields/id" %}
[id](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/id)
{% endcontent-ref %}

### `icon-color`

**Optional**

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

**Default**: The button's [`text-color`](#text-color)

Specify the color of the button's icon.

{% hint style="info" %}
When using `icon-color` with image assets, a color mask will be applied to the icon will remove any color variation in the image.
{% endhint %}

### `icon-position`

{% content-ref url="../xml-fields/icon-position" %}
[icon-position](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/icon-position)
{% endcontent-ref %}

### `label-case`

{% content-ref url="../xml-fields/label-case" %}
[label-case](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/label-case)
{% endcontent-ref %}

### `loading`

**Optional**

**Type**: `boolean`

**Default**: unset

{% hint style="warning" %}
This feature requires asynchronous state management, take care when using it.
{% endhint %}

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.

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

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-1ece48ea1767d580227163b7fd850d7e772be9e9%2Fbutton-loading.png?alt=media)

### `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`](https://docs.journeyapps.com/reference/app-features/calling-js-functions-from-xml) or [navigation](https://docs.journeyapps.com/reference/get-started/journeyapps-fundamentals/view-navigation). See more details:

{% content-ref url="../js-ts-events" %}
[js-ts-events](https://docs.journeyapps.com/reference/build/ui-components/js-ts-events)
{% endcontent-ref %}

{% code title="main.view\.xml" %}

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

{% endcode %}

{% code title="main.js" %}

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

{% endcode %}

{% hint style="info" %}
**Note**: The `on-long-press` function will call validation (as specified by the [`validate`](#validate) attribute) if set.
{% endhint %}

### `outline-button-background-color`

{% hint style="info" %}
**Version compatibility**

`outline-button-background-color` was introduced in version **4.86.1** of the JourneyApps Runtime.
{% endhint %}

**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`](#style) is set to `outline`.

<figure><img src="https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2FmEKbFQ09GAbBObVdT2iX%2Fimage.png?alt=media&#x26;token=a68bf07a-e1b1-474f-9dba-41cb390b5ab5" alt=""><figcaption></figcaption></figure>

### `show-if` and `hide-if`

{% content-ref url="../xml-fields/show-if" %}
[show-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/show-if)
{% endcontent-ref %}

{% content-ref url="../xml-fields/hide-if" %}
[hide-if](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/hide-if)
{% endcontent-ref %}

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

{% hint style="info" %}
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.
{% endhint %}

#### Example: Solid vs Outline button

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

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-f22e7602c5e50bae4d88b90d91e16ad1a0edb0b7%2Fbutton-style.png?alt=media)

#### Example: Legacy `menu` button

{% hint style="info" %}
If the **Buttons v2** feature flag is not enabled, `menu` buttons will keep their [old style](https://docs.journeyapps.com/reference/build/ui-components/all-ui-components/broken-reference).
{% endhint %}

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

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-afb7b28759176a6be9e94a31c8b4f2739721a48c%2Fbutton-style-menu.png?alt=media)

### `text-color`

**Optional**

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

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

#### Example: Solid button with custom text color

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

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-795809988e240045d7dced209337eb1b78d45d5b%2Fbutton-with-custom-text-color.png?alt=media)

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

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

![](https://2865107717-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9TCHLR67eLHBOjPvHhud%2Fuploads%2Fgit-blob-0f481f673f2efdaec3a93ee6c55cc53c6a3bf1ac%2Fbutton-type-primary.png?alt=media)

## Component Methods

The following component methods are available when an [`id`](https://docs.journeyapps.com/reference/build/ui-components/xml-fields/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.