How to use the #available attribute in Swift

Marking pieces of code as available 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 adopt 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.

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 14 and up, you would use the available attribute as follows:

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

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

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

print("This code only runs on iOS 14 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:

An error occurs if you're creating an instance which is not available.
An error occurs if you’re creating an instance which is not available.

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 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 14, macOS 11.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 obsoleted. 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:

Marking a method as deprecated in Swift.
Marking a method as deprecated in Swift.

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 in 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:

Marking a method as renamed in Swift.
Marking a method as renamed in Swift.

Negate available statement

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

As of today, the only way to do this is by inverting the available check as follows:

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

This is far from great and results in an empty code block but is currently the only possible way. There’s an open discussion on the Swift forums but it seems that it’s not going to result in any changes in the nearby future.

Conclusion

We’ve covered all the possibilities of using the available attribute in Swift. You can run code for 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!