Skip Navigation

Windows

A window presents UI views and components in your app or game.

A stylized representation of a window with close, minimize, and full-screen buttons. The image is tinted red to subtly reflect the red in the original six-color Apple logo.

Depending on the platform, device, and context, a window can be undetectable to people. For example, in platforms where the default experience is full screen, like iOS, tvOS, and watchOS, people view and interact with the content inside a window — they don’t view or interact with the window itself. Note that although the default iPadOS experience is also full screen, people can open and manipulate more than one window when they use the multitasking and multiple windows features.

In contrast to windows in other platforms, windows in macOS and visionOS often include visible UI that can function as a frame for the content, letting people open, close, resize, and relocate individual windows, as well as view multiple windows at the same time.

Although the terms window and scene are sometimes used interchangeably, be sure to use window — not scene — if you need to refer to these high-level containers in help or other content that describes your app or game to people.

Because window appearance and behavior is platform-specific, the guidance below applies only to platforms in which windows are detectable objects — that is, iPadOS, macOS, and visionOS. In platforms where windows are undetectable — that is, iOS, tvOS, and watchOS — you don’t need to consider the appearance or behavior of the window itself. For developer guidance, see Windows. For guidance on other types of window-like views on all platforms, see Alerts, Panels, Popovers, and Sheets.

For guidance laying out content within a window on any platform, see Layout; for guidance laying out content in Apple Vision Pro space, see Spatial layout.

Platform considerations

No additional considerations for iOS, tvOS, or watchOS.

iPadOS

In iPadOS, people can be aware of an app’s window as a visually distinct object when they use the multitasking and multiple windows features. For example, people can view two or three apps onscreen at the same time or open multiple windows in the same app.

To support multitasking and multiwindow workflows on iPad, you need to ensure that your windows adapt to different sizes and that you match each window’s presentation style to its content. For guidance, see Multitasking on iPad.

macOS

In macOS, people typically run several apps at the same time, often viewing windows from multiple apps on one desktop and switching frequently between different windows — moving, resizing, minimizing, and revealing the windows to suit their work style.

To learn about setting up a window to display your game in macOS, see Managing your game window for Metal in macOS.

macOS window anatomy

A macOS window consists of a frame and a body area. People can move a window by dragging the frame and can often resize the window by dragging its edges.

An illustration that represents a Finder window in macOS, with callouts indicating the window frame area at the top and the body area below it.

The frame of a window appears above the body area and can include a title bar, toolbar, and tabs. In rare cases, a window can also display a bottom bar, which is a part of the frame that appears below body content.

macOS window states

A macOS window can have one of three states:

  • Main. The frontmost window that people view is an app’s main window. There can be only one main window per app.

  • Key. Also called the active window, the key window accepts people’s input. There can be only one key window onscreen at a time. Although the front app’s main window is usually the key window, another window — such as a panel floating above the main window — might be key instead. People typically click a window to make it key; when people click an app’s Dock icon to bring all of that app’s windows forward, only the most recently accessed window becomes key.

  • Inactive. A window that’s not in the foreground is an inactive window.

The system gives main, key, and inactive windows different appearances to help people visually identify them. For example, the key window uses color in the title bar options for closing, minimizing, and zooming; inactive windows and main windows that aren’t key use gray in these options. Also, inactive windows don’t use vibrancy (an effect that can pull color into a window from the content underneath it), which makes them appear subdued and seem visually farther away than the main and key windows.

A stack of three windows, as follows: An inactive window in the background, an app’s main window in the middle, and a key window appearing above the other two windows.

Creating a custom macOS window

Make sure custom windows use the system-defined appearances. People rely on the visual differences between windows to help them identify the foreground window and know which window will accept their input. When you use system-provided components, a window’s background and button appearances update automatically when the window changes state; if you use custom implementations, you need to do this work yourself.

Avoid putting critical information or actions in a bottom bar. People often relocate a window in a way that hides its bottom edge.

If you must include a bottom bar, use it only to display a small amount of information directly related to a window’s contents or to a selected item within it. For example, Finder uses a bottom bar (called the status bar) to display the total number of items in a window, the number of selected items, and how much space is available on the disk. A bottom bar is small, so if you have more information to display, consider using an inspector, which typically presents information on the trailing side of a split view.

Using the title bar in a macOS window

Display a title when necessary. For app and game windows, the title is the name of the app or game. For document windows, the title is the name of the document or Untitled (for new documents). If you need to use a filename as a title, consider using the file’s display name, which reflects people’s preference for showing or hiding a file extension and may be localized. If your app can open multiple windows that have the same title, like Untitled, append a numeric suffix starting with the second window — for example, Untitled, Untitled 2, Untitled 3, and so on.

Make sure people can still interact with your window if you hide the title bar. Provide alternative ways — like menus — to close and minimize the window. Make sure people can still drag the frame to move the window. If the window has a toolbar and no title bar, make sure there’s enough space in the toolbar to drag the window without activating toolbar items.

visionOS

visionOS defines two main window styles: default and volumetric. Both a default window (called a window) and a volumetric window (called a volume) can display 2D and 3D content, and people can view multiple windows and volumes at the same time in both the Shared Space and a Full Space.

An illustration representing a window in visionOS. The illustration consists of two parallel rounded rectangles, slightly separated and displayed on an angle, positioned above a window bar.
A window

An illustration representing a volume in visionOS. The illustration consists of a translucent cube. The base of the cube is darker than the other sides. The front of the cube is positioned above a window bar.
A volume

