Guides and Sample Code


macOS Human Interface Guidelines

On This Page


A dialog is a window that is designed to elicit a response from the user. Many dialogs—the Print dialog, for example—allow users to provide several responses at one time.

macOS provides three main ways to present dialogs.

image: ../Art/doc_modal_sheet_2x.png

Document modal. A document-modal dialog prevents the user from doing anything else within a particular document. The user can switch to other documents in the app and to other apps. Document-modal dialogs should be sheets, which are described in Using Document-Modal Dialogs (Sheets).

App modal. An app modal dialog prevents the user from interacting fully with the current app, although the user can switch to another app. An example of an app-modal dialog is the Open dialog (described in The Open Dialog).

image: ../Art/app_modal_2x.png
image: ../Art/modeless_2x.png

Modeless. A modeless dialog enables users to change settings in the dialog while still interacting with document windows. The Find window in many word processors is an example of a modeless dialog.

In addition to these main dialog types, macOS provides an alert, which is a special type of dialog that can be document modal or app modal. In general, if the error condition or notification applies to a single document, the alert is document modal (that is, a sheet). If the alert applies to the state of the app as a whole, or to more than one document or window belonging to the app, the alert is app modal. For guidelines on when to use alerts and how to design them, see Alerts.

Using Document-Modal Dialogs (Sheets)

A sheet is a modal dialog that is attached to a particular document or window, preventing users from interacting with the document or window until they dismiss the dialog. To avoid annoying users, use a sheet only when necessary.

Because a sheet is attached to the window from which it emerges, users never lose track of which window the dialog applies to. The TextEdit locked dialog shown here is an example of a sheet.

image: ../Art/sheet_example_2x.png

A sheet animates into view as if it were emerging from a window’s toolbar (or title bar, if no toolbar is present). When a sheet opens on a window near the edge of the screen and the sheet is wider than the window it’s attached to, the sheet causes the window to move away from the edge. When the sheet is dismissed, the window returns to its previous position.

Only one sheet can be open for a window at any one time. If the user’s response to a sheet causes another sheet to open for that document, the first sheet closes before the second one opens.

In general, a sheet is a good way to present:

  • A modal dialog for an activity that is specific to a particular document, such as exporting, attach files, or print files.

  • A modal dialog that is specific to a single-window app that does not create documents. For example, a single-window utility app might use a sheet to request acceptance of a licensing agreement from the user.

  • Other window-specific dialogs that are typically dismissed by users before they proceed with their task.

If necessary, display a sheet on top of any active panels that are related to the current document window. However, if the user leaves a sheet open and clicks another document in the same app, the inactive window and its sheet should go behind any open panels.

Avoid using sheets if multiple open windows can show different parts of the same document at the same time. A sheet is not useful in this situation, because it implies that the changes users make apply only to one portion of the document. In this type of situation, it’s better to use an app modal dialog to help users understand that changes in one window affect the content in other windows.

Use a sheet when multiple documents can appear in a single window at different times. For example, a tabbed browser can display different documents in a single window at different times. A sheet is appropriate in this situation, even though it applies to only the document that is currently visible in the window. Because users must in effect dismiss the current document before viewing a different document in the same window, they should first dismiss the sheet.

Don’t use a sheet if users need to see or interact with the window in order to address the dialog. For example, if the dialog requests information that the user must get from the window, the dialog should not be a sheet. In this case, a modeless dialog allows users to see or copy information in the window and apply it to the dialog.

Don’t use a sheet for a modeless operation in which users need to observe the effects of their changes. In this situation, a panel is a better choice because users can leave it open while they make changes to their content.

Don’t use a sheet on a window that doesn’t have a title bar. Sheets should emerge from a definite visual edge.

Accepting and Applying User Input in a Dialog

Because dialogs are small, transient UI elements, users don’t expect to have in-depth interactions with them.

Make it easy for users to enter information. As you design a dialog, keep the following points in mind to help you make user interaction easy:

  • When appropriate, display default values for controls and text fields so that the user can verify information rather than enter it from scratch.

  • Display a selection or an insertion point in the first location that accepts user input—a text entry field or a list, for example.

  • When it provides an obvious user benefit, ensure that static text is selectable. For example, a user should be able to copy an error message, a serial number, or IP address to paste elsewhere.

