<!--
{
  "availability" : [
    "iOS: 10.3.0 -",
    "iPadOS: 10.3.0 -",
    "macCatalyst: 13.1.0 -",
    "tvOS: 10.2.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "UIKit",
  "identifier" : "/documentation/UIKit/UIApplication/setAlternateIconName(_:completionHandler:)",
  "metadataVersion" : "0.1.0",
  "role" : "Instance Method",
  "symbol" : {
    "kind" : "Instance Method",
    "modules" : [
      "UIKit"
    ],
    "preciseIdentifier" : "c:objc(cs)UIApplication(im)setAlternateIconName:completionHandler:"
  },
  "title" : "setAlternateIconName(_:completionHandler:)"
}
-->

# setAlternateIconName(_:completionHandler:)

Changes the icon the system displays for the app.

```
func setAlternateIconName(_ alternateIconName: String?, completionHandler: (@Sendable ((any Error)?) -> Void)? = nil)
```

## Parameters

`alternateIconName`

The name of the alternate icon, as declared in the `CFBundleAlternateIcons` key of your app’s `Info.plist` file. Specify `nil` if you want to display the app’s primary icon, which you declare using the `CFBundlePrimaryIcon` key. Both keys are subentries of the `CFBundleIcons` key in your app’s `Info.plist` file.

`completionHandler`

The handler to execute with the results. After attempting to change your app’s icon, the system reports the results by calling your handler. The handler executes on a UIKit-provided queue, and not necessarily on your app’s main queue. The handler has no return value and takes the following parameter:

- error: On success, the value of this parameter is `nil`. If an error occurred, this parameter contains the error object indicating what happened and the value of the [`alternateIconName`](/documentation/UIKit/UIApplication/alternateIconName) property remains unchanged.

## Discussion

Use this method to change your app’s icon to its primary icon or to one of its alternate icons. You can change the icon only if the value of the [`supportsAlternateIcons`](/documentation/UIKit/UIApplication/supportsAlternateIcons) property is <doc://com.apple.documentation/documentation/Swift/true>.

You must configure your app’s primary icon asset in the “App Icons and Launch Images” section of the General pane or set it directly using the “Primary App Icon Set Name” build setting. You specify the names of additional icon assets available to your app using the “Alternate App Icon Sets” build setting. Xcode uses these setting to generate the entries for <doc://com.apple.documentation/documentation/BundleResources/Information-Property-List/CFBundleIcons/CFBundlePrimaryIcon> and <doc://com.apple.documentation/documentation/BundleResources/Information-Property-List/CFBundleIcons/CFBundleAlternateIcons> under the top-level key <doc://com.apple.documentation/documentation/BundleResources/Information-Property-List/CFBundleIcons>. For more information, see <doc://com.apple.documentation/documentation/Xcode/build-settings-reference> and <doc://com.apple.documentation/documentation/Xcode/configuring-your-app-icon>.

> Note:
> This method still sets the alternate icon in compatible iPad and iPhone apps running in visionOS. Support for alternate icons is unavailable in apps you build using the visionOS SDK, and calling this method has no effect.

---

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)