Skip Navigation

Immersive experiences

In visionOS, you can design apps and games that extend beyond windows and volumes, immersing people in your content.

A sketch that suggests Apple Vision Pro. The image is overlaid with rectangular and circular grid lines and is tinted yellow to subtly reflect the yellow in the original six-color Apple logo.

You can choose whether your visionOS app or game runs in the Shared Space or in a Full Space. In the Shared Space, your software runs alongside other experiences, and people can switch between them much as they do on a Mac; in a Full Space, your app or game runs alone, hiding other experiences and helping people immerse themselves in your content. Apps and games can support different types of immersion, and can transition fluidly between the Shared Space and a Full Space.

Play

Immersion and passthrough

While wearing Apple Vision Pro, people use passthrough to see their physical surroundings. Passthrough provides real-time video from the device’s external cameras, helping people feel comfortable and connected to their physical context.

People can also use the Digital Crown to help them manage app or game content and adjust passthrough. For example, people can press and hold the Digital Crown to recenter content in their field of view or double-click it to briefly hide all content and show passthrough for a clear view of their surroundings.

Play

The system also helps people remain comfortable by automatically changing the opacity of content in certain situations. For example, if someone gets too close to a physical object in mixed immersion, the content in front of them dims briefly so they can see their immediate physical surroundings more clearly. In more immersive experiences — such as in the progressive and full styles described below — the system defines a boundary that extends about 1.5 meters from the initial position of the wearer’s head. As their head gets close to this boundary, the entire experience begins to fade and passthrough increases. When their head moves beyond this boundary, the immersive visuals are replaced in space by the app’s icon, and are restored when the wearer returns to their original location or recenters their view using the Digital Crown.

Immersion styles

visionOS offers several ways to immerse people in your content. For example, you can:

  • Use dimmed passthrough to bring attention to your content. You can subtly dim or tint passthrough and other visible content to bring attention to your app in the Shared Space without hiding other apps and games, or create a more focused experience in a Full Space. While passthrough is tinted black by default, you can apply a custom tint color to create a dynamic experience in your app. For developer guidance, see SurroundingsEffect.

  • Increase immersion in a Full Space. When your app or game transitions to a Full Space, the system hides other apps so people can focus on yours. In a Full Space, you can display 3D content that isn’t bound by a window, in addition to content in standard windows and volumes. For developer guidance, see automatic.

    • Use mixed immersion to blend your content with passthrough. When your app or game runs in a Full Space, you can request access to information about nearby physical objects and room layout, helping you display virtual content in a person’s surroundings. The mixed immersion style doesn’t define a boundary. Instead, when a person gets too close to a physical object, the system automatically makes nearby content semi-opaque to help them remain aware of their surroundings. For developer guidance, see mixed and ARKit.

    • Use progressive immersion to blend your custom environment with a person’s surroundings. When your app or game runs in a Full Space, you can use the progressive style to display a custom environment that partially replaces passthrough. You can also define a specific range of immersion that works best with your app or game. While in your immersive experience, people can use the Digital Crown to adjust the amount of immersion within either the default range of 120- to 360-degrees or a custom range, if you specify one. The system defines the approximately 1.5-meter boundary when an experience using the progressive style starts. For developer guidance, see progressive.

    • Use full immersion to create a fully immersive experience. When your app or game runs in a Full Space, you can use the full style to display a 360-degree custom environment that completely replaces passthrough and transports people to a new place. As with the progressive style, the system defines the approximately 1.5-meter boundary when a fully immersive experience starts. For developer guidance, see full.

A screenshot of an app running in a Full Space using the mixed immersion style in visionOS.
Mixed immersion style in a Full Space blending in-app objects with real-world surroundings

Best practices

Offer multiple ways to use your app or game. In addition to giving people the freedom to choose their experiences, it’s essential to design your software to support the accessibility features people use to personalize the ways they interact with their devices. For guidance, see Accessibility.

