How to migrate your iOS app to Apple Vision Pro — and deliver a good UX

The new Apple Vision Pro presents an opportunity for brands and businesses to extend their digital product portfolio to arguably the most immersive digital platform yet.

At launch, Apple announced 600 new Vision Pro apps that offer custom “spatial experiences.” And there are more than 1 million existing “compatible” iOS apps.

Following the excitement and buzz from the Vision Pro launch, the question facing many builders is, “How can I quickly get my app into the Apple Vision Pro app store?”

We consider these three primary paths to get there:

• Option 1: Port an existing iPhone or iPad app.

• Option 2: Update an existing iPhone or iPad app, using visionOS, to match the basic design and feature set of the Vision Pro.

• Option 3: Build an entirely new spatial computing experience from scratch, specifically designed to take advantage of the unique features of the Vision Pro.

We don’t recommend Option 1 because it seldom will work just fine and your app will likely go unnoticed among the millions of “compatible” apps. And while we are most excited about the potential for building new spatial computing apps for the Vision Pro (Option 3), it can take months to deliver a truly lovable and memorable experience.

Of course, there’s value in being present on a new platform, quickly, before your competition. And gaining feedback from real users that might steer future product development. So, for this post, we’ll focus on Option 2 — showing you some of the steps for updating an existing app using visionOS. This option presents the best compromise to get something to the platform fast, and one that delivers a good user experience. We’ll also explain our first impressions and some key differences between visionOS and the other Apple platforms.

Choosing ‘Designed for iPad’ vs. ‘Apple Vision’

If you have an existing iPhone or iPad app, it’s easy to create an unmodified and “compatible” version of your app for Apple Vision Pro, our first bullet from above. This is Option 1 from above, and although it’s the fastest path to get onto the Apple Vision Pro App Store, we don’t recommend it.

An unmodified existing iOS or iPadOS app won’t be able to leverage any of the features from visionOS. In addition, an existing app may not work as expected — especially if it relies on iPhone or iPad features not included in the Apple Vision Pro. For example, user location on Apple Vision Pro is approximated via Wi-Fi — but iPhone location is identified via GPS and Bluetooth.

The better path to bringing your iPhone or iPad app to the Apple Vision Pro is to update your code within visionOS by selecting Apple Vision in Xcode:

Xcode provides two ways of supporting Apple Vision: using the visionOS SDK, the option highlighted above, or running an unmodified iOS app via “Designed for iPad.”

Getting your existing app to run on Apple Vision Pro

The first obstacle to overcome when migrating iOS or iPadOS applications to visionOS is third-party SDKs. All your dependencies need to support visionOS before you can support it yourself. Every third-party library provider needs a visionOS version for your app to use it, regardless of the dependency manager.

Xcode errors showing missing libraries for visionOS.

When you compile your app, you may have several missing API errors. Any iOS API that was deprecated before iOS 14 won’t be available on visionOS. Also, several APIs related to screen size and device orientation are missing since those concepts do not apply to Apple Vision Pro. If you use the size, scale, or orientation of the screen to determine how your UI elements are presented, you will have to rethink this and update your code.

A block of code with missing API compilation errors, including UIScreen, isLandscape, and orientation.

Depending on how you built your UI, you may notice warnings in the UI code. Storyboards and their APIs are deprecated on visionOS and could disappear in a future release. Apple’s advice is to migrate your interface code to SwiftUI.

Xcode warnings showing that compiling Interface Builder products for visionOS will not be supported in future versions.

If your app is already built with SwiftUI, you’re in for a smooth transition. If you depend on UIKit, you’ll face challenges with the new APIs, since they have been built with SwiftUI in mind. To overcome these challenges, use UI hosting views, which allow SwiftUI views to be added to UIKit views.

One example is the Ornaments API. Ornaments allow UI elements like tab bars and menus to be displayed outside of your app’s windows — so that they do not overlap with your app’s content. For example, a video player app could display video controls outside of the video content so that they don’t cover any parts of the video. However, the ornaments view is only available on SwiftUI. If your app is built with UIKit, you will have to create a UIHostingOrnament and add the SwiftUI ornaments to it. That’s possible, but it’s an additional step. We discuss ornaments more in the next section.

