Titanium SDK

# Titanium.UI.iOS.ButtonConfiguration

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

Availability
13.0.0
13.0.0
Extends
Titanium.Proxy

# Overview

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

# apiName READONLY

Availability
13.0.0
13.0.0
apiName :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, Titanium.UI.Button returns Ti.UI.Button.

# attributedString

Availability
13.0.0
13.0.0
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

Availability
13.0.0
13.0.0
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

Availability
13.0.0
13.0.0
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

Availability
13.0.0
13.0.0
bubbleParent :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.

Default: true

# color

Availability
13.0.0
13.0.0
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

Availability
13.0.0
13.0.0
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

Availability
13.0.0
13.0.0
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

Availability
13.0.0
13.0.0
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

Availability
13.0.0
13.0.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

# padding

Availability
13.0.0
13.0.0
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 CREATION ONLY

Availability
13.0.0
13.0.0
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

Availability
13.0.0
13.0.0
subtitle :String

The subtitle text to display below the title.

# textAlign

Availability
13.0.0
13.0.0
textAlign :String | Number

Text alignment of the configuration title.

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

This API can be assigned the following constants:

# title

Availability
13.0.0
13.0.0
title :String

The title text to display on the button.

# titlePadding

Availability
13.0.0
13.0.0
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

# addEventListener

Availability
13.0.0
13.0.0
addEventListener(name, callback) → void

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

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to invoke when the event is fired.

Returns

Type
void

# applyProperties

Availability
13.0.0
13.0.0
applyProperties(props) → void

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 Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# fireEvent

Availability
13.0.0
13.0.0
fireEvent(name[, event]) → void

Fires a synthesized event to any registered listeners.

Parameters

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

Returns

Type
void

# removeEventListener

Availability
13.0.0
13.0.0
removeEventListener(name, callback) → void

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 Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

Returns

Type
void

Contents