Titanium.UI.iOS.ButtonConfiguration

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

Extends: Titanium.Proxy · Since: 13.0.0, 13.0.0, 13.0.0 · Platforms: iphone, ipad, macos

Properties

apiName

extended

3.2.0

3.2.0

3.2.0

9.2.0

Type: String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Button
returns Ti.UI.Button.

attributedString

0.9

0.9

0.9

9.2.0

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

0.9

0.9

0.9

9.2.0

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

0.9

0.9

0.9

9.2.0

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

extended

3.0.0

3.0.0

3.0.0

9.2.0

Type: Boolean

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

Some proxies (most commonly views) have a relationship to other proxies, often
established by the add() method. For example, for a button added to a window, a
click event on the button would bubble up to the window. Other common parents are
table sections to their rows, table views to their sections, and scrollable views
to their views. Set this property to false to disable the bubbling to the proxy's parent.

color

0.9

0.9

0.9

9.2.0

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

0.9

0.9

0.9

9.2.0

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

0.9

0.9

0.9

9.2.0

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

0.9

0.9

0.9

9.2.0

Type: Number

The spacing between the image and title.

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

imagePlacement

0.9

0.9

0.9

9.2.0

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

lifecycleContainer

extended

3.6.0

Type: Titanium.UI.Window, Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks
will also be called on the proxy. Proxies that require the activity lifecycle will need this property set
to the appropriate containing Window or TabGroup.

loading

13.1.0

13.1.0

13.1.0

13.1.0

Type: Boolean

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

0.9

0.9

0.9

9.2.0

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

creation only

0.9

0.9

0.9

9.2.0

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

0.9

0.9

0.9

9.2.0

Type: String

The subtitle text to display below the title.

textAlign

0.9

0.9

0.9

9.2.0

Type: String, Number

Text alignment of the configuration title.

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

title

0.9

0.9

0.9

9.2.0

Type: String

The title text to display on the button.

titlePadding

0.9

0.9

0.9

9.2.0

Type: Number

The spacing between the title and subtitle.

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

Methods

addEventListener

extended

0.9

0.9

0.9

9.2.0

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

Parameters:

Name	Type	Summary	Optional
name	String	Name of the event.	No
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired.	No

applyProperties

extended

3.0.0

3.0.0

3.0.0

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that
myproxy[key] = value.

Parameters:

Name	Type	Summary	Optional
props	Dictionary	A dictionary of properties to apply.	No

fireEvent

extended

0.9

0.9

0.9

9.2.0

Fires a synthesized event to any registered listeners.

Parameters:

Name	Type	Summary	Optional
name	String	Name of the event.	No
event	Dictionary	A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.	Yes

removeEventListener

extended

0.9

0.9

0.9

9.2.0

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

Multiple listeners can be registered for the same event, so the
callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function
in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters:

Name	Type	Summary	Optional
name	String	Name of the event.	No
callback	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to addEventListener.	No

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
    })
});