Token Fields

A token field is a type of text field that includes tokens, blocks of text that can be easily selected and manipulated.

When composing a new message in Mail, the address fields are token fields. As you enter recipients, the recipients become tokenized—converted from text into token form. You can select these recipient tokens and drag them to reorder or otherwise work with them individually.

A token field can be configured to present the user with a list of suggested tokens as text is entered into the field. For example, Mail suggests recipients as you type into an address field. If you select a suggested recipient, it’s inserted into the field as a token.

An individual token can also include a contextual menu that’s denoted by a downward chevron character. Such a contextual menu may include information about the token or editing options. In Mail, a recipient token includes a contextual menu with options for things like editing the recipient, marking the recipient as a VIP, and viewing the recipient’s contact card.

Some token fields are accompanied by a separate list of available tokens, which may be selected and dragged into the field. The Language & Region preference pane uses this approach for its date and time format fields. Individual date and time tokens are offered separately and may be dragged into token fields, where formatting options become available via contextual menus.

Add value with a contextual menu. Consider whether the user may benefit from a contextual menu that includes useful options or displays additional information about a token.

Expand the list of characters that invokes tokenization if it makes sense in your app. By default, entered text becomes tokenized whenever the user types a comma. You can specify additional characters, such as carriage return, that should also trigger this action.

Customize the delay before showing suggested tokens. By default, suggestions appear immediately. However, suggestions appearing too quickly can be a distraction while typing. If your app suggests tokens, consider adjusting the delay to a comfortable level.

For related guidance, see Text Fields. For developer guidance, see Token Field Programming Guide and NSTokenField.