You are reading 13.3.1. See this page in 13.4.1.

Titanium.UI.iOS.ButtonConfiguration

proxyiPhoneiPadmacOSsince 13.0.0

A configuration object for customizing the appearance and behavior of a button.

The ButtonConfiguration API provides a modern way to configure buttons on iOS with support for various styles, titles, subtitles, images, and padding. This API wraps the native UIButtonConfiguration introduced in iOS 15.0 and represents a modern alternative to the existing Button API while retaining backwards compatibility. In the future, this API may be merged into the root parameters of a button instead.

Use the Titanium.UI.iOS.createButtonConfiguration method to create a button configuration.

Button configurations support several predefined styles:

plain: A plain button style with minimal background
tinted: A tinted button style with a subtle background
filled: A filled button style with a solid background
gray: A gray button style
borderless: A borderless button style
bordered: A bordered button style with an outline
borderedTinted: A bordered button style with a tinted outline
borderedProminent: A bordered button style with a prominent appearance

Additional styles available on iOS 26.0+:

glass: A glass-like appearance
prominentGlass: A prominent glass-like appearance
clearGlass: A clear glass-like appearance
prominentClearGlass: A prominent clear glass-like appearance

Examples

Basic Button Configuration

const button = Ti.UI.createButton({
    configuration: Ti.UI.iOS.createButtonConfiguration({
        style: 'filled',
        title: 'Sign In',
        subtitle: 'with your account',
        backgroundColor: '#007AFF',
        color: 'white'
    })
});

Button with Image and Padding

const button = Ti.UI.createButton({
    configuration: Ti.UI.iOS.createButtonConfiguration({
        style: 'borderedTinted',
        title: 'Upload',
        image: 'upload-icon.png',
        imagePlacement: 'leading',
        imagePadding: 8,
        padding: {
            top: 12,
            left: 20,
            bottom: 12,
            right: 20
        }
    })
});

Prominent Button Style

const button = Ti.UI.createButton({
    configuration: Ti.UI.iOS.createButtonConfiguration({
        style: 'borderedProminent',
        title: 'Get Started',
        backgroundColor: '#34C759'
    })
});

Typography and Alignment

const button = Ti.UI.createButton({
    configuration: Ti.UI.iOS.createButtonConfiguration({
        style: 'filled',
        title: 'Continue',
        font: { fontSize: 18, fontWeight: 'semibold' },
        textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER
    })
});

Highlighted Background Color

const button = Ti.UI.createButton({
    configuration: Ti.UI.iOS.createButtonConfiguration({
        style: 'filled',
        title: 'Tap Me',
        backgroundColor: '#007AFF',
        backgroundSelectedColor: '#005BBB' // shown while pressed
    })
});

Properties 17

apiName

Stringsince Android 3.2.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0read-only

Inherited from Titanium.Proxy

The name of the API that this proxy corresponds to.

attributedString

Titanium.UI.AttributedString

Specify an attributed string for the button title.

Sets the configuration’s attributedTitle. If set, avoid also setting title, color, and font to prevent conflicting styles.

backgroundColor

String | Titanium.UI.Color

The background color of the button.

Sets the base background color for the button. This color may be modified by the system based on the button state and configuration style.

backgroundSelectedColor

String | Titanium.UI.Color

Background color to use while the button is highlighted (pressed).

When this configuration is assigned to a Titanium.UI.Button and both backgroundColor and backgroundSelectedColor are provided, the button will automatically swap the configuration’s background to backgroundSelectedColor when highlighted and restore the base color when not highlighted.

This mirrors the traditional backgroundSelectedColor behavior on views when used with modern button configurations.

bubbleParent

Booleansince Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0

Inherited from Titanium.Proxy

Indicates if the proxy will bubble an event to its parent.

Default: true

color

String | Titanium.UI.Color

The foreground color of the button's content.

Sets the base foreground color for the button's title and subtitle text. This color may be modified by the system based on the button state.

font

Font

Font to use for the button title.

Sets the font applied to the configuration’s title via the underlying UIButtonConfiguration.titleTextAttributesTransformer.

When using attributedString, prefer setting font in the attributed content instead.

image

String | Titanium.Blob | Titanium.Filesystem.File

The image to display on the button.

The image to display alongside the button's title. Use the imagePlacement property to control where the image appears relative to the title.

imagePadding

Number

The spacing between the image and title.

The amount of spacing in points between the button's image and its title text.

Default: 0

imagePlacement

String

The placement of the image relative to the title.

Controls where the button's image appears relative to its title text.

Valid string values are:

"leading": Place the image before the title text
"trailing": Place the image after the title text
"top": Place the image above the title text
"bottom": Place the image below the title text

Default: leading

loading

Booleansince 13.1.0

Whether or not a loading indicator should be shown

A Boolean value that determines whether the button displays an activity indicator instead of an image.

padding

Padding

The padding around the button's content.

An object with top, left, bottom, and right properties to specify the content insets for the button.

style

String

The style of button configuration to create.

Sets the base configuration style for the button. This property should be set first as it determines the initial configuration that other properties will modify.

Valid string values are:

"plain": A plain button style with minimal background
"tinted": A tinted button style with a subtle background
"filled": A filled button style with a solid background
"gray": A gray button style
"borderless": A borderless button style
"bordered": A bordered button style with an outline
"borderedTinted": A bordered button style with a tinted outline
"borderedProminent": A bordered button style with a prominent appearance
"glass": A glass-like appearance (iOS 26.0+)
"prominentGlass": A prominent glass-like appearance (iOS 26.0+)
"clearGlass": A clear glass-like appearance (iOS 26.0+)
"prominentClearGlass": A prominent clear glass-like appearance (iOS 26.0+)

subtitle

String

The subtitle text to display below the title.

textAlign

String | Number

Text alignment of the configuration title.

Aligns the title within the button’s content area. Maps to UIButtonConfigurationTitleAlignment.

Accepts

title

String

The title text to display on the button.

titlePadding

Number

The spacing between the title and subtitle.

The amount of spacing in points between the button's title and subtitle text.

Default: 0

Methods 4

addEventListener

Inherited from Titanium.Proxy

Adds the specified callback as an event listener for the named event.

Parameters
Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.

applyProperties

since 3.0.0

Inherited from Titanium.Proxy

Applies the properties to the proxy.

Parameters
Parameters	Type	Description
props	Dictionary	A dictionary of properties to apply.

fireEvent

Inherited from Titanium.Proxy

Fires a synthesized event to any registered listeners.

Parameters
Parameters	Type	Description
name	String	Name of the event.
event?	Dictionary	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

removeEventListener

Inherited from Titanium.Proxy

Removes the specified callback as an event listener for the named event.

Parameters
Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to `addEventListener`. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.