# Titanium.UI.Button

> A button widget that has four states: normal, disabled, focused and selected.

- Source: https://titaniumsdk.com/docs/sdk/13.0.1/Titanium.UI.Button
- Titanium SDK version: 13.0.1
- Kind: view
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 0.8
- Extends: Titanium.UI.View
- Inheritance: Titanium.UI.View > Titanium.Proxy

| Android | iOS |
| ------- | --- |
| ![Android](./button_android.png) | ![iOS](./button_ios.png) |

A button displays its  selected state while it is being pressed. The focused state is
only used on Android devices that have navigation keys or a keyboard, to indicate
which button has input focus.

You can specify background images for each state, as well as button text and a button
icon. On iOS, there are button styles which define appearance for each state, even if
no button images are set.

Use the [Titanium.UI.createButton](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createButton) method or a **`<Button>`** Alloy element to create a button
(see [Examples](#!/api/Titanium.UI.Button-examples)) .

#### Android Platform Notes

Android uses default button images for the normal, focused, selected and disabled
states. If you use a custom button image, you should specify versions for the focused
and selected states (and the disabled state, if the button is ever disabled).

Android also supports setting the background color for each of the states. These are not
supported on iOS.

The Material style introduced in Titanium SDK 10.0.0 will change the default look of the buttons.
You can change button styles with a custom theme as follows:
``` xml
<!-- Assign this custom theme to "tiapp.xml" file's android manifest application element. -->
<style name="Theme.MyTheme" parent="Theme.Titanium.Light">
    <item name="textAppearanceButton">@style/TextAppearance.MyButton</item>
    <item name="android:buttonStyle">@style/Widget.MyButton</item>
    <item name="buttonStyle">@style/Widget.MyButton</item>
</style>

<!-- Affects the appearance of text in all material buttons. -->
<style name="TextAppearance.MyButton" parent="TextAppearance.MaterialComponents.Button">
    <!-- Do not display button text in all-caps. -->
    <item name="android:textAllCaps">false</item>
    <!-- Remove extra spacing between characters. -->
    <item name="android:letterSpacing">0</item>
</style>

<!-- Affects the appearance of all non-material system buttons. -->
<style name="Widget.MyButton" parent="Widget.AppCompat.Button">
    <!-- Do not display button text in all-caps. -->
    <item name="android:textAllCaps">false</item>
    <!-- Remove extra spacing between characters. -->
    <item name="android:letterSpacing">0</item>
</style>
```

#### iOS Platform Notes

* When assigning a custom image to the `backgroundImage` property, the image must be
partially or wholly transparent for the background color or background gradient to be visible.
* Similarly, for an assigned background gradient to show through, the `backgroundColor` may need to be
set to 'transparent'.

Unlike Android, iOS doesn't supply any default background images for buttons--
system button styles serve this purpose.

The `systemButton` property lets you create a predefined system-defined button,
such as the **Camera** or **Add** buttons, for use in toolbars and nav bars.
Specifically, system buttons may be used in the following locations:

* [Titanium.UI.iOS.Toolbar](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.Toolbar.md). The `items` array can contain system buttons.
* [Titanium.UI.iPad.Popover](https://titaniumsdk.com/docs/sdk/Titanium.UI.iPad.Popover.md). The `leftNavButton` and `rightNavButton` properties can
  refer to system buttons
* [Titanium.UI.iOS.SplitWindow](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.SplitWindow.md). The `toolbar` array can contain system buttons.
* [Titanium.UI.TextField](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextField.md). The `keyboardToolbar` array can contain system buttons.
* [Titanium.UI.TextArea](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextArea.md). The `keyboardToolbar` array can contain system buttons.
* [Titanium.UI.Window](https://titaniumsdk.com/docs/sdk/Titanium.UI.Window.md). The `leftNavButton` and `rightNavButton` properties can refer to
  system buttons and the `toolbar` array can contain system buttons.

Use the constants in [Titanium.UI.iOS.SystemButton](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.SystemButton.md)
to specify a button type. The size, style and decoration of system buttons is set
automatically, so you can create a button by setting only the `systemButton` property.

For example:

``` js
var cancelButton = Ti.UI.createButton({ systemButton: Ti.UI.iOS.SystemButton.CANCEL });
```

In Alloy, you can omit the namespace when setting the `systemButton` property:

``` xml
<Button id="cancelbtn" systemButton="CANCEL"></Button>
```

Note that the `systemButton` property specifies *appearance*, not behavior. For
example, to bring up the camera when the user presses the **Camera** button, you must
add an event listener to the button and call [Titanium.Media.showCamera](https://titaniumsdk.com/docs/sdk/Titanium.Media.md#showCamera) when the
button is clicked.

##### iOS Pressed Button Effects

If you do not supply separate background images for the normal and selected states,
iOS supplies a built-in effect for pressed buttons. For most iOS buttons, the effect
dims the entire button (except for the text) while the button is being pressed.

For toolbar buttons that use the [PLAIN](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#BUTTON_STYLE_OPTION_NEUTRAL) style
or use system icons such as [CAMERA](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.SystemButton.md#CAMERA), a glow effect is
used. The glow effect shows as a white circular glow or highlight at the center of the button
when the button is pressed.

## Example: Simple Button Example

``` js
var win = Ti.UI.createWindow();
var button = Titanium.UI.createButton({
    title: 'Hello',
    top: 10,
    width: 100,
    height: 50
});
button.addEventListener('click',function(e)
{
    Titanium.API.info("You clicked the button");
});
win.add(button);
win.open();
```

## Example: Alloy XML Markup

Previous example as an Alloy view.

button.xml:
``` xml
<Alloy>
    <Window id="win" backgroundColor="white">
        <!-- The title property can also be defined as node text. -->
        <Button id="button" onClick="doClick" title="Hello"
            top="10" width="100" height="50" />
    </Window>
</Alloy>
```

button.js:
``` js
function doClick(e){
    Titanium.API.info("You clicked the button");
};
```

## Properties

### attributedString

- Type: Titanium.UI.AttributedString
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 7.5.0

Specify an attributed string for the label.

The underlying attributed string drawn by the label. If set, avoid setting common attributes
in the label, such as `color` and `font`, as unexpected behaviors may result.

iOS Note: This property can also be used to supress the underline style when accessibility
is enabled. To do so, set the `type` to [Titanium.UI.ATTRIBUTE_UNDERLINES_STYLE](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#ATTRIBUTE_UNDERLINES_STYLE) and the
`value` to [Titanium.UI.ATTRIBUTE_UNDERLINE_STYLE_NONE](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#ATTRIBUTE_UNDERLINE_STYLE_NONE).

### backgroundDisabledImage

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Background image for the button in its disabled state, specified as a local file path
or URL.

Also sets the background image for the other button states (normal, focused, selected),
unless they've been specified explicitly, except for iOS, which requires a backgroundImage.

### backgroundFocusedImage

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Background image for the button in its focused state, specified as a local file path
or URL.

Focusable must be true for normal views. Sets the background image for the focused
state only. For iOS, since there is not a trackball, this does nothing.

### backgroundImage

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Background image for the button in its normal state, specified as a local file path or URL.

Also sets the background image for the other button states (disabled, focused, selected),
unless they've been specified explicitly. On iOS, if backgroundDisabledImage is unset, the
image will appear faded to indicate being disabled. Also on iOS, if `backgroundSelectedImage`
is unset, the image will be darkened to indicate being selected.

### backgroundSelectedColor

- Type: String | Titanium.UI.Color
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK iPhone 6.1.0, iPad 6.1.0, Android 0.9.0
- Default: `Background color of this view.`

Selected background color of the view, as a color name or hex triplet.

For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

### backgroundSelectedImage

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Background image for the button in its selected state, specified as a local file
path or URL.

On Android, Focusable must be true in order to be selected. Sets the background image for the selected
state only.

### color

- Type: String | Titanium.UI.Color
- Platforms: Android, iPhone, iPad, macOS

Default button text color, as a color name or hex triplet.

For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

### configuration

- Type: Titanium.UI.iOS.ButtonConfiguration
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 13.0.0
- Requires: iOS 15.0+

Button configuration for modern button styling.

A [Titanium.UI.iOS.ButtonConfiguration](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.ButtonConfiguration.md) object that defines the appearance and behavior 
of the button. This provides a modern way to configure buttons with support for titles, 
subtitles, images, and various styling options.

When using a button configuration, it takes precedence over individual styling properties
like `title`, `color`, and `backgroundColor`.

### disabledColor

- Type: String | Titanium.UI.Color
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.2.0

Text color of the button in its disabled state, as a color name or hex triplet.

### enabled

- Type: Boolean
- Platforms: Android, iPhone, iPad
- Default: `true`

Set to `true` to enable the button, `false` to disable the button.

### font

- Type: Font
- Platforms: Android, iPhone, iPad, macOS

Font to use for the button text.

### image

- Type: String | Number | Titanium.Blob
- Platforms: Android, iPhone, iPad, macOS

Image to display next to the button title.

As of Titanium 11.0.0, the [imageIsMask](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#imageIsMask) property determines how
this image is displayed. If set `true`, this image will be tinted using the color assigned to the
[tintColor](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#tintColor) property. If set `false`, the image is displayed as-is.

On Android, you can set this to a numeric resource drawable ID via `Ti.App.Android.R.drawable.*`
which lets you use native vector drawbles that are commonly used as icons.

### imageIsMask

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 11.0.0
- Default: `true`

Set true to tint the button image. Set false to show the image as-is.

### selectedColor

- Type: String | Titanium.UI.Color
- Platforms: iPhone, iPad, macOS

Button text color used to indicate the selected state, as a color name or hex triplet.

For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

### shadowColor

- Type: String | Titanium.UI.Color
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.2.0

Shadow color of the [title](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#title), as a color name or hex triplet.

Use in conjunction with [shadowOffset](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#shadowOffset) and [shadowRadius](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#shadowRadius).
For information about color values, see the "Colors" section of [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

### shadowOffset

- Type: Point
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.2.0

Shadow offset of the [title](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#title), as a dictionary with the properties `x` and `y`.

Use in conjunction with [shadowColor](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#shadowColor) and [shadowRadius](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#shadowRadius).

### shadowRadius

- Type: Number
- Platforms: Android
- Since: Titanium SDK 3.2.0

Shadow radius of the [title](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#title).

Use in conjunction with [shadowColor](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#shadowColor) and [shadowOffset](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#shadowOffset).

### style

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 10.0.0, iPhone 0.8.0, iPad 0.8.0, macOS 9.2.0
- Default: `<Titanium.UI.BUTTON_STYLE_TEXT> (on iOS),
<Titanium.UI.BUTTON_STYLE_FILLED> (on Android)
`

The border and fill style the button will use.

On Android, this is a creation-only property and cannot be changed dynamically.

Accepts: `Titanium.UI.BUTTON_STYLE_FILLED`, `Titanium.UI.BUTTON_STYLE_OPTION_NEGATIVE`, `Titanium.UI.BUTTON_STYLE_OPTION_NEUTRAL`, `Titanium.UI.BUTTON_STYLE_OPTION_POSITIVE`, `Titanium.UI.BUTTON_STYLE_OUTLINED`, `Titanium.UI.BUTTON_STYLE_TEXT`

### systemButton

- Type: Number
- Platforms: iPhone, iPad, macOS

Specifies an iOS system button appearance, as defined in [Titanium.UI.iOS.SystemButton](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.SystemButton.md).

In JavaScript:

``` js
var cancelButton = Ti.UI.createButton({
    systemButton: Ti.UI.iOS.SystemButton.CANCEL
});
```

In Alloy, you can omit the namespace when setting the `systemButton` property on a `<Button>`
element:
``` xml
<Button systemButton="CAMERA"/>
```

Accepts: `Titanium.UI.iOS.SystemButton.ACTION`, `Titanium.UI.iOS.SystemButton.ACTIVITY`, `Titanium.UI.iOS.SystemButton.ADD`, `Titanium.UI.iOS.SystemButton.BOOKMARKS`, `Titanium.UI.iOS.SystemButton.CAMERA`, `Titanium.UI.iOS.SystemButton.CANCEL`, `Titanium.UI.iOS.SystemButton.COMPOSE`, `Titanium.UI.iOS.SystemButton.CONTACT_ADD`, `Titanium.UI.iOS.SystemButton.DISCLOSURE`, `Titanium.UI.iOS.SystemButton.DONE`, `Titanium.UI.iOS.SystemButton.EDIT`, `Titanium.UI.iOS.SystemButton.FAST_FORWARD`, `Titanium.UI.iOS.SystemButton.FIXED_SPACE`, `Titanium.UI.iOS.SystemButton.FLEXIBLE_SPACE`, `Titanium.UI.iOS.SystemButton.INFO_DARK`, `Titanium.UI.iOS.SystemButton.INFO_LIGHT`, `Titanium.UI.iOS.SystemButton.ORGANIZE`, `Titanium.UI.iOS.SystemButton.PAUSE`, `Titanium.UI.iOS.SystemButton.PLAY`, `Titanium.UI.iOS.SystemButton.REFRESH`, `Titanium.UI.iOS.SystemButton.REPLY`, `Titanium.UI.iOS.SystemButton.REWIND`, `Titanium.UI.iOS.SystemButton.SAVE`, `Titanium.UI.iOS.SystemButton.SPINNER`, `Titanium.UI.iOS.SystemButton.STOP`, `Titanium.UI.iOS.SystemButton.TRASH`

### textAlign

- Type: String | Number
- Platforms: Android, iPhone, iPad, macOS
- Default: `<Titanium.UI.TEXT_ALIGNMENT_CENTER>`

Text alignment, specified using one of the [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md) text alignment constants.

Accepts: `Titanium.UI.TEXT_ALIGNMENT_CENTER`, `Titanium.UI.TEXT_ALIGNMENT_JUSTIFY`, `Titanium.UI.TEXT_ALIGNMENT_LEFT`, `Titanium.UI.TEXT_ALIGNMENT_RIGHT`

### tintColor

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 5.4.0, iPhone 3.1.3, iPad 3.1.3

Color applied to button's image and title.

Color to be applied to the button's [image](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#image), but only if the
[imageIsMask](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#imageIsMask) property is set `true`.

This tint color is also applied to the button's [title](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#title)
unless the [color](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md#color) property is set.

### title

- Type: String
- Platforms: Android, iPhone, iPad, macOS

Button title.

### titleid

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 1.5

Key identifying a string from the locale file to use for the button title.

Only one of `title` or `titleid` should be specified.

### tooltip

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 12.1.0
- Requires: iOS 15.0+

The default text to display in the control's tooltip.

Assigning a value to this property causes the tool tip to be displayed for the view.
Setting the property to `null` cancels the display of the tool tip for the view.
Note: This property is only used for apps targeting macOS Catalyst.

### verticalAlign

- Type: Number | String
- Platforms: Android, iPhone, iPad, macOS
- Default: `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_CENTER`

Vertical alignment for the text field, specified using one of the
vertical alignment constants from [Titanium.UI](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

Accepts: `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_BOTTOM`, `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_CENTER`, `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_TOP`

## Events

### touchfiltered

- Platforms: Android
- Since: Titanium SDK 9.3.0

Fired when the device detects a swipe gesture against the view.

If the button's [filterTouchesWhenObscured](https://titaniumsdk.com/docs/sdk/Titanium.UI.View.md#filterTouchesWhenObscured) property
is set `true`, then this event will be fired if the touch event was discarded because another app's
overlapping window obscured it.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a
system overlay to intercept touch events in your app or to trick the end-user to tap on UI
in your app intended for the overlay.

You can use this event to display an alert dialog explaining why the button's action has been disabled.
Especially if the overlapping window is completely invisible.

Event properties:

- `x` (Number): X coordinate of the event from the `source` view's coordinate system.
- `y` (Number): Y coordinate of the event from the `source` view's coordinate system.
- `obscured` (Boolean): Always `true` since the touch event passed through another app's overlapping window.

## Inherited members

93 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.0.1/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`
- [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/13.0.1/Titanium.UI.View.md): `accessibilityDisableLongPress`, `accessibilityHidden`, `accessibilityHint`, `accessibilityLabel`, `accessibilityValue`, `anchorPoint`, `animate`, `animatedCenter`, `backgroundColor`, `backgroundDisabledColor`, `backgroundFocusedColor`, `backgroundGradient`, `backgroundLeftCap`, `backgroundRepeat`, `backgroundTopCap`, `borderColor`, `borderRadius`, `borderWidth`, `bottom`, `center`, `clearMotionEffects`, `click`, `clipMode`, `convertPointToView`, `dblclick`, `doubletap`, `elevation`, `filterTouchesWhenObscured`, `focus`, `focusable`, `getViewById`, `height`, `hiddenBehavior`, `hide`, `horizontalMotionEffect`, `horizontalWrap`, `id`, `insertAt`, `keepScreenOn`, `keypressed`, `layout`, `left`, `longclick`, `longpress`, `opacity`, `overrideCurrentAnimation`, `pinch`, `postlayout`, `previewContext`, `pullBackgroundColor`, `rect`, `right`, `rotate`, `rotation`, `rotationX`, `rotationY`, `scaleX`, `scaleY`, `show`, `singletap`, `size`, `softKeyboardOnFocus`, `stopAnimation`, `swipe`, `toImage`, `top`, `touchEnabled`, `touchFeedback`, `touchFeedbackColor`, `touchcancel`, `touchend`, `touchmove`, `touchstart`, `transform`, `transitionName`, `translationX`, `translationY`, `translationZ`, `twofingertap`, `verticalMotionEffect`, `viewShadowColor`, `viewShadowOffset`, `viewShadowRadius`, `visible`, `width`, `zIndex`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.