In general, changes that a user makes in a dialog should appear to take effect immediately. To support the appearance of immediate effect, you need to validate the information users enter and you need to decide when to apply their changes.

As much as possible, do error checking as the user enters information. If you wait to check for errors until the user tries to dismiss the dialog, you might have to present an alert, which is not a good user experience. It’s better to check for errors as soon as possible, because it allows users to fix the problem before they leave the context of the dialog.

Avoid validating input after each keystroke. Too-frequent validation can annoy users and slow down your app. It’s better to design your interface to automatically disallow invalid input. For example, your app could automatically convert lowercase characters to uppercase when appropriate.

Use the length of an operation to determine whether to perform it automatically. Sometimes, it’s appropriate for your app to automatically perform an operation based on user input; other times, it’s better when the user initiates the operation—for example, by clicking a button. In general, it’s acceptable to automatically perform an operation that completes quickly and returns user control within a couple of seconds. For an operation that takes a longer time to execute, display an estimate of the time required to complete the operation and let the user initiate it.

Provide an Apply button when it makes sense. An Apply button can be appropriate in a dialog that displays multiple settings that affect the user’s view of data. In this situation, an Apply button allows the user to preview the effect of the selected settings without committing to the changes.

Be cautious about using an Apply button for operations that take a long time to implement or undo; it might not be obvious to users that they can interrupt or reverse the process. In particular, save dialogs or dialogs that allow users to make changes that can’t be previewed easily should not include an Apply button.

Don’t use an Apply button to mean the same thing as the OK button. In particular, clicking an Apply button should not dismiss a dialog because the user should first decide whether to accept the previewed changes (by clicking OK) or to reject them (by clicking Cancel). When the user dismisses the dialog without clicking OK, all previewed changes should be discarded.

Expanding Dialogs

Sometimes you need to provide the user with additional information or functionality in a dialog, but you don’t want to display it all the time. To do this, you use one of the disclosure controls to expand the dialog and reveal the additional information or capability to the user.

Use a disclosure button to provide additional choices in a dialog. In particular, the disclosure button is the appropriate choice when the additional choices are directly related to selections that are offered in a pop-up or command pop-down menu in a dialog. When users click the disclosure button, the dialog expands to reveal selections in addition to those listed in the pop-up or command pop-down menu. (For more information about how to use a disclosure button in your dialog, see Disclosure Button.)

Use a disclosure triangle to reveal details that elaborate on the primary information in a dialog. When users open the disclosure triangle, the dialog expands, revealing additional information and, if appropriate, extra functionality. (For more information about how to use a disclosure triangle in your dialog, see Disclosure Triangle.)

Respond appropriately when users can resize a dialog that contains columns of data. If users can resize a dialog that displays columns (such as the Open dialog), the columns should grow and additional columns should appear. All other elements should remain the same size and be anchored to the right, center, or left side of the dialog.

Dismissing Dialogs

Users expect all the buttons at the bottom right of a dialog to dismiss the dialog. A button that initiates an action is furthest to the right. This rightmost button, called the action button, confirms the main point of the dialog. The Cancel button is to the left of the action button.

Usually the rightmost button or the Cancel button is the default button. A default button has color to let users know that when they press Return or Enter, the default button is activated.

image: ../Art/dialog_button_default_2x.png

Use a default button only if the user’s most likely action is harmless. Make the default button represent the action that the user is most likely to perform if that action isn’t potentially dangerous. Users sometimes press Return merely to dismiss a dialog, without reading its content, so it’s crucial to ensure that the default button performs a harmless action.

Don’t use a default button if the user’s most likely action is dangerous. An example of a dangerous action is one that causes a loss of user data. When there is no default button, pressing Return or Enter has no effect; the user must explicitly click a button to dismiss the dialog. This guideline protects users from accidentally damaging their work by pressing Return or Enter without fully understanding the dialog’s message. You can consider using a safe default button, such as Cancel, or not using a default button at all.

Don’t use a default button if you use the Return key in the dialog’s text fields. Having two behaviors for one key can confuse users and make the interface less predictable. Also, users might press Return one too many times and dismiss the dialog (and activate the default button) without meaning to.

