<!--
{
  "availability" : [
    "iOS: 15.0.0 -",
    "iPadOS: 15.0.0 -",
    "macCatalyst: 15.0.0 -",
    "tvOS: 15.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: -"
  ],
  "documentType" : "symbol",
  "framework" : "UIKit",
  "identifier" : "/documentation/UIKit/UIButtonConfiguration",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "UIKit"
    ],
    "preciseIdentifier" : "c:objc(cs)UIButtonConfiguration"
  },
  "title" : "UIButtonConfiguration"
}
-->

# UIButtonConfiguration

A configuration that specifies the appearance and behavior of a button and its contents.

```
@interface UIButtonConfiguration : NSObject
```

## Overview

You can configure and update a button with a [`UIButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration). A button configuration contains all the customization options available with other methods, such as [`setTitle(_:for:)`](/documentation/UIKit/UIButton/setTitle(_:for:)), and can serve as a replacement for those methods. Alternatively, you can use a configuration in combination with these other methods and adopt new button behaviors and appearance without rewriting your customized [`UIButton`](/documentation/UIKit/UIButton) code.

## Topics

### Creating configurations

[`+  plainButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/plainButtonConfiguration)

Creates a configuration for a button with a transparent background.

[`+  grayButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/grayButtonConfiguration)

Creates a configuration for a button with a gray background.

[`+  tintedButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/tintedButtonConfiguration)

Creates a configuration for a button with a tinted background color.

[`+  filledButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/filledButtonConfiguration)

Creates a configuration for a button with a background filled with the button’s tint color.

[`+  borderlessButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/borderlessButtonConfiguration)

Creates a configuration for a button that has a borderless style.

[`+  borderedButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/borderedButtonConfiguration)

Creates a configuration for a button that has a bordered style.

[`+  borderedTintedButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/borderedTintedButtonConfiguration)

Creates a configuration for a button that has a tinted, bordered style.

[`+  borderedProminentButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/borderedProminentButtonConfiguration)

Creates a configuration for a button that has a prominent, bordered style.

[`+  glassButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/glassButtonConfiguration)

Creates a configuration for a button that has a Liquid Glass style.

[`+  prominentGlassButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/prominentGlassButtonConfiguration)

Creates a configuration for a button that has a prominent Liquid Glass style.

[`+  clearGlassButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/clearGlassButtonConfiguration)

Creates a configuration for a button that has a clear Liquid Glass style.

[`+  prominentClearGlassButtonConfiguration`](/documentation/UIKit/UIButtonConfiguration/prominentClearGlassButtonConfiguration)

Creates a configuration for a button that has a prominent, clear Liquid Glass style.

[`-  updatedConfigurationForButton:`](/documentation/UIKit/UIButtonConfiguration/updatedConfigurationForButton:)

Returns a copy of the configuration, updated for the given button.

### Configuring titles

[`title`](/documentation/UIKit/UIButtonConfiguration/title)

The text of the title label the button displays.

[`subtitle`](/documentation/UIKit/UIButtonConfiguration/subtitle)

The text the subtitle label of the button displays.

[`attributedTitle`](/documentation/UIKit/UIButtonConfiguration/attributedTitle)

The text and style attributes for the button’s title label.

[`attributedSubtitle`](/documentation/UIKit/UIButtonConfiguration/attributedSubtitle)

The text and style attributes for the button’s subtitle label.

[`titleTextAttributesTransformer`](/documentation/UIKit/UIButtonConfiguration/titleTextAttributesTransformer)

A transformer to update the attributed title when the button state changes.

[`subtitleTextAttributesTransformer`](/documentation/UIKit/UIButtonConfiguration/subtitleTextAttributesTransformer)

A transformer to update the attributed subtitle when the button state changes.

[`UIConfigurationTextAttributesTransformer`](/documentation/UIKit/UIConfigurationTextAttributesTransformer-swift.struct)

Defines a text transformation that can affect the visual appearance of a string.

[`UIConfigurationTextAttributesTransformer`](/documentation/UIKit/UIConfigurationTextAttributesTransformer-c.typealias)

Defines a text transformation that can affect the visual appearance of a string.

[`titlePadding`](/documentation/UIKit/UIButtonConfiguration/titlePadding)

The distance between the title and subtitle labels.