Prefer launching your app or game in the Shared Space or using the mixed immersion style. Launching in the Shared Space lets people reference your app or game while using other running software, and enables seamless switching between them. If your app or game provides a fully immersive or progressive style experience, launching in the mixed immersion style or with a window-based experience in the Shared Space gives people more control, letting them choose when to increase immersion.

Reserve immersion for meaningful moments and content. Not every task benefits from immersion, and not every immersive task needs to be fully immersive. Although people sometimes want to enter a different world, they often want to stay grounded in their surroundings while they’re using your app or game, and they can appreciate being able to use other software and system features at the same time. Instead of assuming that your app or game needs to be fully immersive most of the time, design ways for people to immerse themselves in the individual tasks and content that make your experience unique. For example, people can browse their albums in Photos using a familiar app window in the Shared Space, but when they want to examine a single photo, they can temporarily transition to a more immersive experience in a Full Space where they can expand the photo and appreciate its details.

Help people engage with key moments in your app or game, regardless of the level of immersion. Cues like dimming, tinting, motion, scale, and Spatial Audio can help draw people’s attention to a specific area of content, whether it’s in a window in the Shared Space or in a completely immersive experience in a Full Space. Start with subtle cues that gently guide people’s attention, strengthening the cues only when there’s a good reason to do so.

Prefer subtle tint colors for passthrough. In visionOS 2 and later, you can tint passthrough to help a person’s surroundings visually coordinate with your content, while also making their hands look like they belong in your experience. Avoid bright or dramatic tints that can distract people and diminish the sense of immersion. For developer guidance, see SurroundingsEffect.

Promoting comfort

Be mindful of people’s visual comfort. For example, although you can place 3D content anywhere while your app or game is running in a Full Space, prefer placing it within people’s field of view. Also, make sure you display motion in comfortable ways while your software runs in a Full Space to avoid causing distraction, confusion, or discomfort. For guidance, see Motion.

Avoid encouraging people to move while they’re in an immersive experience. Some people may not want to move, or are unable to move because of a disability or their physical environment. Design ways for people to interact with content without moving. For example, let people bring a virtual object closer to them instead of expecting them to move close to the object.

Choose a style of immersion that supports the movements people might make while they’re in your app or game. It’s essential to choose the right style for your immersive experience because it allows the system to respond appropriately when people move. Although people can make minor physical movements while in an immersive experience — such as shifting their weight, turning around, or switching between sitting and standing — making excessive movements can cause the system to interrupt some experiences. In particular, avoid using the progressive or full immersion styles if you think people might move beyond the 1.5-meter boundary.

If you use the mixed immersion style, avoid obscuring passthrough too much. People use passthrough to help them understand and navigate their physical surroundings, so it’s important to avoid displaying virtual objects that block too much of their view. If your app or game displays virtual objects that could substantially obscure passthrough, use the full or progressive immersion styles instead of mixed.

Adopt ARKit if you want to blend custom content with someone’s surroundings. For example, you might want to integrate virtual content into someone’s surroundings or use the wearer’s hand positions to inform your experience. If you need access to these types of sensitive data, you must request people’s permission. For guidance, see Privacy; for developer guidance, see SceneReconstructionProvider.

Transitioning between immersive styles

Design smooth, predictable transitions when changing immersion. Help people prepare for different experiences by providing gentle transitions that let people visually track changes. Avoid sudden, jarring transitions that might be disorienting or uncomfortable. For developer guidance, see CoordinateSpaceProtocol.

Let people choose when to enter a more immersive experience. You don’t want to put people into a more immersive experience when they’re not expecting it, and you don’t want to overwhelm them by suddenly displaying large windows or objects. Instead, provide a clear entry control so people can decide when to be more immersed in your content.

Let people choose when to exit an immersive experience. For example, Keynote provides a prominent Exit button to help people leave the Theater experience and return to the slide-viewing window. Make sure your button clarifies whether it returns people to a previous, less immersive context or quits an experience altogether. If exiting your immersive experience also quits your app or game, consider providing controls that let people pause or return to a place where they can save their progress before quitting. In particular, avoid making the close button in Control Center or pressing the Digital Crown the only ways people can leave your immersive experience.