In general, include a Cancel button. The Cancel button returns the computer to the state it was in before the dialog appeared. It means “forget I mentioned it.” Also, make sure that the keyboard shortcut Command-period and the Esc (Escape) key are mapped to the Cancel button.

Ensure that Cancel undoes applied changes. If your dialog includes an Apply button that helps users see the effect of changes before committing to them, make sure that clicking Cancel undoes all of the applied changes. Cancel should never silently commit the changes the user previewed by clicking Apply. For more guidelines on using an Apply button, see Accepting and Applying User Input in a Dialog.

Place a third button for dismissing the dialog to the left of the Cancel button. If the third button could result in data loss—Don’t Save, for example—try to position it at least 24 points away from the “safe” buttons (Cancel and Save, for example).

Place a button that affects the contents of the dialog itself in the left end of the dialog. If there is no Help button, locate a button that affects dialog contents so that its left edge is aligned with the main dialog text. If there is a Help button, place the button to the right of the Help button. For example, the Help button is to the left of the Show Details button in the Print dialog, which expands the dialog to display more information about the print job.

image: ../Art/dialog_buttons_with_help_2x.png

Preferences Windows

A preferences window is a modeless dialog that contains settings that the user changes infrequently. In general, the user opens a preferences window to change the default way an app displays an item or performs a task, then closes the window, and expects the new settings to have taken effect. To provide a good preferences experience in your app, see Preferences.

Often, a preferences window has a toolbar that contains items that function as pane switchers. When the user clicks an item in this type of toolbar, the content area of the preferences window switches to display a different view, called a pane. This design is useful for apps that need to provide multiple settings in each of several different categories. For example, the Safari preferences window contains a toolbar that allows user to choose among categories of settings, such as bookmarks, appearance, and RSS.

image: ../Art/safari_prefs_2x.png

Don’t enable customization of a pane-switcher toolbar in a preferences window. A pane-switcher toolbar in a preferences window does not provide a shortcut to frequently used commands, but instead acts as a convenient way to group settings. If users customize this type of toolbar, they might forget that hidden settings are still available. For the same reason, it makes sense to disable the ability to hide the toolbar in a preferences window, too.

Maintain the selected appearance of an item in a pane-switcher toolbar. When the user clicks an item in a pane-switcher toolbar, the window displays a different pane. It’s important to indicate which item is currently selected by maintaining the item’s selected appearance. For example, in the Safari preferences window, you can see the background highlighting that indicates the Tabs item is the active one.

image: ../Art/pane_switcher_2x.png

Don’t allow resizing or include active minimize or zoom buttons in a preferences window. Remember that preferences windows are intended to give users a place to make occasional adjustments to the way an app behaves, so there should be no need for a preferences window to be resized or to remain open for a long time.

Use the title of the current pane to title the preferences window. The preferences window title should be the same as the title of the currently selected pane even if you don’t use a pane-switcher toolbar to change panes. (Note that if your preferences window does not contain multiple panes, its title should be “App Name Preferences”.) In addition, a changeable-pane preferences window should remember which pane the user selected the last time the window was open.

Use the standard menu item and keyboard shortcut to open your preferences window. Users expect most apps to include a Preferences command in the app menu. In addition, most users expect to be able to use the Command-comma keyboard shortcut to open an app’s preferences window.

The Open Dialog

The Open dialog gives users a consistent way to find and open an item in an app.

image: ../Art/nondocument_open_dialog_2x.png

You can extend the Open dialog as appropriate for your app. For example, the TextEdit Open dialog contains an additional section that allows users to specify different encodings.

image: ../Art/customized_open_dialog_2x.png

As much as possible, use the Open command to mean “open,” and not “act upon.” The Open dialog is best suited to helping users find an item to open in your app. To help users find items to use in an app-specific task, use a Choose dialog instead. For guidance on using a Choose dialog, see The Choose Dialog.

Make sure users can use the Open command to display the Open dialog. Users expect the Open command to display an Open dialog. Contrast this with the Choose dialog, which can be displayed by different commands in different apps. It’s also a good idea to provide the standard Command-O keyboard shortcut to display the Open dialog, because most users are accustomed to it.