The system defines the initial position of the first window or volume people open in your app or game. In both the Shared Space and a Full Space, people can move windows and volumes to new locations.

visionOS windows

The default window style consists of an upright plane that uses an unmodifiable background material called glass and includes a close button, window bar, and resize controls that let people close, move, and resize the window. A window can also include a Share button, tab bar, toolbar, and one or more ornaments. By default, visionOS uses dynamic scale to help a window’s size appear to remain consistent regardless of its proximity to the viewer. For developer guidance, see DefaultWindowStyle.

A screenshot of a window for an app named 'Hello World' in visionOS. The window includes text and buttons for entering different experiences.
A window

Prefer using a window to present a familiar interface and to support familiar tasks. Help people feel at home in your app by displaying an interface they’re already comfortable with, reserving more immersive experiences for the meaningful content and activities you offer. If you want to showcase bounded 3D content like a game board, consider using a volume.

Retain the window’s glass background. The default glass background helps your content feel like part of people’s surroundings while adapting dynamically to lighting and using specular reflections and shadows to communicate the window’s scale and position. Removing the glass material tends to cause UI elements and text to become less legible and to no longer appear related to each other; using an opaque background obscures people’s surroundings and can make a window feel constricting and heavy.

Choose an initial window size that minimizes empty areas within it. By default, a window measures 1280x720 pt. When a window first opens, the system places it about two meters in front of the wearer, giving it an apparent width of about three meters. Too much empty space inside a window can make it look unnecessarily large while also obscuring other content in people’s space.

Aim for an initial shape that suits a window’s content. For example, a default Keynote window is wide because slides are wide, whereas a default Safari window is tall because most webpages are much longer than they are wide. For games, a tower-building game is likely to open in a taller window than a driving game.

Choose a minimum and maximum size for each window to help keep your content looking great. People appreciate being able to resize windows as they customize their space, but you need to make sure your layout adjusts well across all sizes. If you don’t set a minimum and maximum size for a window, people could make it so small that UI elements overlap or so large that your app or game becomes unusable. For developer guidance, see Positioning and sizing windows.

A screenshot of a window for an app in visionOS. The window includes text that discusses objects in orbit, and it includes buttons for viewing a satellite, the moon, and a telescope. The satellite button is selected and a 3D satellite is displayed.
A window containing 3D content

Minimize the depth of 3D content you display in a window. The system adds highlights and shadows to the views and controls within a window, giving them the appearance of depth and helping them feel more substantial, especially when people view the window from an angle. Although you can display 3D content in a window, the system clips it if the content extends too far from the window’s surface. To display 3D content that has greater depth, use a volume.

visionOS volumes

You can use a volume to display 2D or 3D content that people can view from any angle. A volume includes window-management controls just like a window, but unlike in a window, a volume’s close button and window bar shift position to face the viewer as they move around the volume. For developer guidance, see VolumetricWindowStyle.

A screenshot of a volume containing a 3D globe in visionOS, beside a window.
A volume

Prefer using a volume to display rich, 3D content. In contrast, if you want to present a familiar, UI-centric interface, it generally works best to use a window.

Place 2D content so it looks good from multiple angles. Because a person’s perspective changes as they move around a volume, the location of 2D content within it might appear to change in ways that don’t make sense. To pin 2D content to specific areas of 3D content inside a volume, you can use an attachment.

In general, use dynamic scaling. Dynamic scaling helps a volume’s content remain comfortably legible and easy to interact with, even when it’s far away from the viewer. On the other hand, if you want a volume’s content to represent a real-world object, like a product in a retail app, you can use fixed scaling (this is the default).

Take advantage of the default baseplate appearance to help people discern the edges of a volume. In visionOS 2 and later, the system automatically makes a volume’s horizontal “floor,” or baseplate, visible by displaying a gentle glow around its border when people look at it. If your content doesn’t fill the volume, the system-provided glow can help people become aware of the volume’s edges, which can be particularly useful in keeping the resize control easy to find. On the other hand, if your content is full bleed or fills the volume’s bounds — or if you display a custom baseplate appearance — you may not want the default glow.

Consider offering high-value content in an ornament. In visionOS 2 and later, a volume can include an ornament in addition to a toolbar and tab bar. You can use an ornament to reduce clutter in a volume and elevate important views or controls. When you use an attachment anchor to specify the ornament’s location, such as topBack or bottomFront, the ornament remains in the same position, relative to the viewer’s perspective, as they move around the volume. Be sure to avoid placing an ornament on the same edge as a toolbar or tab bar, and prefer creating only one additional ornament to avoid overshadowing the important content in your volume. For developer guidance, see ornament(visibility:attachmentAnchor:contentAlignment:ornament:).

Choose an alignment that supports the way people interact with your volume. As people move a volume, the baseplate can remain parallel to the floor of a person’s surroundings, or it can tilt to match the angle at which a person is looking. In general, a volume that remains parallel to the floor works well for content that people don’t interact with much, whereas a volume that tilts to match where a person is looking can keep content comfortably usable, even when the viewer is reclining.

Resources

Split views

Multitasking

Developer documentation

Windows — SwiftUI

WindowGroup — SwiftUI

UIWindow — UIKit

NSWindow — AppKit

Videos

Change log

Date

Changes

June 10, 2024

Updated to include guidance for using volumes in visionOS 2 and added game-specific examples.

June 21, 2023

Updated to include guidance for visionOS.

Current page is Windows