Guides and Sample Code


macOS Human Interface Guidelines

On This Page


Push Button

A push button performs an app-specific action.

image: ../Art/push_buttons_2x.png

A push button:

  • Is designed for use in the window body only, not in the window-frame areas. To learn about controls that you can use in window-frame areas, see Some Controls Can Be Used in the Window Frame.

  • Always contains text, never an image.

  • Is white, unless it’s the default button in a dialog. For more information about dialog controls, see Dismissing Dialogs.

  • May open another window to complete its operation.

  • May respond to a force click by spring loading an action or accelerating its operation.

Use a push button in the window body to perform an instantaneous action, such as Print or Delete.

Avoid using a push button to mimic the behavior of other controls. Users expect an immediate action to occur when they click a push button, including the opening of another window or the dismissal of a dialog. In particular:

  • Don’t use a push button to indicate a state, such as on or off. Instead, you can use checkboxes to indicate state, as described in Checkbox.

  • Don’t use a push button as a label. Instead, use static text to label elements and provide information in the interface, as described in Static Text Field.

  • Avoid associating a menu with a push button.

Use enough space between buttons so that users can click a specific one easily. In particular, if a push button can lead to a potentially dangerous or destructive action (such as Delete), place it far enough away from safe buttons so that users are unlikely to click it accidentally.

Avoid displaying an image in a standard push button. A standard push button should contain text that describes the action it performs.

Use a verb or verb phrase and title-style capitalization for the title of a push button. The title should describe the action the button performs—Save, Close, Print, Delete, Change Password, and so on. If a push button acts on a single setting or entity, name the button as specifically as possible; “Choose Picture…,” for example, is more helpful than “Choose…” Because buttons initiate an immediate action, there’s no need to include “now” in the button title. To learn more about title-style capitalization, see Use the Right Capitalization Style in Labels and Text.

Add an ellipsis to the title if the button immediately opens another window, dialog, or app to perform its action. An ellipsis prepares users to expect another window to open in which they complete the action the button initiates. For example, the Print & Scan preferences pane uses ellipsis characters in the names of buttons that open the print queue window and show information about the printer’s options and supplies.

image: ../Art/push_buttons_ellipsis_2x.png

Resize a button’s width to accommodate the title. If you don’t make a button wide enough, the end caps clip the text. Note that the height of a push button is fixed for each size.

In general, don’t use a static text label to introduce a push button. Avoid an introductory label by clearly describing the push button action in the button title.

Radio Buttons

A group of radio buttons displays a set of mutually exclusive, but related, choices.

image: ../Art/radio_button_examples_2x.png

A radio button:

  • Is designed for use in the window body only, not in the window-frame areas. To learn about controls that you can use in window-frame areas, see Some Controls Can Be Used in the Window Frame.

  • Is not dynamic; that is, the button’s content and label don’t change depending on the context.

  • Doesn’t display custom text or images.

Use a group of radio buttons when you need to display a set of choices from which the user can choose only one.

Use checkboxes, instead of radio buttons, to display a set of choices from which the user can choose more than one at the same time. Also, if you need to display a single setting, state, or choice that the user can either accept or reject, don’t use a single radio button; use a checkbox instead. To learn more about checkboxes, see Checkbox.

Consider using a pop-up menu if you need to display more than five items. It’s best when a group of radio buttons contains at least two items and a maximum of about five. To learn more about pop-up menus, see Pop-Up Menu.

Don’t use a radio button to initiate an action. Instead, use a push button to initiate an action. Note that the choice of a radio button can change the state of the app. In Speech preferences, for example, the user must choose the second listening method (“Listen continuously with keyword”), to enable the keyword setup preferences.

image: ../Art/radio_enables_further_2x.png

Give each radio button a text label that describes the choice it represents. Users need to know precisely what they’re choosing when they select a radio button. Give radio button labels sentence-style capitalization, as described in Use the Right Capitalization Style in Labels and Text. In addition, introduce a group of radio buttons with a label that describes the choices represented by the group.

In a horizontal group of radio buttons, make the space between each pair of radio buttons consistent. It works well to measure the space needed to accommodate the longest radio button label and use that measurement consistently. Also, use the Interface Builder guides to ensure that the baseline of the introductory label is aligned with the baseline of the label of the first button in a group.


A checkbox describes a state, action, or value that can be either on or off.

image: ../Art/checkbox_examples_2x.png

A checkbox:

  • Is designed for use in the window body only, not in the window-frame areas. To learn about controls that you can use in window-frame areas, see Some Controls Can Be Used in the Window Frame.

  • Doesn’t display custom text or images

Use a checkbox to allow users to choose between two opposite states, actions, or values.

Use radio buttons, not checkboxes, to provide a set of choices from which users can choose only one. To learn more about using radio buttons in your app, see Radio Buttons.

Use the alignment of a group of checkboxes to show how they’re related. If there are several independent values or states that you want users to control, you can provide a group of checkboxes that are all left-aligned. If, on the other hand, you need to allow users to make an on-off type of choice that can lead to additional, related on-off choices, you can display checkboxes in a hierarchy that indicates the relationship.

For example, in the Clock pane of Date & Time preferences, the options for customizing the display of date and time in the menu bar are inactive unless the user selects “Show date and time in menu bar.” In addition to using unambiguous labels, the Clock pane uses this indentation to show users that some settings are dependent on others.

image: ../Art/dependent_checkboxes_2x.png

Provide a label for each checkbox that clearly implies two opposite states. The label should make it clear what happens when the option is selected or deselected. If you can’t find an unambiguous label, consider using a pair of radio buttons instead, so you can clarify the two states with two different labels. Give checkbox labels sentence-style capitalization, unless the state or value is the title of another element in the interface that is capitalized. For more on this style, see Use the Right Capitalization Style in Labels and Text.