Specify a reasonable default location. For the iCloud Open dialog, iCloud is the default location. You should not change this behavior. See iCloud for more information.

For other dialogs, the default location is typically one of the predefined folders in the user’s home folder. If the user selects a different folder, make sure you remember the user’s selection so that it appears the next time the dialog is displayed.

Consider including a pop-up menu that allows users to filter the types of files that appear in the list. Display items that don't meet the filtering criteria as dimmed. You can supplement this list with custom types and specify the default to show when the dialog opens. Include an All Applicable Files item, which doesn’t have to be the default item.

Include an Open Recent command to accompany the Open command. The Open Recent command allows users to reopen recently opened documents without using the Open dialog.

Extend the functionality of the Open dialog, if appropriate. For example, it’s a good idea to support document preview so that users can be sure they’re opening the document they intend. In addition, you can enable multiple selection if your app allows more than one document to be opened at one time.

The Choose Dialog

A Choose dialog gives users a consistent way to select an item as the target of a task. An app can have more than one Choose dialog, but only one can be open at a time.

A Choose dialog:

  • Can be opened by various commands

  • Can support multiple selection

  • Supports document preview

  • Can be resized

For example, Calendar displays a choose dialog that allows users to choose a calendar to import.

image: ../Art/choose_dialog_2x.png

Customize the Choose dialog title to reflect the task (if the dialog is not a sheet). By default, the dialog’s title is “Choose.” If, for example, the command that displays the dialog is Choose Picture, title the dialog “Choose Picture.” If it’s helpful, also change the Choose button to something more specific.

Consider including a pop-up menu that allows users to filter the types of files that appear in the list. Display items as dimmed that don't meet the filtering criteria. You can supplement this list with custom types and specify the default to show when the dialog opens. Include an All Applicable Files item, but it does not have to be the default.

The Print and Page Setup Dialogs

Users expect most documents to be printable, or to include a printable version. macOS provides standard dialogs that your app can display so that users can have a consistent printing experience in every app they use.

The Print dialog is focused on printing the current document, but it also includes features that can be provided by individual apps and by printer modules. The Page Setup dialog gives users a way to set the scaling and orientation options for a document, based on the intended output paper size and the printer.

By default, the Print dialog appears in its minimal form (shown here in the dialog attached to a TextEdit document). Users can get additional functionality in the expanded Print dialog by clicking Show Details.

image: ../Art/print_dialog_2x.png

In the expanded Print dialog, user options are provided through the features pop-up menu, which displays panes that are drawn and controlled by printing dialog extensions (PDEs). PDEs are provided by the operating system, printer modules, and apps. Apple provides a number of printing panes. In the expanded Print dialog shown here, you can see the “Print header and footer” and “Rewrap contents to fit page” options that TextEdit provides.

image: ../Art/expanded_print_dialog_2x.png

You might want to provide custom print panes that give users options that are relevant to the types of content your app handles. For example, Contacts helps users print their contact information in different styles, such as mailing label, envelope, and list. Here are some specific guidelines to keep in mind if you implement custom printing features:

  • Choose a menu item name that doesn’t conflict with menu items already in the features pop-up menu, and that accurately describes the content of the pane. For an app, the menu item should be the app name.

  • Make sure the features you implement are appropriate for your app. For example, an option to print in reverse order should be provided by the operating system, not by your app. (Implementing this feature requires the app to know the hardware’s capabilities.)

  • Make interdependencies among options clear to users. For example, if a user selects double-sided printing, the option to print on transparencies should become unavailable.

  • Separate more advanced features from frequently used features. When the user chooses to display the advanced features, there should be an “advanced options” title above the advanced controls.

  • When appropriate, show users what effect their choices will have. For example, a thumbnail image that shows the effect of changing a tone control helps users determine desired settings.

  • Save a user’s printing preferences for a document, at least while the document is open, and provide a way for users to save custom settings.

If you think users would appreciate being able to set printing attributes for different printers or different paper sizes, provide a Page Setup dialog in your app. Be sure to save the settings that users make in this dialog with the document. Below, you can see the Page Setup dialog that TextEdit provides.

image: ../Art/page_attributes_2x.png

Find Windows

A Find window is a modeless dialog that opens in response to the Find command and that provides an interface for specifying items to search for.