Optimizing your UI for Apple Vision Pro

After going through these steps, your app should be on Apple Vision Pro. However, the user interface will probably look out of place — similar to how an outdated website might feel on the modern web. Now’s the time to spend some effort to make your app look at home on Apple Vision Pro.

First, make sure your app supports landscape orientation. The canvas on visionOS is infinite, but the system will present your app window in landscape layout by default. So feel free to explore this horizontal space and be mindful of the reduced vertical space.

Next, update your app to better match the visionOS identity and design system, which is different than the other Apple platforms. On iPhone, the default background color in light mode is white, and that changes to a dark gray in dark mode. On visionOS, none of that is true; visionOS windows and elements use Apple’s new glass material background.

While many companies use background colors consistent with the visual identity of their brands, Apple’s recommendation for visionOS is to use glass material background and semantic colors and font sizes.

UI comparison: iOS vs. visionOS

To help illustrate the differences between how an app appears on Vision Pro when designed for iOS vs. one that’s designed for visionOS, we built a basic demo app.

The app uses AI to create images of birds, simply choosing color and size. This screenshot shows the app running on an iPad in landscape mode, where the user selected “Yellow” as its color and now needs to select a size for the bird:

After choosing “Large,” here is what the AI-generated large, yellow bird looks like on an iPad:

The app highlights selected elements in purple. The area displaying the generated bird has a light purple background. It uses system fonts and colors. Since the app was built entirely in SwiftUI, the transition to visionOS should be quite smooth.

The following screenshot shows the same app running on visionOS with no modifications:

The system adapted the user interface to look correct on Apple Vision Pro. However, things customized in iOS now look out of place. Notice how the purple “Select a size” label is barely visible with the glass background. That font color looked great with the white background of iPad light mode, but not so great on the Apple Vision Pro.

The following screenshot shows what the app looks like after the user chooses small, and AI generates the image:

The light purple background also looks out of place with the translucent background used in the other parts of the window. We can improve that by using the glassBackgroundEffect modifier and reducing the opacity of the background to 50%, as the following code snippet shows:

ZStack {
  Colors.primaryVariant
    .opacity(0.5)
  Image(bird)
}
.glassBackgroundEffect()

After the change, the app looks like this:

In addition to reducing the opacity, the code change also slightly adjusts the color based on the brightness of the surroundings.

Since visionOS does not have light and dark modes, apps don’t need to support light and dark appearances. Instead, apps should opt for system colors and let the system choose the best colors for the user according to the level of brightness in their surroundings.

Also, it’s important to understand how the user experience with modals is different on visionOS. Clicking outside of modals doesn’t automatically deactivate the frontmost modal like other platforms. Also, permission prompts — e.g. when a user gives an app permission to share location or send notifications — don’t block the UI to wait for the user’s response, so you should build your logic accordingly.

2 visionOS APIs to learn: HoverEffect and ornaments

Finally, it’s important to consider two new APIs on visionOS that affect user experience. The first one is HoverEffect. One of the main ways users interact with apps on Apple Vision is by using their eyes. When the user looks at interactive elements on the screen — such as buttons and controls — the system automatically highlights those elements. Without this hover effect, users may not know that they can interact with an element. Buttons and controls have HoverEffect enabled by default. However, you should revisit all your interactive UI elements and determine whether HoverEffect is appropriate.

The second API, ornaments, can help your UI elements look more at home in the Apple Vision Pro interface. As previously mentioned, ornaments allow you to display the usual menus and tab bars outside of your app’s window, freeing up some space for your app’s content. The ornaments API is simple to use, especially if you already use SwiftUI.

Is your app ready for Apple Vision Pro?

In this blog post, we explored the paths to bring your app to the Apple Vision Pro. We covered some of the new APIs for visionOS and showed the main differences between iOS and visionOS. Need help with your Vision Pro app? Our iOS developers have been creating lovable apps for over 15 years. Contact us for a free consultation.