Guides and Sample Code


macOS Human Interface Guidelines

On This Page

About Windows

A window provides a frame for viewing and interacting with content in an app.

Although users tend to view most rectangular areas on the screen as “windows,” developers need to understand the differences in the five main varieties of windows in macOS.

image: ../Art/document_window_2x.png

A document window contains file-based user data.

An app window is the main window of an app that is not document-based.

image: ../Art/app_window_2x.png
image: ../Art/panel_2x.png

A panel floats above other windows and provides tools or controls that users can work with while documents are open. In some cases, a panel can be translucent. For more information about panels, see Panels.

A dialog appears in response to a user action and typically provides ways users can complete the action. A dialog requires a response from the user before it can close. For more information about dialogs, see Dialogs.

image: ../Art/sheet_2x.png
image: ../Art/alert_2x.png

An alert is a special type of dialog that appears when a serious problem occurs, such as an error. Because an alert is a dialog, it also requires a user response before it can close. For more information about alerts, see Alerts.

As you can see in these examples of windows, the overall look of a window in macOS is subtle and understated. In addition, some areas of a window can be translucent, such as the toolbar and the sidebar. The visually muted effect of a window helps users focus on the content that’s important to them.

Window Anatomy

A window consists of window-frame areas and a window body. The window-frame areas are the title bar and toolbar, which are typically combined. (In rare cases, a window might also have a bottom bar, which is a window-frame area that appears at the bottom edge of the window.) The window body can extend from the top edge of the window (that is, underneath the combined title bar/toolbar area) to the bottom edge of the window.

The window body represents the main content area of the window. For example, in a Mail message viewer window, the window body contains the mailbox list, the message list, and the selected message.

image: ../Art/window_body_2x.png

macOS defines appearances that can affect the look of controls and views in particular contexts, such as a window’s sidebar. For example, the Mail window shown here uses the vibrant light appearance in the sidebar area. To learn more about this appearance, see NSAppearanceNameVibrantLight.

The Mail sidebar uses a “behind window” blending mode, which brings colors from the content behind the window into the sidebar. In contrast, the toolbar uses an “in window” blend mode, which means that content within the window can blend with content in the toolbar. To learn more about these blending modes, see NSVisualEffectBlendingMode.

macOS specifies a set of control/style combinations that are designed to look good on the toolbar, whether the toolbar is translucent or opaque. You can learn more about these controls in Some Controls Can Be Used in the Window Frame. macOS also defines system colors that are designed to look good on the system-provided appearances. You can learn about these colors in Use System Colors to Integrate with System Appearances.

Every document window, app window, and panel has, at a minimum:

  • A title bar (or a combined title bar and toolbar), so that users can move the window.

  • A close button, so that users have a consistent way to dismiss the window.

A standard document window may also have the following additional elements that an app window or panel might not have:

  • Transient horizontal or vertical scroll bars, or both (if not all the window’s contents are visible)

  • Minimize and fullscreen buttons (note that the fullscreen button changes to a zoom button if the window doesn’t support fullscreen mode or when users hold down the Option key)

  • A proxy icon and a versions menu (after the user has given a document a name and save location for the first time)

  • The title of the document (that functions as the title of the window)

  • Transient resize controls

For example, the TextEdit document window shown here contains a title, a proxy icon, the close, minimize, and fullscreen buttons, and the title bar Versions menu. You can’t see the resize controls in this window, because they are visible only when the pointer rests above a window edge. Similarly, the only part of the Versions menu that’s visible in this window is the disclosure control that’s to the right of the document title.

image: ../Art/document_window_parts_2x.png

The TextEdit window shown above also includes an optional window element called the scope bar. A scope bar appears below the toolbar and allows users to narrow down a search operation or to filter objects or other operations by identifying specific sets of characteristics. To learn more about scope bars, see Searching In a Window.

Rarely, a window displays a bottom bar, which is a window frame area that appears below the main content area of the window body. A bottom bar contains controls that directly affect the contents and organization of the window, such as the “Add a buddy” and chat controls at the bottom of the Messages window.

image: ../Art/bottom_bar_2x.png

Window Layering

Each app and document window exists in its own layer on a desktop, so that windows and documents from different apps can be interleaved. Clicking a window to bring it to the front doesn’t disturb the layering order of any other window on the desktop.

A window’s depth in the layers is determined by when the user last accessed it. When a user clicks an inactive document window or chooses it from the app’s Window menu, only that document—and any open panel associated with it—is brought to the front.

Users can bring all of an app’s windows forward by clicking the app icon in the Dock or by choosing Bring All to Front in the app’s Window menu. These actions bring forward all of the app’s open windows, maintaining their onscreen location, size, and layering order within the app.

Panels are always in the top layer. They are visible only when their app is active, and they float on top of any open document windows in the app.

Users can view all of an app’s open windows by activating App Exposé. In App Exposé view, users can choose one of the open windows on the current desktop or scroll to find an open window on a different desktop. Users can also cycle forward or backward through an app’s open windows on the current desktop by using Command-Backquote (Command-`) and Command-Shift-Backquote (Command-Shift-`). If full keyboard access is on, they can cycle through all windows by using Control-F4 and Shift-Control-F4.

Main, Key, and Inactive Windows

Windows can look different based on how the user is interacting with them. The foremost document or app window that is the focus of the user’s attention is called the main window. The main window is often also the key window, which is the window that accepts user input. For example, the “close window” keyboard shortcut, Command-W, always targets the key window.

Although the main window is often also the key window, this is not always the case. Sometimes a window other than the main window takes the focus of the input device, while the main window remains the focus of the user’s attention. For example, users might be working in a document window when they need to open a standalone inspector or the Colors window to make adjustments. In this situation, the document window remains the main window, but the inspector or Colors window is the key window.

Main and key windows are both active windows. By default, only an active window uses any translucency. In other words, UI elements that can be translucent, such as toolbars, title bars, and sidebars, appear translucent only when their window is active.

Inactive windows are open windows that are not in the foreground. In an inactive window, translucent UI elements are opaque by default. Here you can see the visual distinctions between main, key, and inactive windows.

image: ../Art/inactive_main_key_2x.png