# Titanium.UI.iOS.ButtonConfiguration > A configuration object for customizing the appearance and behavior of a button. - Source: https://titaniumsdk.com/docs/sdk/13.1.1/Titanium.UI.iOS.ButtonConfiguration - Titanium SDK version: 13.1.1 - Kind: proxy - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 13.0.0 - Extends: Titanium.Proxy - Inheritance: Titanium.Proxy 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](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.md#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 ## Example: Basic Button Configuration ``` js const button = Ti.UI.createButton({ configuration: Ti.UI.iOS.createButtonConfiguration({ style: 'filled', title: 'Sign In', subtitle: 'with your account', backgroundColor: '#007AFF', color: 'white' }) }); ``` ## Example: Button with Image and Padding ``` js 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 } }) }); ``` ## Example: Prominent Button Style ``` js const button = Ti.UI.createButton({ configuration: Ti.UI.iOS.createButtonConfiguration({ style: 'borderedProminent', title: 'Get Started', backgroundColor: '#34C759' }) }); ``` ## Example: Typography and Alignment ``` js 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 }) }); ``` ## Example: Highlighted Background Color ``` js const button = Ti.UI.createButton({ configuration: Ti.UI.iOS.createButtonConfiguration({ style: 'filled', title: 'Tap Me', backgroundColor: '#007AFF', backgroundSelectedColor: '#005BBB' // shown while pressed }) }); ``` ## Properties ### attributedString - Type: Titanium.UI.AttributedString - Platforms: iPhone, iPad, macOS 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 - Type: String | Titanium.UI.Color - Platforms: iPhone, iPad, macOS 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 - Type: String | Titanium.UI.Color - Platforms: iPhone, iPad, macOS Background color to use while the button is highlighted (pressed). When this configuration is assigned to a [Titanium.UI.Button](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md) 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. ### color - Type: String | Titanium.UI.Color - Platforms: iPhone, iPad, macOS 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 - Type: Font - Platforms: iPhone, iPad, macOS 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 - Type: String | Titanium.Blob | Titanium.Filesystem.File - Platforms: iPhone, iPad, macOS 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 - Type: Number - Platforms: iPhone, iPad, macOS - Default: `0` The spacing between the image and title. The amount of spacing in points between the button's image and its title text. ### imagePlacement - Type: String - Platforms: iPhone, iPad, macOS - Default: `leading` 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 ### loading - Type: Boolean - Platforms: iPhone, iPad, macOS - Since: Titanium SDK 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 - Type: Padding - Platforms: iPhone, iPad, macOS 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 - Type: String - Platforms: iPhone, iPad, macOS 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 - Type: String - Platforms: iPhone, iPad, macOS The subtitle text to display below the title. ### textAlign - Type: String | Number - Platforms: iPhone, iPad, macOS Text alignment of the configuration title. Aligns the title within the button’s content area. Maps to `UIButtonConfigurationTitleAlignment`. Accepts: `Titanium.UI.TEXT_ALIGNMENT_CENTER`, `Titanium.UI.TEXT_ALIGNMENT_JUSTIFY`, `Titanium.UI.TEXT_ALIGNMENT_LEFT`, `Titanium.UI.TEXT_ALIGNMENT_RIGHT` ### title - Type: String - Platforms: iPhone, iPad, macOS The title text to display on the button. ### titlePadding - Type: Number - Platforms: iPhone, iPad, macOS - Default: `0` The spacing between the title and subtitle. The amount of spacing in points between the button's title and subtitle text. ## Inherited members 6 members are inherited. Each is documented on the type that declares it. - [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.1.1/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `removeEventListener` --- - 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`.