<!--
{
  "availability" : [
    "iOS: 15.0.0 -",
    "iPadOS: 15.0.0 -",
    "macCatalyst: -",
    "tvOS: 15.0.0 -",
    "visionOS: -"
  ],
  "documentType" : "symbol",
  "framework" : "UIKit",
  "identifier" : "/documentation/UIKit/UIButton/Configuration-swift.struct",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "UIKit"
    ],
    "preciseIdentifier" : "s:So8UIButtonC5UIKitE13ConfigurationV"
  },
  "title" : "UIButton.Configuration"
}
-->

# UIButton.Configuration

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

```
struct Configuration
```

## Overview

You can configure and update a button with a [`UIButton.Configuration`](/documentation/UIKit/UIButton/Configuration-swift.struct). 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

[`plain()`](/documentation/UIKit/UIButton/Configuration-swift.struct/plain())

Creates a configuration for a button with a transparent background.

[`gray()`](/documentation/UIKit/UIButton/Configuration-swift.struct/gray())

Creates a configuration for a button with a gray background.

[`tinted()`](/documentation/UIKit/UIButton/Configuration-swift.struct/tinted())

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

[`filled()`](/documentation/UIKit/UIButton/Configuration-swift.struct/filled())

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

[`borderless()`](/documentation/UIKit/UIButton/Configuration-swift.struct/borderless())

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

[`bordered()`](/documentation/UIKit/UIButton/Configuration-swift.struct/bordered())

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

[`borderedTinted()`](/documentation/UIKit/UIButton/Configuration-swift.struct/borderedTinted())

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

[`borderedProminent()`](/documentation/UIKit/UIButton/Configuration-swift.struct/borderedProminent())

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

[`glass()`](/documentation/UIKit/UIButton/Configuration-swift.struct/glass())

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

[`prominentGlass()`](/documentation/UIKit/UIButton/Configuration-swift.struct/prominentGlass())

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

[`clearGlass()`](/documentation/UIKit/UIButton/Configuration-swift.struct/clearGlass())

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

[`prominentClearGlass()`](/documentation/UIKit/UIButton/Configuration-swift.struct/prominentClearGlass())

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

[`updated(for:)`](/documentation/UIKit/UIButton/Configuration-swift.struct/updated(for:))

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

### Configuring titles

[`title`](/documentation/UIKit/UIButton/Configuration-swift.struct/title)

The text of the title label the button displays.

[`subtitle`](/documentation/UIKit/UIButton/Configuration-swift.struct/subtitle)

The text the subtitle label of the button displays.

[`attributedTitle`](/documentation/UIKit/UIButton/Configuration-swift.struct/attributedTitle)

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

[`attributedSubtitle`](/documentation/UIKit/UIButton/Configuration-swift.struct/attributedSubtitle)

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

[`titleTextAttributesTransformer`](/documentation/UIKit/UIButton/Configuration-swift.struct/titleTextAttributesTransformer)

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

[`subtitleTextAttributesTransformer`](/documentation/UIKit/UIButton/Configuration-swift.struct/subtitleTextAttributesTransformer)

A structure 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.

[`titlePadding`](/documentation/UIKit/UIButton/Configuration-swift.struct/titlePadding)

The distance between the title and subtitle labels.

[`titleAlignment`](/documentation/UIKit/UIButton/Configuration-swift.struct/titleAlignment-swift.property)

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

[`UIButton.Configuration.TitleAlignment`](/documentation/UIKit/UIButton/Configuration-swift.struct/TitleAlignment-swift.enum)

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

[`titleLineBreakMode`](/documentation/UIKit/UIButton/Configuration-swift.struct/titleLineBreakMode)

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

[`subtitleLineBreakMode`](/documentation/UIKit/UIButton/Configuration-swift.struct/subtitleLineBreakMode)

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

### Configuring images

[`image`](/documentation/UIKit/UIButton/Configuration-swift.struct/image)

The foreground image the button displays.

[`imagePadding`](/documentation/UIKit/UIButton/Configuration-swift.struct/imagePadding)

The distance between the button’s image and text.

[`imagePlacement`](/documentation/UIKit/UIButton/Configuration-swift.struct/imagePlacement)

The edge against which the button places the image.

[`imageReservation`](/documentation/UIKit/UIButton/Configuration-swift.struct/imageReservation)

A value that reserves space for the image in the same axis as the edge against which the button places the image.

[`imageColorTransformer`](/documentation/UIKit/UIButton/Configuration-swift.struct/imageColorTransformer)

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

[`preferredSymbolConfigurationForImage`](/documentation/UIKit/UIButton/Configuration-swift.struct/preferredSymbolConfigurationForImage)

A requested configuration object for the button symbol image.

### Configuring layout

[`buttonSize`](/documentation/UIKit/UIButton/Configuration-swift.struct/buttonSize)

A size that requests a preferred size for the button.

[`UIButton.Configuration.Size`](/documentation/UIKit/UIButton/Configuration-swift.struct/Size)

A predefined size for button elements.

[`contentInsets`](/documentation/UIKit/UIButton/Configuration-swift.struct/contentInsets)

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

[`setDefaultContentInsets()`](/documentation/UIKit/UIButton/Configuration-swift.struct/setDefaultContentInsets())

Restores the default content insets.

### Configuring button colors

[`baseBackgroundColor`](/documentation/UIKit/UIButton/Configuration-swift.struct/baseBackgroundColor)

The untransformed color for background views.

[`baseForegroundColor`](/documentation/UIKit/UIButton/Configuration-swift.struct/baseForegroundColor)

The untransformed color for foreground views.

### Configuring the button background

[`background`](/documentation/UIKit/UIButton/Configuration-swift.struct/background)

The configuration to customize the button background.

[`cornerStyle`](/documentation/UIKit/UIButton/Configuration-swift.struct/cornerStyle-swift.property)

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

[`UIButton.Configuration.CornerStyle`](/documentation/UIKit/UIButton/Configuration-swift.struct/CornerStyle-swift.enum)

Settings that determine the appearance of the background corner radius.

### Configuring the indicator

[`indicator`](/documentation/UIKit/UIButton/Configuration-swift.struct/indicator-swift.property)

The style of the indicator that appears on the button.

[`UIButton.Configuration.Indicator`](/documentation/UIKit/UIButton/Configuration-swift.struct/Indicator-swift.enum)

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

[`indicatorColorTransformer`](/documentation/UIKit/UIButton/Configuration-swift.struct/indicatorColorTransformer)

The color transformer for resolving the indicator color.

### Configuring the activity indicator

[`showsActivityIndicator`](/documentation/UIKit/UIButton/Configuration-swift.struct/showsActivityIndicator)

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

[`activityIndicatorColorTransformer`](/documentation/UIKit/UIButton/Configuration-swift.struct/activityIndicatorColorTransformer)

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

### Configuring selection behavior

[`automaticallyUpdateForSelection`](/documentation/UIKit/UIButton/Configuration-swift.struct/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/UIButton/Configuration-swift.struct/macIdiomStyle-swift.property)

The style to use when this button appears in macOS.

[`UIButton.Configuration.MacIdiomStyle`](/documentation/UIKit/UIButton/Configuration-swift.struct/MacIdiomStyle-swift.enum)

The button style your app uses when running in macOS.


---

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)