Guides and Sample Code

Developer

macOS Human Interface Guidelines

iBooks
On This Page

Controls

The system offers a range of standard controls that are designed for use in the app region of the Touch Bar. Use these controls whenever possible for maximum consistency.

Buttons

Buttons initiate app-specific actions when tapped, and can include an icon and a title.

image: ../Art/touchbar_button_2x.png

Prefer icons over titles. Strive to design clear icons that stand on their own without requiring supporting text.

Keep titles short. Overly long titles can crowd the Touch Bar.

Make tasteful bezel color changes. The system-provided bezel is designed to have an appearance similar to physical keyboard buttons. If your app requires a custom bezel color, darker colors are recommended.

Toggles

A toggle is a style of button that switches between on and off states when tapped.

image: ../Art/touchbar_toggle_2x.png

Let the background indicate the state. The system automatically changes the background appearance of buttons in an off state, so there’s no need to indicate the state using color, text, or a different icon.

Use toggles in place of checkboxes and radio buttons. If you need a control that lets people choose between two states, use a toggle button.

Candidate Lists

A candidate list offers autocompletion suggestions during text entry. The user can tap a suggestion to accept and insert it into the active text field or text view on the main screen. A candidate list can be expanded or collapsed by the user. An expanded candidate list replaces other controls that reside within the expansion area.

image: ../Art/touchbar_candidatelist_2x.png

Character Pickers

When tapped, a character picker opens a popover that includes a list of special characters, such as emoji. The user can tap one to insert it into the active text field or text view on the main screen.

image: ../Art/touchbar_characterpicker_2x.png
image: ../Art/touchbar_characterpicker2_2x.png

Color Pickers

When tapped, a color picker opens a popover that includes controls for selecting a color. A color picker can be configured to display a color picker icon, a stroke color picker icon, or a text color picker icon. Regardless of the icon used, all color pickers display the same popover.

image: ../Art/touchbar_colorpicker_2x.png
image: ../Art/touchbar_colorpicker2_2x.png

Use icons as intended. Use the stroke color picker icon for selecting a stroke color. Use the text color picker icon for selecting a text color. For other color selection scenarios, use the color picker icon.

Labels

A label displays read-only text, usually for the purpose of describing a control.

In general, avoid labels. Although the Touch Bar can display labels, they should generally be avoided because they’re not interactive. Instead, focus on designing meaningful icons for your controls. If you must include a label, keep it as short as possible.

Prefer titles over labels when supplementing complex icons. If the meaning of a control’s icon isn’t clear enough on its own, consider including a short title within the control to provide context.

image: ../Art/touchbar_buttontitles_2x.png

Popovers

In a collapsed state, a popover appears as a single button in the Touch Bar.

image: ../Art/touchbar_popover_2x.png

When expanded, the popover replaces the current set of controls in the app region with a modal overlay containing a transient set of controls. In this modal overlay, the user must make a selection or tap an exit button to return to the collapsed state and the previous set of controls.

image: ../Art/touchbar_popover2_2x.png

Collapsed popovers are expanded by tapping them. Optionally, they can also expand in response to a touch-and-hold gesture. Popovers that support touch and hold include a trailing carat decoration.

image: ../Art/touchbar_popupbutton_2x.png

A popover expanded by touch-and-hold can present the same overlay it presents when tapped, or a completely different overlay. In a touch-and-hold overlay, the user can slide the pressed finger to a control to make a selection and lift the finger to collapse the popover.

image: ../Art/touchbar_popupbutton2_2x.png

Use popovers sparingly. Most controls in the Touch Bar should be directly actionable with a single tap.

Avoid nesting popovers. In general, people should rarely need to navigate more than one level in the Touch Bar.

Reserve touch-and-hold for simple popovers. Touch and hold is intended primarily for displaying an overlay that includes a simple set of options, such as a single segmented control, from which the user can make a selection.

Indicate choice selection in a collapsed popover. When an expanded popover includes a list of options, the collapsed state should denote the currently selected option.

Provide an obvious exit path. Make sure people always know how to collapse a popover and return to the previous set of controls.

Scrubbers

A scrubber lets the user swipe left and right to navigate through content like a list of dates or a group of photos. Scrubbers can be fixed or free, and are highly customizable—but should retain an appearance that doesn’t feel out of place in the Touch Bar.

Fixed Scrubbers

A fixed scrubber allows for fluid, continuous interaction with a set of arranged content, such as open Safari tabs. As the user swipes a finger across the scrubber, items beneath the finger become highlighted. Depending on the scrubber’s configuration, a selection is made as the user’s finger moves from item to item, or when the user lifts the finger. If the amount of content exceeds the size of a fixed scrubber, the scrubber automatically scrolls to reveal additional items as the user’s finger nears the edge of the control. In a fixed scrubber, the user’s finger directly moves the selection, rather than the content.

image: ../Art/touchbar_scrubber_2x.png

Free Scrubbers

A free scrubber presents content in a freely scrollable list, such as a list of Calendar dates, which the user directly scrolls by swiping. Depending on the scrubber’s configuration, a single item becomes selected when the item resides at a specific location such as in the center of the scrubber, or when the scrubber is stationary and the user taps the item.

image: ../Art/touchbar_wheel_2x.png

Use predictable and logically ordered values. Many values in a free scrubber may be hidden when the scrollable list is stationary. It's best when people can predict what these values are, such as with a list of alphabetized countries, so they can move through the list quickly.

Avoid displaying large value lists. Long lists can be tedious to navigate in the Touch Bar. If you have a large list of values, consider presenting it on the main screen instead of the Touch Bar, so the keyboard or trackpad can be used for navigation.

Segmented Controls

A segmented control is a linear set of two or more segments, each of which functions as a button—usually configured as a toggle. Within the control, all segments are equal in width. Like buttons, segments can contain text and icons.

image: ../Art/touchbar_segmentedcontrol_2x.png

Limit the number of segments to improve usability. Wider segments are easier to tap.

Prefer icons over titles. Strive to design clear icons that stand on their own without requiring supporting text.

Try to keep segment content size consistent. Because all segments have equal width, it doesn’t look great if content fills some segments but not others.

Keep titles short. Overly long titles can crowd the Touch Bar.

Prefer darker colors for bezel color changes. The system-provided bezel is designed to have an appearance similar to physical keyboard buttons. If your app requires a custom bezel color, darker colors are recommended.

Sharing Service Pickers

Sharing service pickers offer a convenient way for people to share text, images, and other content with apps, social media accounts, and other services. When tapped, a sharing service picker displays a popover that contains sharing buttons.

image: ../Art/touchbar_sharingservicepicker_2x.png
image: ../Art/touchbar_sharingservicepicker2_2x.png

Enable a sharing service picker only when there’s content to share. If the user has no text, images, or other sharable content selected, the sharing service picker should be disabled.

Sliders

A slider is a horizontal track with a control called a thumb, which you can slide with your finger to move between a minimum and maximum value, such as screen brightness level or position during media playback. As a slider’s value changes, the portion of track between the minimum value and the thumb fills with color.

image: ../Art/touchbar_slider_2x.png

Customize a slider’s appearance to match your app and add value. Consider coordinating a slider’s track color with your app’s color scheme.

Provide left and right icons that illustrate the meaning of the minimum and maximum values. A slider that adjusts image size, for example, could show a small image icon on the left and a large image icon on the right.