[`titleAlignment`](/documentation/UIKit/UIButtonConfiguration/titleAlignment)

The text alignment the button uses to lay out the title and subtitle.

[`UIButtonConfigurationTitleAlignment`](/documentation/UIKit/UIButtonConfigurationTitleAlignment)

Specifies how to align a button’s title and subtitle.

[`titleLineBreakMode`](/documentation/UIKit/UIButtonConfiguration/titleLineBreakMode)

The line break mode the button uses to lay out the button’s title.

[`subtitleLineBreakMode`](/documentation/UIKit/UIButtonConfiguration/subtitleLineBreakMode)

The line break mode the button uses to lay out the button’s subtitle.

### Configuring images

[`image`](/documentation/UIKit/UIButtonConfiguration/image)

The foreground image the button displays.

[`imagePadding`](/documentation/UIKit/UIButtonConfiguration/imagePadding)

The distance between the button’s image and text.

[`imagePlacement`](/documentation/UIKit/UIButtonConfiguration/imagePlacement)

The edge against which the button places the image.

[`imageColorTransformer`](/documentation/UIKit/UIButtonConfiguration/imageColorTransformer)

A block that transforms the image color when the button state changes.

[`preferredSymbolConfigurationForImage`](/documentation/UIKit/UIButtonConfiguration/preferredSymbolConfigurationForImage)

A requested configuration object for the button symbol image.

### Configuring layout

[`buttonSize`](/documentation/UIKit/UIButtonConfiguration/buttonSize)

A size that requests a preferred size for the button.

[`UIButtonConfigurationSize`](/documentation/UIKit/UIButtonConfigurationSize)

A predefined size for button elements.

[`contentInsets`](/documentation/UIKit/UIButtonConfiguration/contentInsets)

The distance from the button’s content area to its bounds.

[`-  setDefaultContentInsets`](/documentation/UIKit/UIButtonConfiguration/setDefaultContentInsets)

Restores the default content insets.

### Configuring button colors

[`baseBackgroundColor`](/documentation/UIKit/UIButtonConfiguration/baseBackgroundColor)

The untransformed color for background views.

[`baseForegroundColor`](/documentation/UIKit/UIButtonConfiguration/baseForegroundColor)

The untransformed color for foreground views.

### Configuring the button background

[`background`](/documentation/UIKit/UIButtonConfiguration/background)

The configuration to customize the button background.

[`cornerStyle`](/documentation/UIKit/UIButtonConfiguration/cornerStyle)

The button style that controls the display behavior of the background corner radius.

[`UIButtonConfigurationCornerStyle`](/documentation/UIKit/UIButtonConfigurationCornerStyle)

Settings that determine the appearance of the background corner radius.

### Configuring the indicator

[`indicator`](/documentation/UIKit/UIButtonConfiguration/indicator)

The style of the indicator that appears on the button.

[`UIButtonConfigurationIndicator`](/documentation/UIKit/UIButtonConfigurationIndicator)

Constants that determine the style of the indicator that appears on a button.

[`indicatorColorTransformer`](/documentation/UIKit/UIButtonConfiguration/indicatorColorTransformer)

The color transformer for resolving the indicator color.

### Configuring the activity indicator

[`showsActivityIndicator`](/documentation/UIKit/UIButtonConfiguration/showsActivityIndicator)

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

[`activityIndicatorColorTransformer`](/documentation/UIKit/UIButtonConfiguration/activityIndicatorColorTransformer)

The color transformer for resolving the color of the activity indicator.

### Configuring selection behavior

[`automaticallyUpdateForSelection`](/documentation/UIKit/UIButtonConfiguration/automaticallyUpdateForSelection)

A Boolean value that determines whether the style automatically updates when the button is in a selected state.

### Configuring the appearance on macOS

[`macIdiomStyle`](/documentation/UIKit/UIButtonConfiguration/macIdiomStyle)

The style to use when this button appears in macOS.

[`UIButtonConfigurationMacIdiomStyle`](/documentation/UIKit/UIButtonConfigurationMacIdiomStyle)

The button style your app uses when running in macOS.

## Relationships

### Inherits From

[`NSObject-swift.class`](/documentation/ObjectiveC/NSObject-swift.class)

### Conforms To

[`NSCopying`](/documentation/Foundation/NSCopying)

[`NSSecureCoding`](/documentation/Foundation/NSSecureCoding)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)