---
title: "button"
description: "Overview"
permalink: /docs/build/ui-components/all-ui-components/button/
---
# button

## Overview

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

<Info title={"Version Compatibility"}>

`button` v3 was introduced in version **4.70.0** of the JourneyApps Runtime.

</Info>

<Info>

`button` v3 replaces the deprecated `button` v1 and v2 implementations.

Note that `button` v1 styling will be applied to `menu` buttons if the *Buttons 2.0* feature flag is not enabled.

</Info>

### Basic Example

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

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-04af7d6325137e804fa0b1f62e83241d35a301c1-2fbutton-example-909a035f.png)

## Standard Attributes

### `icon`

<SyntaxCard type={"string"} defaultValue={"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](/docs/build/ui-components/all-ui-components/icons/) for details.

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

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-ca05c88313ef2ea6a56db510ca24701c5feb5c54-2fbutton-with-icon-ca4b59e1.png)

### `validate`

<SyntaxCard type={"boolean"} defaultValue={"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

### `color`

<SyntaxCard type={"string (named color or #HEX value)"} defaultValue={"primary"} />

The main color of the button: Background color of a [`solid`](#style) button; border and text color of an [`outline`](#style) button.

<Info title={"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`](#text-color) attribute.

</Info>

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

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

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-851cf1dd14843504bd1c498f0a8146dd75b8f405-2fbutton-with-custom-color-df5b7f0a.png)

### `disabled-message`

<SyntaxCard type={"string"} defaultValue="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="$:save()" />
```

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

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

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-c6b17077f73cd12288fd954a13a6145e92281602-2fbutton-disabled-message-cdcf03ac.png)

### `icon-color`

<SyntaxCard type={"string (named color or #HEX value)"} defaultValue={"The button's text-color"} />

Specify the color of the button's icon.

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

</Info>

### `loading`

<SyntaxCard type={"boolean"} defaultValue={"unset"} />

<Warning>

This feature requires asynchronous state management, take care when using it.

</Warning>

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="$:navigateHome()" />
```

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-1ece48ea1767d580227163b7fd850d7e772be9e9-2fbutton-loading-b3373406.png)

### `on-long-press`

<SyntaxCard defaultValue={"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`](/docs/app-features/calling-js-functions-from-xml/) or [navigation](/docs/get-started/journeyapps-fundamentals/view-navigation/). See more details:

- [js ts events](/docs/build/ui-components/js-ts-events/)

**main.view\.xml**

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

**main.js**

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

<Info>

**Note**: The `on-long-press` function will call validation (as specified by the [`validate`](#validate) attribute) if set.

</Info>

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

<SyntaxCard type={"string (named color or #HEX value)"} defaultValue={"Light theme: white; Dark theme: #1b262a"} introduced="4.86.1" />

Specify the background color of the button if its [`style`](#style) is set to `outline`.

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fmekbfq09gabbobvdt2ix-2fimage-777521a7.png)

### `subtext`

<SyntaxCard type={"string"} defaultValue={"unset"} />

Text to display below the button label.

### `style`

<SyntaxCard type={["solid","outline"]} defaultValue={"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.

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

</Info>

#### Example: Solid vs Outline button

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

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-f22e7602c5e50bae4d88b90d91e16ad1a0edb0b7-2fbutton-style-a6a2a67f.png)

#### Example: Legacy `menu` button

<Info>

If the **Buttons v2** feature flag is not enabled, `menu` buttons will keep their [old style](/docs/build/ui-components/all-ui-components/broken-reference/).

</Info>

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

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-afb7b28759176a6be9e94a31c8b4f2739721a48c-2fbutton-style-menu-adc583f7.png)

### `text-color`

<SyntaxCard type={"string (named color or #HEX value)"} defaultValue={"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

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

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-795809988e240045d7dced209337eb1b78d45d5b-2fbutton-with-custom-text-color-995e3b26.png)

### `type`

<SyntaxCard type={["normal","primary"]} defaultValue={"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="$:navigateHome()" validate="false" />
```

![](./media/spaces-2f9tchlr67elhbojpvhhud-2fuploads-2fgit-blob-0f481f673f2efdaec3a93ee6c55cc53c6a3bf1ac-2fbutton-type-primary-8e746088.png)

### `align-content`

<AttributeReference label="align-content" href="/docs/build/ui-components/common-attributes/align-content/" badge="advanced" tone="muted" />

### `disabled`

<AttributeReference label="disabled" href="/docs/build/ui-components/common-attributes/disabled/" badge="advanced" tone="muted" />

### `id`

<AttributeReference label="id" href="/docs/build/ui-components/common-attributes/id/" badge="advanced" tone="muted" />

### `icon-position`

<AttributeReference label="icon-position" href="/docs/build/ui-components/common-attributes/icon-position/" badge="advanced" tone="muted" />

### `label-case`

<AttributeReference label="label-case" href="/docs/build/ui-components/common-attributes/label-case/" badge="advanced" tone="muted" />

### `show-if`

<AttributeReference label="show-if" href="/docs/build/ui-components/common-attributes/show-if/" badge="advanced" tone="muted" />

### `hide-if`

<AttributeReference label="hide-if" href="/docs/build/ui-components/common-attributes/hide-if/" badge="advanced" tone="muted" />

## Common Attributes

### `border-radius`

<AttributeReference label="border-radius" href="/docs/build/ui-components/common-attributes/border-radius/" badge="new" sinceVersion="5.1.0" />

### `label`

<AttributeReference label="label" href="/docs/build/ui-components/common-attributes/label/" />

### `on-press`

<AttributeReference label="on-press" href="/docs/build/ui-components/common-attributes/on-press/" />

## Component Methods

The following component methods are available when an [`id`](/docs/build/ui-components/common-attributes/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.