Find windows can be useful in document-creation apps, because users can use one Find window to search for a term in several different open documents. If it makes sense in your UI, however, offer find functionality in a scope bar. A scope bar is attached to a window and provides both search and filtering capabilities to users. For more information about scope bars and how to use them in your app, see Searching In a Window.

Save Dialogs

Users expect to be able to specify a title and save location when they choose to save a document for the first time. To perform the initial save, users expect to see the standard Save dialog.

The Save dialog has two states: minimal (also known as collapsed) and expanded. Clicking the disclosure button toggles between these states. For example, in the minimal Save dialog (shown here displayed by TextEdit), you can see the closed disclosure button to the right of the document title.

image: ../Art/minimal_save_2x.png

The minimal Save dialog contains these elements:

  • The Save As text field, in which users enter the document name. Expert users can enter pathnames by pressing Command-Shift-G. (Note that the pathname separator is the “/” character.)

  • The Where pop-up menu, which contains mounted volumes, folders in the Finder sidebar, and Recent Places (which are the five most recent folders the user opened or saved documents to).

  • A Save button (this is the default button).

  • A Cancel button, which dismisses the dialog and returns the app to its previous state.

  • A disclosure button. Clicking it displays the expanded Save dialog. (For more information about how to use disclosure buttons, see Disclosure Button.)

  • An optional accessory view, which can contain information such as text encoding settings. (In general, the accessory view should not be necessary.)

The expanded Save dialog gives users a broader view of the file system than they get in the minimal Save dialog’s Where pop-up menu. For example, the expanded TextEdit Save dialog displays the browsable file-system view.

image: ../Art/expanded_save_2x.png

In addition to the items in the minimal Save dialog, the expanded Save dialog includes the following:

  • Back and Forward buttons to navigate back and forth between selections made in the list or column view.

  • A source list that mirrors the Finder sidebar.

  • Options for navigating the file system.

  • A File Format (or Format) pop-up menu, which displays a list of file formats from which the user can choose.

  • A New Folder button, which displays an app-modal dialog that asks the user to name the new folder, and then creates it.

  • A “Hide extension” checkbox, which allows the user to control whether or not the filename’s extension (.jpg, for example) is visible.

In addition to the Save dialog, a document-based app can display the close confirmation save dialog. The close confirmation save dialog (shown when users close a document window that contains data that has never been saved) has the same minimal and expanded states as the standard Save dialog. For example, TextEdit displays the close confirmation save dialog when the user closes a new document window with unsaved changes.

image: ../Art/close_confirmation_2x.png

As with the standard Save dialog, the close confirmation save dialog includes a disclosure button to the right of the Save As text field. Clicking this button expands the dialog to show a similar browsable file system view. The differences between the close confirmation save dialog and the standard Save dialog are due to the fact that it’s unclear whether the user intends to discard their work. For this reason, the text at the top of the dialog explains why it has appeared, and the Don’t Save button at the bottom of the dialog allows the user to decline to save their work.

There are a few ways in which you can customize a Save dialog so that it provides a better user experience.

Specify a reasonable default location. The default location appears in the Where pop-up menu (in the minimal Save dialog) and in the Finder view (in the expanded Save dialog). Typically, the default location is one of the predefined folders in the user’s home folder. If the user selects a different folder, make sure you remember the user’s selection so that it appears the next time the dialog is displayed.

Allow users to choose whether to view the file extension. Select the “Hide extension” checkbox as the default (that is, filename extensions should not appear in user-visible filenames unless the user requests them). If the user changes the state of the checkbox for a particular document, the next new document should match the last user-selected state, even after the user quits and reopens the app. The filename in the Save As field updates in real time as the checkbox is selected or deselected.

Display the default new document name before users save the document for the first time. In general, this name should be “untitled.” In the Save As field, display the default name as selected so that users can easily replace it with a custom name. If the user chooses to make the filename extension visible, the extension is not selected.

Display custom UI elements below the location-selection elements. In the minimal Save dialog, custom UI elements go between the Where pop-up menu and the buttons at the bottom of the dialog. In the expanded Save dialog, custom elements go between the file-system browser and the buttons at the bottom of the dialog.