How to use the #available attribute in Swift

Marking pieces of code as available or unavailable per platform or version is required in the ever-changing landscape of app development. When a new Swift version or platform version arrives, we’d like to adapt to it as soon as possible. Without throwing away support for older versions we can make use of the available attribute in Swift.

This post won’t help you decide for a strategy to decide which minimum iOS version you should support but it will be a useful reference for those times you need to make use of newer APIs.

Catch unexpected UI changes inside Pull RequestsUse your existing snapshot tests and store images with Screenshotbot to get notified inside pull-requests when a snapshot changes. Get started for free.

Checking for an OS version to execute code

A basic example comes down to checking for a specific OS version to execute a piece of code. For example, if you’d like to execute a piece of code only when it’s iOS 15 and up, you would use the available attribute as follows:

if #available(iOS 15, *) {
    print("This code only runs on iOS 15 and up")
} else {
    print("This code only runs on iOS 14 and lower")
}

You can use the available attribute inside a guard statement as well:

guard #available(iOS 15, *) else {
    print("Returning if iOS 14 or lower")
    return
}

print("This code only runs on iOS 15 and up")

This is great for cases in which you’d like to execute specific code only for a specific iOS version.

The difference between @available and #available

When navigating through Swift APIs you’ll often run into the @available attribute. We’ve just covered the #attribute which is similar but just a bit different. The shortest answer to describe its difference:

• @available is used to mark the availability for a class or method
• #available is used to only execute a piece of code for specific platforms and/or versions

Setting the availability for a class or method

We can demonstrate this by marking a class or method as available since iOS 14:

@available(iOS 14, *)
final class NewAppIntroduction {
    // ..
}

Once you’ll try to create an instance of this class inside a project that supports versions lower than iOS 14 you’ll run into the following error:

As you can see, the compiler will help us to fix this error with a few suggestions. Two of them will move the problem to a different place in your code by marking the calling class as available since iOS 14 too. The #available will help us in this case:

if #available(iOS 14, *) {
    let appIntroduction = NewAppIntroduction()
} else {
    // .. use the old app introduction
}

We could do exactly the same for methods using the @available attribute:

@available(iOS 14, *)
func launchNewAppIntroduction() {
    let appIntroduction = NewAppIntroduction()
}

Possible values for the available attribute

In the above examples, we’ve only made use of iOS 14 checks. However, there’s much more we can do with the available attribute in Swift.

Obviously, we could replace the number 14 with any OS version that’s available. The platform, in this case, iOS, can be replaced too. The list of available attributes as of today is as follows:

• iOS
• iOSApplicationExtension
• macOS
• macOSApplicationExtension
• macCatalyst
• macCatalystApplicationExtension
• watchOS
• watchOSApplicationExtension
• tvOS
• tvOSApplicationExtension
• swift

Options include platforms as well as the swift key to mark pieces of code as available since a specific Swift version.

The asterisk indicates the availability of the declaration on all of the platform names listed above unless specified specifically. You could specify multiple platforms at once as well if required:

@available(iOS 15, macOS 12.0, *)
func launchNewAppIntroduction() {
    let appIntroduction = NewAppIntroduction()
}

Marking a method as deprecated or obsoleted

Another attribute value is used to mark methods as deprecated or obsoleted. Methods start as being deprecated and will eventually be marked as obsolete. Imagine having an app in which the app introduction will no longer be shown on iOS 14 and up. You could mark the specific method if it’s used from an SDK as deprecated and obsoleted as follows:

@available(iOS, deprecated: 12, obsoleted: 13, message: "We no longer show an app introduction on iOS 14 and up")
func launchAppIntroduction() {
    // ..
}

When implementers of our code still try to use our methods they will run into the following error:

The version numbering when using these values is often confusing. In the above code example, you might think that the method is deprecated on iOS 12 and obsoleted on iOS 13. However, it’s read differently:

• This method is deprecated in versions higher than X
• This method is obsoleted in versions higher than X

The message is used to describe the reasoning and can be helpful to explain the change to your implementors.

Marking a method as renamed

When developing SDKs for colleagues, open-source, or other users you might want to migrate implementors to newer methods of your code. In these cases you can make use of the renamed attribute:

@available(*, unavailable, renamed: "launchOnboarding")
func launchAppIntroduction() {
    // Old implementation
}

func launchOnboarding() {
    // New implementation
}

Note that we’re marking a method as unavailable first. The renamed value indicates which method should be used instead.

Xcode will help implementors nicely by showing a fix option for our renaming:

Unavailability Condition using #unavailable

An often asked question when working with the available attribute is to negate the statement and write code like:

Only run this if the iOS version is lower than X

Swift 5.6 introduced the #unavailable attribute in SE-290 allowing us to invert the available check as follows:

if #unavailable(iOS 15, *) {
    // Run iOS 14 and lower code.
}

You basically read this as:

The new API is unavailable if the OS is lower than iOS 15

Using the unavailable attribute is cleaner than the code you had to write before Swift 5.6:

if #available(iOS 15, *) { } else {
    // Run iOS 14 and lower code.
}

If you’re reading this article after just upgrading to Xcode 13.3 you might want to check your projects for pieces of code like the above and migrate to use the unavailable check instead.

Using multiple unavailable platforms

The unavailable check can also be used with multiple platforms, just like the available check:

if #unavailable(iOS 15, watchOS 9) {
    // Run on iOS 14, watchOS 8 and lower
}

Catch unexpected UI changes inside Pull RequestsUse your existing snapshot tests and store images with Screenshotbot to get notified inside pull-requests when a snapshot changes. Get started for free.

Conclusion

We’ve covered all the possibilities of using the available attribute in Swift. You can run code for a specific platform and Swift versions and you’re now able to mark methods as deprecated, obsoleted, or renamed.

If you like to improve your Swift knowledge, even more, check out the Swift category page. Feel free to contact me or tweet to me on Twitter if you have any additional tips or feedback.

Thanks!