Displaying virtual hands

When running in a Full Space, your immersive app or game can ask permission to hide a person’s hands and instead show virtual hands that represent them.

Prefer virtual hands that match familiar characteristics. For example, match the positions and gestures of the viewer’s hands so they can continue to interact with your app or game in ways that feel natural. Hands that work in familiar ways help people stay immersed in the experience when in fully virtual worlds.

Use caution if you create virtual hands that are larger than the viewer’s hands. Virtual hands that are significantly bigger than human hands can prevent people from seeing the content they’re interested in and can make interactions feel clumsy. Also, large virtual hands can seem out of proportion with the space, appearing to be too close to the viewer’s face.

If there’s an interruption in hand-tracking data, fade out virtual hands and reveal the viewer’s own hands. Don’t let the virtual hands become unresponsive and appear frozen. When hand-tracking data returns, fade the virtual hands back in.

Creating an environment

When your app or game runs in a Full Space, you can replace passthrough with a custom environment that partially or completely surrounds a person, transporting them to a new place. The following guidelines can help you design a beautiful environment that people appreciate.

Minimize distracting content. To help immerse people in a primary task like watching a video, avoid displaying a lot of movement or high-contrast details in your environment. Alternatively, when you want to draw people’s attention to certain areas of your environment, consider techniques like using the highest quality textures and shapes in the important area while using lower quality assets and dimming in less important areas.

Help people distinguish interactive objects in your environment. People often use an object’s proximity to help them decide if they can interact with it. For example, when you place a 3D object far away from people, they often don’t try to touch or move toward it, but when you place a 3D object close to people, they’re more likely to try interacting with it.

Keep animation subtle. Small, gentle movements, like clouds drifting or transforming, can enrich your custom environment without distracting people or making them uncomfortable. Always avoid displaying too much movement near the edges of a person’s field of view. For guidance, see Motion.

Create an expansive environment, regardless of the place it depicts. A small, restrictive environment can make people feel uncomfortable and even claustrophobic.

Use Spatial Audio to create atmosphere. In visionOS, you use Spatial Audio to play sound that people can perceive as coming from specific locations in space, not just from speakers (for guidance, see Playing audio). As you design a soundscape that enhances your custom environment, keep the experience fresh and captivating by avoiding too much repetition or looping. If people can play other audio while they’re in your environment — for example, while watching a movie — be sure to lower the volume of the soundscape or stop it completely.

In general, avoid using a flat 360-degree image to create your environment. A 360-degree image doesn’t tend to give people a sense of scale when they view it in an environment, so it can reduce the immersiveness of the experience. Prefer creating object meshes that include lighting, and use shaders to implement subtle animations like the movements of clouds or leaves or the reflections of objects.

Help people feel grounded. Always provide a ground plane mesh so people don’t feel like they’re floating. If you must use a flat 360-degree image in your environment, adding a ground plane mesh can help it feel more realistic.

Minimize asset redundancy. Using the same assets or models too frequently tends to make an environment feel less realistic.

Platform considerations

Not supported in iOS, iPadOS, macOS, tvOS, or watchOS.

Resources

Spatial layout

Motion

Developer documentation

Creating fully immersive experiences in your app — visionOS

Incorporating real-world surroundings in an immersive experience — visionOS

ImmersionStyle — visionOS

Immersive spaces — SwiftUI

Videos

Change log

Date

Changes

November 19, 2024

Refined immersion style guidance and added artwork.

June 10, 2024

Added guidance for tinting passthrough and specifying initial, minimum, and maximum immersion levels.

May 7, 2024

Added guidance for creating an environment.

February 2, 2024

Clarified guidance for choosing an immersion style that matches the experience your app provides.

October 24, 2023

Updated artwork.

June 21, 2023

New page.

Current page is Immersive experiences