<!--
{
  "availability" : [
    "iOS: 5.0.0 -",
    "iPadOS: 5.0.0 -",
    "macCatalyst: 13.1.0 -",
    "tvOS: -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "UIKit",
  "identifier" : "/documentation/UIKit/UISegmentedControl/setBackgroundImage(_:for:barMetrics:)",
  "metadataVersion" : "0.1.0",
  "role" : "Instance Method",
  "symbol" : {
    "kind" : "Instance Method",
    "modules" : [
      "UIKit"
    ],
    "preciseIdentifier" : "c:objc(cs)UISegmentedControl(im)setBackgroundImage:forState:barMetrics:"
  },
  "title" : "setBackgroundImage(_:for:barMetrics:)"
}
-->

# setBackgroundImage(_:for:barMetrics:)

Sets the background image for given state and bar metrics.

```
func setBackgroundImage(_ backgroundImage: UIImage?, for state: UIControl.State, barMetrics: UIBarMetrics)
```

## Parameters

`backgroundImage`

The background image to use for `state` and `barMetrics`.

`state`

A control state.

`barMetrics`

Bar metrics.

## Discussion

If `backgroundImage` is an image that [`resizableImage(withCapInsets:)`](/documentation/UIKit/UIImage/resizableImage(withCapInsets:)) returns, the system calculates the cap widths from that information.

If `backgroundImage` isn’t an image that [`resizableImage(withCapInsets:)`](/documentation/UIKit/UIImage/resizableImage(withCapInsets:)) returns, the system calculates the cap width by subtracting one from the image’s width, then dividing by 2. The system uses the cap widths as the margins for text placement. To adjust the margin, use the margin adjustment methods.

Generally, specify a value for the [`normal`](/documentation/UIKit/UIControl/State-swift.struct/normal) state. The segmented control uses this state for other states that don’t have a custom value set.

Similarly, when a property is dependent on the bar metrics, be sure to specify a value for [`UIBarMetrics.default`](/documentation/UIKit/UIBarMetrics/default). The segmented control respects properties for [`UIBarMetrics.compact`](/documentation/UIKit/UIBarMetrics/compact) only when the control is in smaller navigation and toolbars.

---

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)