Window Anatomy

A window consists of a frame area and body area that let the user view and interact with content in an app. A window can appear onscreen alongside other windows, or it can fill the entire screen (see Full-Screen Mode). In a window that’s not full-screen, the user can click and drag the frame to reposition the window on screen. If the window supports resizing, the user can also click and drag the edges of the window to resize it.

For developer guidance, see NSWindow.

Types of Windows

There are many varieties of windows in macOS.

Type of Window Description Examples
Document window Presents data for viewing, editing, and printing by the user. A TextEdit document.
A Keynote document.
A PDF in Preview.
A window displaying a website in Safari.
App window Presents content and functions that aren’t document-related. The primary window in an app is considered the main app window. The Calendar window.
The Contacts window.
A Finder window.
Panel Floats above other windows to provide information, configuration options, or tools for interacting with content in another window. For guidance, see Panels. The standard color panel.
The standard Fonts panel.
The document inspector in Preview.
Dialog Appears in response to a user action and requires user action, such as a button click, to dismiss or proceed with an action. See Dialogs. An open file dialog.
A save file dialog.
A print dialog.
Alert A type of dialog that appears modally to provide important information about an error condition or warn the user about a potentially hazardous situation or consequence. For guidance, see Alerts. A warning when emptying the trash.
An alert calling your attention to a server connection error.

Tip A popover is a transient view that nonintrusively provides information or editing functions related to the current context. A popover isn’t considered a window even though it’s similar to a panel in appearance and functionality. For guidance, see Popovers.

The Window Frame

The frame is the portion of window that surrounds body content. A window frame can include the following areas.

Title Bar

The title bar resides at the top of a window and includes options for closing, minimizing, and zooming (or expanding to full-screen mode) the window. These options are usually visible, but can be hidden as a group, such as when playing a movie in QuickTime Player, or individually disabled. Most title bars display title text, although this isn’t always the case. For example, the title bar of an alert is empty. The title bar of a document window may also display an icon and let the user click the title to change the document’s name, tags, and location. A title bar should generally be visible, but can be hidden in an immersive app like a game.

Provide a title unless there’s enough context that one is unnecessary. For document windows, the title is the name of the document or Untitled (for new documents). For app windows, the title is the name of the app. For other windows, the title may be a specific type of functionality, such as Inspector.

Use the display name when using a file name as a window title. The display name reflects the user’s preference for showing or hiding a file extension and may also include localized text.

Don’t display file or folder paths in the title bar. Paths are generally too long to fit in the title bar without clipping, and they’re difficult to parse at a glance. Show the name in the title bar instead. If you want to expose the complete path, do so in another way, such as through an inspector pane.

Use numeric suffixes to differentiate duplicate titles. The first instance of a title shouldn’t have a numeric suffix. When there are other windows with the same title, however, they should include numeric suffixes, starting with 2. For example, Untitled, Untitled 2, Untitled 3.

Make sure the user can still interact with your window if you hide the title bar. Provide alternate ways—like menus—to close and minimize the window. Make sure the user can still click and 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 click and drag the window without activating toolbar items.

Toolbar

A toolbar, when included, resides beneath the title bar (or is integrated with the title bar) and includes controls—known as toolbar items—that provide quick access to frequently used commands and features. For example, the default toolbar on a message viewer window in Mail includes controls for performing tasks like composing, archiving, deleting, replying to, forwarding, flagging, and searching messages.

Separate title bar and toolbar

Integrated title bar and toolbar

A toolbar can be hidden in full-screen mode to increase focus on content. Many apps also let the user customize the toolbar by adding and removing items, and choosing whether to display items as icons, text, or both.

For guidance, see Toolbars.

Tab Bar

A tab bar, when included, lets the user switch between multiple body content views within a single window. For example, a Safari window lets the user create separate tabs, each of which displays a different website. A tab bar resides beneath the title bar and toolbar, and the user can click a tab to view its content. The user can also click and drag a tab out of a tab bar to display it in a separate window. The Finder and many other apps in macOS support tabbed windows—all windows have tabs enabled by default.

Bottom Bar

In rare cases, a window may include a bottom bar that resides below the body area and includes controls for affecting the content of the window. The bottom bar in the Buddies window in Messages, for example, includes options for initiating a chat, FaceTime call, or screen sharing session with the selected buddy.

The Window Body

The body area displays the main content of the window. This content can fill the entire body area, such as a website in a Safari window or image in Preview, or the content can be divided into subviews. For example, the body area of a Finder window could include a sidebar and a column view. Content that extends beyond the bounds of its parent view in the body area is scrollable.

For related guidance, see Sidebars and Scroll Views.

Scope Bar

A scope bar, when included above the body content, lets the user narrow down a search operation or filter content based on specific attributes. When searching for files and folders in the Finder, for example, a scope bar offers controls for scoping the search to specific locations and attributes (like file name, type, extension, and tags). A scope bar resides below the title bar, toolbar, and tab bar.

For related guidance, see Search and Spotlight, and Search Fields.

Window States

The windows displayed onscreen are layered in a hierarchy that’s based on when they were last accessed. More recently accessed windows are layered higher and the hierarchy changes as the user switches between apps and windows. Within the window hierarchy, there are three window states.

Main Window State

The foremost window that’s the focus of the user’s attention within an app is considered that app’s main window. There can be one main window per app.

Key Window State

The window that currently accepts user input is considered the key window (sometimes referred to as the active window). Keyboard shortcuts, like Command-W to close a window, always target the key window. There can be a single key window onscreen at any time. Often, the front app’s main window is also the key window. However, this isn’t always the case. A panel floating above the main window is sometimes the key window.

Inactive Window State

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

Window Appearances

Main, key, and inactive windows vary in their onscreen appearance. Inactive windows are subdued and appear to fall backward, deferring to the main and key windows. The title bar options for closing, minimizing, and zooming are colorized in the key window and gray in other windows. These appearance differences makes it easy for the user to quickly identify the main and key windows.

Within a window, elements like toolbars and sidebars can be opaque or they can implement translucency by adopting vibrancy. Vibrancy is a subtle blurring effect that dynamically blends the foreground and background using a careful balance of lightening and darkening techniques. This effect evokes a feeling of depth by enabling views and controls to hint at content residing in the background. Note that vibrancy is disabled in inactive windows.

For guidance, see Translucency.

Activating Windows

When multiple windows are visible, the user can click one to activate it—bring it to the front and make it the key window. The user can also click an app’s Dock icon to bring all of the app’s windows forward; the most recently accessed app window becomes the key window.

Consider offering a menu of window commands. Many apps have a Window menu, which includes commands for minimizing the key window, zooming the key window, navigating tabs, moving individual windows to the front, and moving all windows to the front.

Mission Control also lets the user navigate between an app’s windows. See Mission Control.

Tip Some windows—usually panels like the Colors panel and Fonts panel—only become the key window when the user clicks the window's title bar or an interface element that requires keyboard input, like a text field.