Guides and Sample Code


macOS Human Interface Guidelines

On This Page

Text Controls

Static Text Field

A static text field displays text that can't be modified by the user.

image: ../Art/static_text_2x.png

Static text fields have two states: active and dimmed.

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

Text Input Field

A text input field accepts user-entered text.

image: ../Art/text_input_field_2x.png

A text input field (also called an editable text field) is a rectangular area in which the user enters text or modifies existing text. A text input field displays user-supplied text in a system font that is appropriate for the size of the control. In addition, a text input field can contain a token field control, which displays the user input in the form of a draggable token. For more information on tokens, see Token Field.

By default, a text input field supports keyboard focus and password entry.

Use a text input field to get information from the user.

Be sure to perform appropriate edit checks when you receive user input. For example, if the only legitimate value for a field is a string of digits, an app should issue an alert if the user types characters other than digits. In most cases, the appropriate time to check the data in the field is when the user clicks outside the field or presses the Return, Enter, or Tab key.

Be sure to use a combo box if you want to combine a menu or list of choices with a text input field. Don’t try to create one by putting a text input field and a menu together. For more information about combo boxes, see Combination Box.

In general, display an introductory label with a text input field. A label helps users understand what type of information they should enter. Generally, these labels should have title-style capitalization (described in Use the Right Capitalization Style in Labels and Text).

In general, ensure that the length of a text input field comfortably accommodates the length of the expected input. The length of a text input field helps users gauge whether they’re inputting the appropriate information.

Space multiple text input fields evenly. If you want to use more than one text input field in a window, you need to leave enough space between them so users can easily see which input field belongs with each introductory label. If you need to position more than one text input field at the same height (that is, in a horizontal line), be sure to leave plenty of space between the end of one text field and the introductory label of the next. Typically, however, multiple text input fields are stacked vertically, as in a form users fill out. In addition, if you display multiple text input fields in a window, be sure they all have the same length.

Token Field

A token field creates a movable token out of text.

image: ../Art/token_field_2x.png

In general, use a token field control in a text input field. As the user types in the text input field, the token field control invokes text completion after a delay that you specify. When the user types the comma character or presses Return, the preceding text input is transformed into a token. For more information about text input fields, see Text Input Field.

If appropriate, add a contextual menu to a token. (Note that you have to add code to support the addition of a contextual menu.) In a token field’s menu, you might offer more information about the token and ways to manipulate it. In Mail, for example, the token menu displays information about the token (the email address associated with the name) and items that allow the user to edit the token or add its associated information to Contacts.

image: ../Art/token_menu_2x.png

Search Field

A search field accepts text from users, which can be used as input for a search (shown here in a toolbar).

image: ../Art/search_field_toolbar_2x.png

A search:

  • Looks like a text field with rounded ends

  • Can be configured to begin searching while the user is still entering text, or to wait until the user is finished

  • Displays the magnifying icon in its left end by default

  • Can also contain an icon the user clicks to cancel the search or clear the field

Use a search field to enable search functionality within your app.

Decide when to start the search. You can begin searching as soon as the user starts typing, or wait until the user presses Return or Enter. If searching occurs while the user is still typing, the behavior is more like a find in which results are filtered as the entered text becomes more specific. This behavior is especially useful when the search field is in a scope bar that focuses on a window’s contents. If search should occur after the user finishes typing, you might want to enable a search term completion menu so that users can choose from commonly searched terms.

In general, avoid using a menu to display search history. For privacy reasons, users might not appreciate having their search history displayed. You might instead use the menu to allow users to choose different types of searches or define the context or scope of a search. Note that a scope bar is well-suited to enabling this type of searching. For more information, see Searching In a Window.

Avoid supplying an introductory label. Users are familiar with the distinctive appearance of a search field, so there is no need to label it. The exception to this is when you place a search field in a toolbar; in this case, you need to supply the label “Search” to be displayed when users customize the toolbar to show icons and text or text only.

Display placeholder text, if it helps users understand how search works in your app. A search field can display a placeholder text in its left end. For example, the search field in the Safari toolbar can display one of three common search engines (users can choose the search engine they want to use in the search field menu).