{"abstract":[{"text":"A token field is a type of text field that can convert text into ","type":"text"},{"inlineContent":[{"text":"tokens","type":"text"}],"type":"emphasis"},{"text":" that are easy to select and manipulate.","type":"text"}],"hierarchy":{"paths":[["doc:\/\/com.apple.documentation\/documentation\/technologies","doc:\/\/com.apple.HIG\/design\/human-interface-guidelines","doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/components","doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/navigation-and-search"]]},"identifier":{"interfaceLanguage":"swift","url":"doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/token-fields"},"kind":"article","legalNotices":{"copyright":"Copyright © 2026 Apple Inc. All rights reserved.","privacyPolicy":"https:\/\/www.apple.com\/privacy\/privacy-policy","termsOfUse":"https:\/\/www.apple.com\/legal\/internet-services\/terms\/site.html"},"metadata":{"availableLanguages":["en-US","zh-CN","ja-JP","ko-KR"],"customMetadata":{"supported-platforms":"macos"},"images":[{"identifier":"components-token-fields-thumbnail.png","type":"card"}],"role":"article","title":"Token fields"},"primaryContentSections":[{"content":[{"inlineContent":[{"identifier":"components-token-field-intro.png","type":"image"}],"type":"paragraph"},{"inlineContent":[{"text":"For example, Mail uses token fields for the address fields in the compose window. As people enter recipients, Mail converts the text that represents each recipient’s name into a token. People can select these recipient tokens and drag to reorder them or move them into a different field.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"text":"You can configure a token field to present people with a list of suggestions as they enter text into the field. For example, Mail suggests recipients as people type in an address field. When people select a suggested recipient, Mail inserts the recipient into the field as a token.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"identifier":"token-fields-suggestion.png","type":"image"}],"type":"paragraph"},{"inlineContent":[{"text":"An individual token can also include a contextual menu that offers information about the token or editing options. For example, a recipient token in Mail includes a contextual menu with commands for editing the recipient name, marking the recipient as a VIP, and viewing the recipient’s contact card, among others.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"identifier":"token-fields-contextual.png","type":"image"}],"type":"paragraph"},{"inlineContent":[{"text":"Tokens can also represent search terms in some situations; for guidance, see ","type":"text"},{"identifier":"doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/search-fields","isActive":true,"type":"reference"},{"text":".","type":"text"}],"type":"paragraph"},{"anchor":"Best-practices","level":2,"text":"Best practices","type":"heading"},{"inlineContent":[{"inlineContent":[{"text":"Add value with a context menu.","type":"text"}],"type":"strong"},{"text":" People often benefit from a ","type":"text"},{"identifier":"https:\/\/developer.apple.com\/design\/human-interface-guidelines\/context-menus","isActive":true,"type":"reference"},{"text":" with additional options or information about a token.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"inlineContent":[{"text":"Consider providing additional ways to convert text into tokens.","type":"text"}],"type":"strong"},{"text":" By default, text people enter turns into a token whenever they type a comma. You can specify additional shortcuts, such as pressing Return, that also invoke this action.","type":"text"}],"type":"paragraph"},{"inlineContent":[{"inlineContent":[{"text":"Consider customizing the delay the system uses before showing suggested tokens.","type":"text"}],"type":"strong"},{"text":" By default, suggestions appear immediately. However, suggestions that appear too quickly may distract people while they’re typing. If your app suggests tokens, consider adjusting the delay to a comfortable level.","type":"text"}],"type":"paragraph"},{"anchor":"Platform-considerations","level":2,"text":"Platform considerations","type":"heading"},{"inlineContent":[{"inlineContent":[{"text":"Not supported in iOS, iPadOS, tvOS, visionOS, and watchOS.","type":"text"}],"type":"emphasis"}],"type":"paragraph"},{"anchor":"Resources","level":2,"text":"Resources","type":"heading"},{"anchor":"Related","level":4,"text":"Related","type":"heading"},{"inlineContent":[{"identifier":"doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/text-fields","isActive":true,"type":"reference"}],"type":"paragraph"},{"inlineContent":[{"identifier":"doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/search-fields","isActive":true,"type":"reference"}],"type":"paragraph"},{"inlineContent":[{"identifier":"doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/context-menus","isActive":true,"type":"reference"}],"type":"paragraph"},{"anchor":"Developer-documentation","level":4,"text":"Developer documentation","type":"heading"},{"inlineContent":[{"identifier":"doc:\/\/com.apple.documentation\/documentation\/AppKit\/NSTokenField","isActive":true,"type":"reference"},{"text":" — AppKit","type":"text"}],"type":"paragraph"}],"kind":"content"}],"schemaVersion":{"major":0,"minor":3,"patch":0},"sections":[],"topicSectionsStyle":"compactGrid","references":{"components-context-menus-thumbnail.png":{"alt":"A stylized representation of a contextual menu beneath a clicking pointer. The image is tinted red to subtly reflect the red in the original six-color Apple logo.","identifier":"components-context-menus-thumbnail.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.HIG\/components-context-menus-thumbnail@2x.png"},{"traits":["2x","dark"],"url":"\/images\/com.apple.HIG\/components-context-menus-thumbnail~dark@2x.png"}]},"components-navigation-and-search-thumbnail.png":{"alt":"A stylized representation of a window with a sidebar, suggesting navigation and search. The image is tinted red to subtly reflect the red in the original six-color Apple logo.","identifier":"components-navigation-and-search-thumbnail.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.HIG\/components-navigation-and-search-thumbnail@2x.png"},{"traits":["2x","dark"],"url":"\/images\/com.apple.HIG\/components-navigation-and-search-thumbnail~dark@2x.png"}]},"components-search-fields-thumbnail.png":{"alt":"A stylized representation of a search field containing placeholder text and a dictation icon. The image is tinted red to subtly reflect the red in the original six-color Apple logo.","identifier":"components-search-fields-thumbnail.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.HIG\/components-search-fields-thumbnail@2x.png"},{"traits":["2x","dark"],"url":"\/images\/com.apple.HIG\/components-search-fields-thumbnail~dark@2x.png"}]},"components-text-fields-thumbnail.png":{"alt":"A stylized representation of a text field containing a value. The image is tinted red to subtly reflect the red in the original six-color Apple logo.","identifier":"components-text-fields-thumbnail.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.HIG\/components-text-fields-thumbnail@2x.png"},{"traits":["2x","dark"],"url":"\/images\/com.apple.HIG\/components-text-fields-thumbnail~dark@2x.png"}]},"components-token-field-intro.png":{"alt":"A stylized representation of a text field containing a person's name formatted as a token. The image is tinted red to subtly reflect the red in the original six-color Apple logo.","identifier":"components-token-field-intro.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.HIG\/components-token-field-intro@2x.png"},{"traits":["2x","dark"],"url":"\/images\/com.apple.HIG\/components-token-field-intro~dark@2x.png"}]},"components-token-fields-thumbnail.png":{"alt":"A stylized representation of a text field containing tokens for prefix and number values. The image is tinted red to subtly reflect the red in the original six-color Apple logo.","identifier":"components-token-fields-thumbnail.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.HIG\/components-token-fields-thumbnail@2x.png"},{"traits":["2x","dark"],"url":"\/images\/com.apple.HIG\/components-token-fields-thumbnail~dark@2x.png"}]},"components.png":{"alt":"","identifier":"components.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.HIG\/components@2x.png"},{"traits":["2x","dark"],"url":"\/images\/com.apple.HIG\/components~dark@2x.png"}]},"doc://com.apple.HIG/design/Human-Interface-Guidelines/components":{"abstract":[{"text":"Learn how to use and customize system-defined components to give people a familiar and consistent experience.","type":"text"}],"identifier":"doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/components","images":[{"identifier":"overview.svg","type":"icon"},{"identifier":"components.png","type":"card"}],"kind":"article","role":"collectionGroup","title":"Components","type":"topic","url":"\/design\/human-interface-guidelines\/components"},"doc://com.apple.HIG/design/Human-Interface-Guidelines/context-menus":{"abstract":[{"text":"A context menu provides access to functionality that’s directly related to an item, without cluttering the interface.","type":"text"}],"identifier":"doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/context-menus","images":[{"identifier":"components-context-menus-thumbnail.png","type":"card"}],"kind":"article","role":"article","title":"Context menus","type":"topic","url":"\/design\/human-interface-guidelines\/context-menus"},"doc://com.apple.HIG/design/Human-Interface-Guidelines/navigation-and-search":{"abstract":[],"identifier":"doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/navigation-and-search","images":[{"identifier":"navigation-and-search.svg","type":"icon"},{"identifier":"components-navigation-and-search-thumbnail.png","type":"card"}],"kind":"article","role":"collectionGroup","title":"Navigation and search","type":"topic","url":"\/design\/human-interface-guidelines\/navigation-and-search"},"doc://com.apple.HIG/design/Human-Interface-Guidelines/search-fields":{"abstract":[{"text":"A search field lets people search a collection of content for specific terms they enter.","type":"text"}],"identifier":"doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/search-fields","images":[{"identifier":"components-search-fields-thumbnail.png","type":"card"}],"kind":"article","role":"article","title":"Search fields","type":"topic","url":"\/design\/human-interface-guidelines\/search-fields"},"doc://com.apple.HIG/design/Human-Interface-Guidelines/text-fields":{"abstract":[{"text":"A text field is a rectangular area in which people enter or edit small, specific pieces of text.","type":"text"}],"identifier":"doc:\/\/com.apple.HIG\/design\/Human-Interface-Guidelines\/text-fields","images":[{"identifier":"components-text-fields-thumbnail.png","type":"card"}],"kind":"article","role":"article","title":"Text fields","type":"topic","url":"\/design\/human-interface-guidelines\/text-fields"},"doc://com.apple.HIG/design/human-interface-guidelines":{"abstract":[{"text":"The HIG contains guidance and best practices that can help you design a","type":"text"},{"text":" ","type":"text"},{"text":"great experience for any Apple platform.","type":"text"}],"identifier":"doc:\/\/com.apple.HIG\/design\/human-interface-guidelines","images":[{"identifier":"human-interface-guidelines-page-image-card.png","type":"card"}],"kind":"article","role":"collection","title":"Human Interface Guidelines","type":"topic","url":"\/design\/human-interface-guidelines"},"doc://com.apple.documentation/documentation/AppKit/NSTokenField":{"abstract":[{"text":"A text field that converts text into visually distinct tokens.","type":"text"}],"fragments":[{"kind":"keyword","text":"class"},{"kind":"text","text":" "},{"kind":"identifier","text":"NSTokenField"}],"identifier":"doc:\/\/com.apple.documentation\/documentation\/AppKit\/NSTokenField","kind":"symbol","navigatorTitle":[{"kind":"identifier","text":"NSTokenField"}],"role":"symbol","title":"NSTokenField","type":"topic","url":"\/documentation\/appkit\/nstokenfield"},"doc://com.apple.documentation/documentation/technologies":{"abstract":[],"identifier":"doc:\/\/com.apple.documentation\/documentation\/technologies","kind":"technologies","role":"overview","title":"Technologies","type":"topic","url":"\/documentation\/technologies"},"https://developer.apple.com/design/human-interface-guidelines/context-menus":{"identifier":"https:\/\/developer.apple.com\/design\/human-interface-guidelines\/context-menus","title":"context menu","titleInlineContent":[{"text":"context menu","type":"text"}],"type":"link","url":"https:\/\/developer.apple.com\/design\/human-interface-guidelines\/context-menus"},"human-interface-guidelines-page-image-card.png":{"alt":"An illustration of several Liquid Glass components such as toggles, sliders, and buttons, atop a neutral background. The transparent components cast shadows on the background and allow their colored elements, like a blue slider track and a green toggle backing, to show through, highlighting the Liquid Glass material's lensing effect.","identifier":"human-interface-guidelines-page-image-card.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.HIG\/human-interface-guidelines-page-image-card@2x.png"}]},"navigation-and-search.svg":{"alt":"An icon of a window with a sidebar, suggesting navigation and search.","identifier":"navigation-and-search.svg","type":"image","variants":[{"svgID":"navigation-and-search","traits":["1x","light"],"url":"\/images\/com.apple.HIG\/navigation-and-search.svg"}]},"overview.svg":{"alt":"An icon of a grid comprised of four squares.","identifier":"overview.svg","type":"image","variants":[{"svgID":"overview","traits":["1x","light"],"url":"\/images\/com.apple.HIG\/overview.svg"}]},"token-fields-contextual.png":{"alt":"A partial screenshot of a Mail compose window in which one recipient token reveals a menu of commands.","identifier":"token-fields-contextual.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.HIG\/token-fields-contextual@2x.png"},{"traits":["2x","dark"],"url":"\/images\/com.apple.HIG\/token-fields-contextual~dark@2x.png"}]},"token-fields-suggestion.png":{"alt":"A partial screenshot of a Mail compose window in which tokens represent some recipients.","identifier":"token-fields-suggestion.png","type":"image","variants":[{"traits":["2x","light"],"url":"\/images\/com.apple.HIG\/token-fields-suggestion@2x.png"},{"traits":["2x","dark"],"url":"\/images\/com.apple.HIG\/token-fields-suggestion~dark@2x.png"}]}},"variantOverrides":[{"patch":[{"op":"replace","path":"\/references\/doc:~1~1com.apple.documentation~1documentation~1AppKit~1NSTokenField\/fragments","value":[{"kind":"identifier","text":"NSTokenField"}]}],"traits":[{"interfaceLanguage":"occ"}]}]}