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

# UIBackgroundConfiguration

A configuration that describes a specific background appearance.

```
struct UIBackgroundConfiguration
```

## Overview

Background configurations provide a lightweight way for you to create backgrounds for your views. Using a background configuration, you can obtain system default background styling for a variety of different view states. You apply background configurations directly to [`UIButton`](/documentation/UIKit/UIButton) or to cells, headers, and footers in [`UICollectionView`](/documentation/UIKit/UICollectionView) and [`UITableView`](/documentation/UIKit/UITableView).

To use a background configuration:

1. Create a background configuration with one of the default system styles.
2. Modify the configuration to match your view’s style if you need additional customization.
3. Set the view’s current background configuration to your configuration.

```swift
var backgroundConfig = UIBackgroundConfiguration.listPlainCell()

// Set a nil background color to use the view's tint color. 
backgroundConfig.backgroundColor = nil 

cell.backgroundConfiguration = backgroundConfig
```

You can also start by creating an empty background configuration using `clear()`, which produces a transparent background.

Each of the system background styles provides system default values for different configuration states ([`UIConfigurationState`](/documentation/UIKit/UIConfigurationState-8d7pd)). If you apply a background configuration to a view whose [`automaticallyUpdatesBackgroundConfiguration`](/documentation/UIKit/UICollectionViewCell/automaticallyUpdatesBackgroundConfiguration) property is <doc://com.apple.documentation/documentation/Swift/true>, the system automatically updates the background configuration when the view’s state changes.

If you want additional customization beyond the system default values, you can choose to manually update the background configuration by overriding the view’s [`updateConfiguration(using:)`](/documentation/UIKit/UICollectionViewCell/updateConfiguration(using:)) method.

```swift
override func updateConfiguration(using state: UIConfigurationState) {
    // Get the system default background configuration for a plain style list cell in the current state. 
    var backgroundConfig = UIBackgroundConfiguration.listPlainCell().updated(for: state) 

    // Customize the background color to use the tint color when the cell is highlighted or selected. 
     if state.isHighlighted || state.isSelected { 
        backgroundConfig.backgroundColor = nil 
     } 

    // Apply the background configuration to the cell. 
    self.backgroundConfiguration = backgroundConfig 
} 
```

When you apply a configuration to a view, UIKit performs the actual drawing and rendering of the background. When you use background configurations instead of rendering your own backgrounds, the system provides automatic view hierarchy management, support for interactive and interruptible animations and transitions, and performance optimizations.

## Topics

### Creating cell background configurations

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

Creates the default configuration you use to style a cell in a plain list.

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

Creates the default configuration you use to style a cell in a grouped list.

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

Creates the default configuration you use to style a cell in a sidebar list.

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

Creates the default configuration you use to style a cell in an accompanied sidebar list.

### Creating header and footer background configurations

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

Creates the default configuration you use to style a plain list header or footer.

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

Creates the default configuration you use to style a grouped list header or footer.

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

Creates the default configuration you use to style a sidebar list header.

### Creating an empty background configuration

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

Creates an empty background configuration with a transparent background and no default styling.

### Customizing the background

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

A custom view for the background.

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

The preferred corner radius, using a continuous corner curve, for the background and stroke.

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

The insets (or outsets, if negative) for the background and stroke, relative to the edges of the containing view.

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

The edges on which the configuration adds the containing view’s layout margins to the background insets.

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

The color of the background.

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

The color transformer for resolving the background color.

[`resolvedBackgroundColor(for:)`](/documentation/UIKit/UIBackgroundConfiguration-swift.struct/resolvedBackgroundColor(for:))

Generates the resolved background color for the specified tint color, using the background color and color transformer.

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

The visual effect that the configuration applies to the background.

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

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

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

The color of the stroke.

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

The color transformer for resolving the stroke color.

[`resolvedStrokeColor(for:)`](/documentation/UIKit/UIBackgroundConfiguration-swift.struct/resolvedStrokeColor(for:))

Generates the resolved stroke color for the specified tint color, using the stroke color and color transformer.

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

The width of the stroke.

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

The outset (or inset, if negative) for the stroke.

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

The image displayed in the view’s background.

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

A property that determines the layout of a background image in a view when its bounds change.

### Updating background configurations

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

Generates a configuration for the specified state by applying the configuration’s default values for that state to any properties that you haven’t customized.


---

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)