In addition, it’s a good idea to provide a label that introduces a group of checkboxes and clearly describes the set of choices they represent. Use the Interface Builder guides to ensure that the baseline of the introductory label is aligned with the baseline of the label of the first button in a group.

If appropriate, display a dash inside a checkbox. A dash indicates that the selection represents more than one state, in a way that is similar to the use of a dash in a menu. For more information about this, see Symbols Can Give Users Information About State.

In general, arrange checkboxes in a column. When checkboxes are arranged vertically, it’s easier for users to distinguish one state from another.

Gradient Button

A gradient button performs an instantaneous action related to a view, such as a source list.

image: ../Art/gradient_button_example_2x.png

A gradient button:

  • Can have push-button, toggle, or pop-up menu behavior

  • Contains only images; in particular, a gradient button doesn't contain text

Use a gradient button to offer functionality that’s directly related to a source list or other view, such as a browser or column view.

Because the function of a gradient button is closely tied to the view with which it’s associated, there’s little need to describe its action in a label.

When possible, use system-provided images, such as the Action and the Add images, because their meaning is familiar to users. For more information on the system-provided images, see System-Provided Images.

Disclosure Triangle

A disclosure triangle displays (or discloses) information or functionality associated with the primary information in a window.

image: ../Art/disclosure_triangles_2x.png

A disclosure triangle is in the closed position (that is, pointing to the right) by default. When the user clicks a disclosure triangle, it points down and the additional information is displayed.

Use a disclosure triangle when you want to provide a simple default view of something while also allowing users to view more details or perform additional actions at specific times. For example, you can use a disclosure triangle to:

  • Reveal more information in dialogs that have a minimal state and an expanded state. For example, you might want to use a disclosure triangle to hide explanatory information about a choice that most users aren’t interested in seeing.

  • Reveal subordinate items in a hierarchical list. For example, the Mail Photo Browser panel uses a disclosure triangle to reveal specific iPhoto categories.

    image: ../Art/disclosure_triangles2_2x.png

Supply a label for a disclosure triangle in a dialog. The label should indicate what is disclosed or hidden and it should change, depending on the position of the disclosure triangle. For example, when the disclosure triangle is closed the label might be “Show advanced settings;” when the disclosure triangle is open the label can change to “Hide advanced settings.”

Don’t use a disclosure triangle to display additional choices associated with a specific control. If you need to do this, use a disclosure button instead. For more information about this control, see Disclosure Button.

Disclosure Button

A disclosure button expands a dialog or panel to display a wider range of choices related to a specific selection control.

image: ../Art/disclosure_button1_2x.png

A disclosure button:

  • Contains a small triangular icon.

  • Is in the closed position—that is, pointing down—by default. When the user clicks a disclosure button, the window expands to reveal the additional choices, and the disclosure button changes to point up.

Use a disclosure button when you need to provide additional options that are closely related to a specific list of choices.

Don’t use a disclosure button to display additional information or functionality, or to display subordinate items in a list. If you need to display additional information or functionality related to the contents of a window or a section of a window, or if you need a way to reveal subordinate items in a hierarchical list, use a disclosure triangle instead. For more information on this control, see Disclosure Triangle.

Place a disclosure button close to the control to which it’s related. Users need to understand how the expanded choices are related to their current task. For example, TextEdit puts a disclosure button close to the Save As text field, so that users understand that the expanded view of the dialog will help them choose a location for their document.

image: ../Art/disclosure_button_dialog_2x.png

Scope Button

A scope button specifies the scope of an operation, such as a search, or defines a set of scoping criteria.

image: ../Art/scope_button_example_2x.png

Scope buttons are available in two different styles:

The recessed scope button: image: ../Art/recessed_scope_button_2x.png

The round rectangle scope button: image: ../Art/round_rect_scope_button_2x.png

Typically, round rectangle and recessed scope buttons contain text, but they can instead contain images.

Use a recessed scope button to display types or groups of objects or locations that users select to narrow the focus of a search or other operation.

Use a round rectangle scope button to allow users to save a set of search criteria and to change or set scoping criteria.

For example, the Finder uses round rectangle scope buttons to display search criteria, such as creation and last opened dates, and to provide a save search button. The Finder location buttons, such as This Mac and Shared, are recessed scope buttons.

image: ../Art/scope_buttons_2x.png

If you want to display an image in a scope button, be sure to consider the system-provided images before you spend time designing your own. If you decide to design a custom icon for use in a scope button, see Toolbar Items.

The Help Button

The Help button opens a window that displays app-specific help.

image: ../Art/help_button_2x.png

The Help button is always a clear, circular button. The Help button is available in a single size and it always contains the standard macOS question mark graphic.

When users click a Help button, the system-provided Help Viewer app opens to a page in the current app’s help book. An app can determine whether the help book should open to a top-level page or to a page that is appropriate for the context of the button.

Don’t create a custom button to perform the function of the standard Help button.

In dialogs (including preferences windows) and drawers, the Help button can be located in either bottom corner. In a dialog that includes OK and Cancel buttons (or other buttons used to dismiss the dialog), the Help button should be in the lower-left corner, vertically aligned with the buttons. In a dialog that doesn’t include OK and Cancel buttons, such as a preferences window, the Help button should be in the lower-right corner. For example, the Mail Signatures preference pane displays a Help button in the lower-right corner.

image: ../Art/help_button_in_window_2x.png

For information on providing help in your app, see User Assistance.