cardinale/swift-front
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
swift-front/data/categories/general.json
T
Anthony Cardinale 34bd90e30d Initial release: swift-front skill with Apple HIG integration 
Combines frontend-design aesthetics with swiftui-pro correctness,
grounded in Apple's Human Interface Guidelines (134 articles).

Includes curated HIG reference files for typography, color, layout,
materials, motion, icons, and components, plus full HIG JSON data
for deep lookups.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-25 07:52:07 -04:00

4137 lines
192 KiB
JSON
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"metadata": {
"source": "Apple Human Interface Guidelines",
"source_url": "https://developer.apple.com/design/human-interface-guidelines/",
"generated_at": "2026-03-24T10:09:01.952605+00:00",
"article_count": 134,
"format_version": "1.0",
"purpose": "Agent-readable reference for designing Swift/SwiftUI applications following Apple HIG",
"category": "general"
},
"name": "General",
"articles": [
{
"title": "Activity views",
"url": "https://developer.apple.com/design/human-interface-guidelines/activity-views",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Activity views present sharing activities like messaging and actions like Copy and Print, in addition to quick access to frequently used apps. People typically reveal a share sheet by choosing an Action button while viewing a page or document, or after they’ve selected an item. An activity view can appear as a sheet or a popover, depending on the device and orientation."
},
{
"type": "paragraph",
"text": "You can provide app-specific activities that can appear in a share sheet when people open it within your app or game. For example, Photos provides app-specific actions like Copy Photo, Add to Album, and Adjust Location. By default, the system lists app-specific actions before actions — such as Add to Files or AirPlay — that are available in multiple apps or throughout the system. People can edit the list of actions to ensure that it displays the ones they use most and to add new ones."
},
{
"type": "paragraph",
"text": "You can also create app extensions to provide custom share and action activities that people can use in other apps. (An app extension is code you provide that people can install and use outside of your app.) For example, you might create a custom share activity that people can install to help them share a webpage with a specific social media service. Even though macOS doesn’t provide an activity view, you can create share and action app extensions that people can use on a Mac. For guidance, see Share and action extensions."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Avoid creating duplicate versions of common actions that are already available in the activity view. For example, providing a duplicate Print action is unnecessary and confusing because people wouldn’t know how to distinguish your action from the system-provided one. If you need to provide app-specific functionality that’s similar to an existing action, give it a custom title. For example, if you let people use custom formatting to print a bank transaction, use a title that helps people understand what your print activity does, like “Print Transaction.”"
},
{
"type": "paragraph",
"text": "Consider using a symbol to represent your custom activity. SF Symbols provides a comprehensive set of configurable symbols you can use to communicate items and concepts in an activity view. If you need to create a custom interface icon, center it in an area measuring about 70x70 pixels. For guidance, see Icons."
},
{
"type": "paragraph",
"text": "Write a succinct, descriptive title for each custom action you provide. If a title is too long, the system wraps it and may truncate it. Prefer a single verb or a brief verb phrase that clearly communicates what the action does. Avoid including your company or product name in an action title. In contrast, the share sheet displays the title of a share activity — typically a company name — below the icon that represents it."
},
{
"type": "paragraph",
"text": "Make sure activities are appropriate for the current context. Although you can’t reorder system-provided tasks in an activity view, you can exclude tasks that aren’t applicable to your app. For example, if it doesn’t make sense to print from within your app, you can exclude the Print activity. You can also identify which custom tasks to show at any given time."
},
{
"type": "paragraph",
"text": "Use the Share button to display an activity view. People are accustomed to accessing system-provided activities when they choose the Share button. Avoid confusing people by providing an alternative way to do the same thing."
}
]
},
{
"heading": "Share and action extensions",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Share extensions give people a convenient way to share information from the current context with apps, social media accounts, and other services. Action extensions let people initiate content-specific tasks — like adding a bookmark, copying a link, editing an inline image, or displaying selected text in another language — without leaving the current context."
},
{
"type": "paragraph",
"text": "The system presents share and action extensions differently depending on the platform:"
},
{
"type": "list",
"items": [
"In iOS and iPadOS, share and action extensions are displayed in the share sheet that appears when people choose an Action button.",
"In macOS, people access share extensions by clicking a Share button in the toolbar or choosing Share in a context menu. People can access an action extension by holding the pointer over certain types of embedded content — like an image they add to a Mail compose window — clicking a toolbar button, or choosing a quick action in a Finder window."
]
},
{
"type": "paragraph",
"text": "If necessary, create a custom interface that feels familiar to people. For a share extension, prefer the system-provided composition view because it provides a consistent sharing experience that people already know. For an action extension, include your app name. If you need to present an interface, include elements of your app’s interface to help people understand that your extension and your app are related."
},
{
"type": "paragraph",
"text": "Streamline and limit interaction. People appreciate extensions that let them perform a task in just a few steps. For example, a share extension might immediately post an image to a social media account with a single tap or click."
},
{
"type": "paragraph",
"text": "Avoid placing a modal view above your extension. By default, the system displays an extension within a modal view. While it might be necessary to display an alert above an extension, avoid displaying additional modal views."
},
{
"type": "paragraph",
"text": "If necessary, provide an image that communicates the purpose of your extension. A share extension automatically uses your app icon, helping give people confidence that your app provided the extension. For an action extension, prefer using a symbol or creating an interface icon that clearly identifies the task."
},
{
"type": "paragraph",
"text": "Use your main app to denote the progress of a lengthy operation. An activity view dismisses immediately after people complete the task in your share or action extension. If a task is time-consuming, continue it in the background, and give people a way to check the status in your main app. Although you can use a notification to tell people about a problem, don’t notify them simply because the task completes."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for iOS, iPadOS, or visionOS. Not supported in macOS, tvOS, or watchOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Sheets"
},
{
"type": "paragraph",
"text": "Popovers"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "UIActivityViewController — UIKit"
},
{
"type": "paragraph",
"text": "UIActivity — UIKit"
},
{
"type": "paragraph",
"text": "App Extension Support — Foundation"
}
]
}
],
"platforms": [],
"related": [
{
"title": "Share and action extensions",
"url": "/design/human-interface-guidelines/activity-views#Share-and-action-extensions"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/activity-views#Best-practices"
},
{
"title": "SF Symbols",
"url": "/design/human-interface-guidelines/sf-symbols"
},
{
"title": "Icons",
"url": "/design/human-interface-guidelines/icons"
},
{
"title": "symbol",
"url": "https://developer.apple.com/design/human-interface-guidelines/sf-symbols"
},
{
"title": "icon",
"url": "https://developer.apple.com/design/human-interface-guidelines/icons"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/activity-views#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/activity-views#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/activity-views#Related"
},
{
"title": "Sheets",
"url": "/design/human-interface-guidelines/sheets"
},
{
"title": "Popovers",
"url": "/design/human-interface-guidelines/popovers"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/activity-views#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/activity-views#Videos"
}
],
"image_count": 0
},
{
"title": "Context menus",
"url": "https://developer.apple.com/design/human-interface-guidelines/context-menus",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Although a context menu provides convenient access to frequently used items, it’s hidden by default, so people might not know it’s there. To reveal a context menu, people generally choose a view or select some content and then perform an action, using the input modes their current configuration supports. For example:"
},
{
"type": "list",
"items": [
"The system-defined touch or pinch and hold gesture in visionOS, iOS, and iPadOS",
"Pressing the Control key while clicking a pointing device in macOS and iPadOS",
"Using a secondary click on a Magic Trackpad in macOS or iPadOS"
]
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Prioritize relevancy when choosing items to include in a context menu. A context menu isn’t for providing advanced or rarely used items; instead, it helps people quickly access the commands they’re most likely to need in their current context. For example, the context menu for a Mail message in the Inbox includes commands for replying and moving the message, but not commands for editing message content, managing mailboxes, or filtering messages."
},
{
"type": "paragraph",
"text": "Aim for a small number of menu items. A context menu that’s too long can be difficult to scan and scroll."
},
{
"type": "paragraph",
"text": "Support context menus consistently throughout your app. If you provide context menus for items in some places but not in others, people won’t know where they can use the feature and may think there’s a problem."
},
{
"type": "paragraph",
"text": "Always make context menu items available in the main interface, too. For example, in Mail in iOS and iPadOS, the context menu items that are available for a message in the Inbox are also available in the toolbar of the message view. In macOS, an app’s menu bar menus list all the app’s commands, including those in various context menus."
},
{
"type": "paragraph",
"text": "If you need to use submenus to manage a menu’s complexity, keep them to one level. A submenu is a menu item that reveals a secondary menu of logically related commands. Although submenus can shorten a context menu and clarify its commands, more than one level of submenu complicates the experience and can be difficult for people to navigate. If you need to include a submenu, give it an intuitive title that helps people predict its contents without opening it. For guidance, see Submenus."
},
{
"type": "paragraph",
"text": "Hide unavailable menu items, don’t dim them. Unlike a regular menu, which helps people discover actions they can perform even when the action isn’t available, a context menu displays only the actions that are relevant to the currently selected view or content. In macOS, the exceptions are the Cut, Copy, and Paste menu items, which may appear unavailable if they don’t apply to the current context."
},
{
"type": "paragraph",
"text": "Aim to place the most frequently used menu items where people are likely to encounter them first. When a context menu opens, people often read it starting from the part that’s closest to where their finger or pointer revealed it. Depending on the location of the selected content, a context menu might open above or below it, so you might also need to reverse the order of items to match the position of the menu."
},
{
"type": "paragraph",
"text": "Show keyboard shortcuts in your app’s main menus, not in context menus. Context menus already provide a shortcut to task-specific commands, so it’s redundant to display keyboard shortcuts too."
},
{
"type": "paragraph",
"text": "Follow best practices for using separators. As with other types of menus, you can use separators to group items in a context menu and help people scan the menu more quickly. In general, you don’t want more than about three groups in a context menu. For guidance, see Menus."
},
{
"type": "paragraph",
"text": "In iOS, iPadOS, and visionOS, warn people about context menu items that can destroy data. If you need to include potentially destructive items in your context menu — such as Delete or Remove — list them at the end of the menu and identify them as destructive (for developer guidance, see destructive). The system can display a destructive menu item using a red text color."
}
]
},
{
"heading": "Content",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "A context menu seldom displays a title. In contrast, each item in a context menu needs to display a short label that clearly describes what it does. For guidance, see Menus > Labels."
},
{
"type": "paragraph",
"text": "Include a title in a context menu only if doing so clarifies the menu’s effect. For example, when people select multiple Mail messages and tap the Mark toolbar button in iOS and iPadOS, the resulting context menu displays a title that states the number of selected messages, reminding people that the command they choose affects all the messages they selected."
},
{
"type": "paragraph",
"text": "Represent menu item actions with familiar icons. Icons help people recognize common actions throughout your app. Use the same icons as the system to represent actions such as Copy, Share, and Delete, wherever they appear. For a list of icons that represent common actions, see Standard icons. For additional guidance, see Menus."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for tvOS. Not supported in watchOS."
}
]
},
{
"heading": "iOS, iPadOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Provide either a context menu or an edit menu for an item, but not both. If you provide both features for the same item, it can be confusing to people — and difficult for the system to detect their intent. See Edit menus."
},
{
"type": "paragraph",
"text": "In iPadOS, consider using a context menu to let people create a new object in your app. iPadOS lets you reveal a context menu when people perform a long press on the touchscreen or use a secondary click with an attached trackpad or keyboard. For example, Files lets people create a new folder by revealing a context menu in an area between existing files and folders."
},
{
"type": "paragraph",
"text": "In iOS and iPadOS, a context menu can display a preview of the current content near the list of commands. People can choose a command in the menu or — in some cases — they can tap the preview to open it or drag it to another area."
},
{
"type": "paragraph",
"text": "Prefer a graphical preview that clarifies the target of a context menu’s commands. For example, when people reveal a context menu on a list item in Notes or Mail, the preview shows a condensed version of the actual content to help people confirm that they’re working with the item they intend."
},
{
"type": "paragraph",
"text": "Ensure that your preview looks good as it animates. As people reveal a context menu on an onscreen object, the system animates the preview image as it emerges from the content, dimming the screen behind the preview and the menu. It’s important to adjust the preview’s clipping path to match the shape of the preview image so that its contours, such as the rounded corners, don’t appear to change during animation. For developer guidance, see UIContextMenuInteractionDelegate."
}
]
},
{
"heading": "macOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "On a Mac, a context menu is sometimes called a contextual menu."
}
]
},
{
"heading": "visionOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Consider using a context menu instead of a panel or inspector window to present frequently used functionality. Minimizing the number of separate views or windows your app opens can help people keep their space uncluttered."
},
{
"type": "paragraph",
"text": "In general, avoid letting a context menu’s height exceed the height of the window. In visionOS, a window includes system-provided components above and below its top and bottom edges, such as window-management controls and the Share menu, so a context menu that’s too tall could obscure them. As you consider the number of items to include, be guided by the ways people are likely to use your app. For example, people who use an app to accomplish in-depth, specialist tasks often expect to spend time learning a large number of sophisticated commands and might appreciate contextual access to them. On the other hand, people who use an app to perform a few simple actions may appreciate short contextual menus that are quick to scan and use."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Menus"
},
{
"type": "paragraph",
"text": "Edit menus"
},
{
"type": "paragraph",
"text": "Pop-up buttons"
},
{
"type": "paragraph",
"text": "Pull-down buttons"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "contextMenu(menuItems:) — SwiftUI"
},
{
"type": "paragraph",
"text": "UIContextMenuInteraction — UIKit"
},
{
"type": "paragraph",
"text": "popUpContextMenu(_:with:for:) — AppKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"December 5, 2023",
"Added guidance on hiding unavailable menu items."
],
[
"June 21, 2023",
"Updated to include guidance for visionOS."
],
[
"September 14, 2022",
"Refined guidance on including a submenu and added a guideline on using a context menu to support object creation in an iPadOS app."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/context-menus#Best-practices"
},
{
"title": "Submenus",
"url": "/design/human-interface-guidelines/menus#Submenus"
},
{
"title": "Menus",
"url": "/design/human-interface-guidelines/menus"
},
{
"title": "Content",
"url": "/design/human-interface-guidelines/context-menus#Content"
},
{
"title": "Menus > Labels",
"url": "https://developer.apple.com/design/human-interface-guidelines/menus#Labels"
},
{
"title": "Standard icons",
"url": "/design/human-interface-guidelines/icons#Standard-icons"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/context-menus#Platform-considerations"
},
{
"title": "iOS, iPadOS",
"url": "/design/human-interface-guidelines/context-menus#iOS-iPadOS"
},
{
"title": "Edit menus",
"url": "/design/human-interface-guidelines/edit-menus"
},
{
"title": "macOS",
"url": "/design/human-interface-guidelines/context-menus#macOS"
},
{
"title": "visionOS",
"url": "/design/human-interface-guidelines/context-menus#visionOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/context-menus#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/context-menus#Related"
},
{
"title": "Pop-up buttons",
"url": "/design/human-interface-guidelines/pop-up-buttons"
},
{
"title": "Pull-down buttons",
"url": "/design/human-interface-guidelines/pull-down-buttons"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/context-menus#Developer-documentation"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/context-menus#Change-log"
}
],
"image_count": 0
},
{
"title": "Dock menus",
"url": "https://developer.apple.com/design/human-interface-guidelines/dock-menus",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "The system-provided Dock menu items can vary depending on whether the app is open. For example, the Dock menu for Safari includes menu items for actions like viewing a current window or creating a new window."
},
{
"type": "note",
"text": "NoteAlthough iOS and iPadOS don’t support a Dock menu, people can reveal a similar menu of system-provided and custom items — called Home Screen quick actions — when they long press an app icon on the Home Screen or in the Dock. For guidance, see Home Screen quick actions."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "As with all menus, you need to label Dock menu items succinctly and organize them logically. For guidance, see Menus."
},
{
"type": "paragraph",
"text": "Make custom Dock menu items available in other places, too. Not everyone uses a Dock menu, so it’s important to offer the same commands elsewhere, like in your menu bar menus or within your interface."
},
{
"type": "paragraph",
"text": "Prefer high-value custom items for your Dock menu. For example, a Dock menu can list all currently or recently open windows, making it a convenient way to jump to the window people want. Also consider listing a few of the actions that are most likely to be useful when your app isn’t frontmost or when there are no open windows. For example, Mail includes items for getting new mail and composing a new message in addition to listing all open windows."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Menus"
},
{
"type": "paragraph",
"text": "Home Screen quick actions"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "applicationDockMenu(_:) — AppKit"
}
]
}
],
"platforms": [],
"related": [
{
"title": "Home Screen quick actions",
"url": "/design/human-interface-guidelines/home-screen-quick-actions"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/dock-menus#Best-practices"
},
{
"title": "Menus",
"url": "/design/human-interface-guidelines/menus"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/dock-menus#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/dock-menus#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/dock-menus#Related"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/dock-menus#Developer-documentation"
}
],
"image_count": 0
},
{
"title": "Edit menus",
"url": "https://developer.apple.com/design/human-interface-guidelines/edit-menus",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "In addition to text, an edit menu’s commands can apply to many types of selectable content, such as images, files, and objects like contact cards, charts, or map locations. In iOS, iPadOS, and visionOS, the system automatically detects the data type of a selected item, which can result in the addition of a related action to the edit menu. For example, selecting an address can add an item like Get directions to the edit menu."
},
{
"type": "paragraph",
"text": "Edit menus can look and behave slightly differently in different platforms."
},
{
"type": "list",
"items": [
"In iOS, the edit menu displays commands in a compact, horizontal list that appears when people touch and hold or double-tap to select content in a view. People can tap a chevron on the trailing edge to expand it into a context menu.",
"In iPadOS, the edit menu looks different depending on how people reveal it. When people use touch interactions to reveal the menu, it uses the compact, horizontal appearance. In contrast, when people use a keyboard or pointing device to reveal it, the edit menu opens directly in a context menu.",
"In macOS, people can access editing commands in a context menu they can reveal while in an editing task, as well as through the app’s Edit menu in the menu bar.",
"In visionOS, people use the standard pinch and hold gesture to open the edit menu as a horizontal bar, or they can open it in a context menu."
]
},
{
"type": "paragraph",
"text": "Editing content is rare in tvOS and watchOS experiences, so the system doesn’t provide an edit menu in these platforms."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Prefer the system-provided edit menu. People are familiar with the contents and behavior of the system-provided component, so creating a custom menu that presents the same commands is redundant and likely to be confusing. For a list of standard edit menu commands, see UIResponderStandardEditActions."
},
{
"type": "paragraph",
"text": "Let people reveal an edit menu using the system-defined interactions they already know. For example, people expect to touch and hold on a touchscreen, pinch and hold in visionOS, or use a secondary click with an attached trackpad or keyboard. Although the interactions to reveal an edit menu can differ based on platform, people don’t appreciate having to learn a custom interaction to perform a standard task."
},
{
"type": "paragraph",
"text": "Offer commands that are relevant in the current context, removing or dimming commands that don’t apply. For example, if nothing is selected, avoid showing options that require a selection, such as Copy or Cut. Similarly, avoid showing a Paste option when there’s nothing to paste."
},
{
"type": "paragraph",
"text": "List custom commands near relevant system-provided ones. For example, if you offer custom formatting commands, you can help maintain the ordering people expect by listing them after the system-provided commands in the format section. Avoid overwhelming people with too many custom commands."
},
{
"type": "paragraph",
"text": "When it makes sense, let people select and copy noneditable text. People appreciate being able to paste static content — such as an image caption or social media status — into a message, note, or web search. In general, let people copy content text, but not control labels."
},
{
"type": "paragraph",
"text": "Support undo and redo when possible. Like all menus, an edit menu doesn’t require confirmation before performing its actions, so people can easily use undo and redo to recover a previous state. For guidance, see Undo and redo."
},
{
"type": "paragraph",
"text": "In general, avoid implementing other controls that perform the same functions as edit menu items. People typically expect to choose familiar edit commands in an edit menu, or use standard keyboard shortcuts. Offering redundant controls can crowd your interface, giving you less space for presenting actions that people might not already know about."
},
{
"type": "paragraph",
"text": "Differentiate different types of deletion commands when necessary. For example, a Delete menu item behaves the same as pressing a Delete key, but a Cut menu item copies the selected content to the system pasteboard before deleting it."
}
]
},
{
"heading": "Content",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Create short labels for custom commands. Use verbs or short verb phrases that succinctly describe the action your command performs. For guidance, see Labels."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for visionOS. Not supported in tvOS or watchOS."
}
]
},
{
"heading": "iOS, iPadOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Ensure your edit menu works well in both styles. The system displays the compact, horizontal style when people use Multi-Touch gestures to reveal the edit menu, and the vertical style when people use a keyboard or pointing device to reveal it. For guidance using the vertical menu layout, see Menus > iOS, iPadOS."
},
{
"type": "paragraph",
"text": "Adjust an edit menu’s placement, if necessary. Depending on available space, the default menu position is above or below the insertion point or selection. The system also displays a visual indicator that points to the targeted content. Although you can’t change the shape of the menu or its pointer, you can change the menu’s position. For example, you might need to move the menu to prevent it from covering important content or parts of your interface."
}
]
},
{
"heading": "macOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "To learn about the order of items in a macOS app’s Edit menu, see Edit menu."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Menus"
},
{
"type": "paragraph",
"text": "Context menus"
},
{
"type": "paragraph",
"text": "The menu bar"
},
{
"type": "paragraph",
"text": "Undo and redo"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "UIEditMenuInteraction — UIKit"
},
{
"type": "paragraph",
"text": "NSMenu — AppKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"June 21, 2023",
"Updated to include guidance for visionOS."
],
[
"September 14, 2022",
"Added guidance on supporting both edit-menu styles in iPadOS."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "context menu",
"url": "/design/human-interface-guidelines/context-menus"
},
{
"title": "Edit menu",
"url": "/design/human-interface-guidelines/the-menu-bar#Edit-menu"
},
{
"title": "pinch and hold",
"url": "/design/human-interface-guidelines/gestures#Standard-gestures"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/edit-menus#Best-practices"
},
{
"title": "Undo and redo",
"url": "/design/human-interface-guidelines/undo-and-redo"
},
{
"title": "Content",
"url": "/design/human-interface-guidelines/edit-menus#Content"
},
{
"title": "Labels",
"url": "/design/human-interface-guidelines/labels"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/edit-menus#Platform-considerations"
},
{
"title": "iOS, iPadOS",
"url": "/design/human-interface-guidelines/edit-menus#iOS-iPadOS"
},
{
"title": "Menus > iOS, iPadOS",
"url": "/design/human-interface-guidelines/menus#iOS-iPadOS"
},
{
"title": "macOS",
"url": "/design/human-interface-guidelines/edit-menus#macOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/edit-menus#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/edit-menus#Related"
},
{
"title": "Menus",
"url": "/design/human-interface-guidelines/menus"
},
{
"title": "The menu bar",
"url": "/design/human-interface-guidelines/the-menu-bar"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/edit-menus#Developer-documentation"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/edit-menus#Change-log"
}
],
"image_count": 0
},
{
"title": "Home Screen quick actions",
"url": "https://developer.apple.com/design/human-interface-guidelines/home-screen-quick-actions",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "People can get a menu of available quick actions when they touch and hold an app icon (on a 3D Touch device, people can press on the icon with increased pressure to see the menu). For example, Mail includes quick actions that open the Inbox or the VIP mailbox, initiate a search, and create a new message. In addition to app-specific actions, a Home Screen quick action menu also lists items for removing the app and editing the Home Screen."
},
{
"type": "paragraph",
"text": "Each Home Screen quick action includes a title, an interface icon on the left or right (depending on your app’s position on the Home Screen), and an optional subtitle. The title and subtitle are always left-aligned in left-to-right languages. Your app can even dynamically update its quick actions when new information is available. For example, Messages provides quick actions for opening your most recent conversations."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Create quick actions for compelling, high-value tasks. For example, Maps lets people search near their current location or get directions home without first opening the Maps app. People tend to expect every app to provide at least one useful quick action; you can provide a total of four."
},
{
"type": "paragraph",
"text": "Avoid making unpredictable changes to quick actions. Dynamic quick actions are a great way to keep actions relevant. For example, it may make sense to update quick actions based on the current location or recent activities in your app, time of day, or changes in settings. Make sure that actions change in ways that people can predict."
},
{
"type": "paragraph",
"text": "For each quick action, provide a succinct title that instantly communicates the results of the action. For example, titles like “Directions Home,” “Create New Contact,” and “New Message” can help people understand what happens when they choose the action. If you need to give more context, provide a subtitle too. Mail uses subtitles to indicate whether there are unread messages in the Inbox and VIP folder. Don’t include your app name or any extraneous information in the title or subtitle, keep the text short to avoid truncation, and take localization into account as you write the text."
},
{
"type": "paragraph",
"text": "Provide a familiar interface icon for each quick action. Prefer using SF Symbols to represent actions. For a list of icons that represent common actions, see Standard icons; for additional guidance, see Menus."
},
{
"type": "paragraph",
"text": "If you design your own interface icon, use the Quick Action Icon Template that’s included with Apple Design Resources for iOS and iPadOS."
},
{
"type": "paragraph",
"text": "Don’t use an emoji in place of a symbol or interface icon. Emojis are full color, whereas quick action symbols are monochromatic and change appearance in Dark Mode to maintain contrast."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Menus"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Add Home Screen quick actions — UIKit"
}
]
}
],
"platforms": [],
"related": [
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/home-screen-quick-actions#Best-practices"
},
{
"title": "SF Symbols",
"url": "/design/human-interface-guidelines/sf-symbols"
},
{
"title": "Standard icons",
"url": "/design/human-interface-guidelines/icons#Standard-icons"
},
{
"title": "Menus",
"url": "/design/human-interface-guidelines/menus"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/home-screen-quick-actions#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/home-screen-quick-actions#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/home-screen-quick-actions#Related"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/home-screen-quick-actions#Developer-documentation"
}
],
"image_count": 0
},
{
"title": "Panels",
"url": "https://developer.apple.com/design/human-interface-guidelines/panels",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "In general, a panel has a less prominent appearance than an app’s main window. When the situation calls for it, a panel can also use a dark, translucent style to support a heads-up display (or HUD) experience."
},
{
"type": "paragraph",
"text": "When your app runs in other platforms, consider using a modal view to present supplementary content that’s relevant to the current task or selection. For guidance, see Modality."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Use a panel to give people quick access to important controls or information related to the content they’re working with. For example, you might use a panel to provide controls or settings that affect the selected item in the active document or window."
},
{
"type": "paragraph",
"text": "Consider using a panel to present inspector functionality. An inspector displays the details of the currently selected item, automatically updating its contents when the item changes or when people select a new item. In contrast, if you need to present an Info window — which always maintains the same contents, even when the selected item changes — use a regular window, not a panel. Depending on the layout of your app, you might also consider using a split view pane to present an inspector."
},
{
"type": "paragraph",
"text": "Prefer simple adjustment controls in a panel. As much as possible, avoid including controls that require typing text or selecting items to act upon because these actions can require multiple steps. Instead, consider using controls like sliders and steppers because these components can give people more direct control."
},
{
"type": "paragraph",
"text": "Write a brief title that describes the panel’s purpose. Because a panel often floats above other open windows in your app, it needs a title bar so people can position it where they want. Create a short title using a noun — or a noun phrase with title-style capitalization — that can help people recognize the panel onscreen. For example, macOS provides familiar panels titled “Fonts” and “Colors,” and many apps use the title “Inspector.”"
},
{
"type": "paragraph",
"text": "Show and hide panels appropriately. When your app becomes active, bring all of its open panels to the front, regardless of which window was active when the panel opened. When your app is inactive, hide all of its panels."
},
{
"type": "paragraph",
"text": "Avoid including panels in the Window menu’s documents list. It’s fine to include commands for showing or hiding panels in the Window menu, but panels aren’t documents or standard app windows, and they don’t belong in the Window menu’s list."
},
{
"type": "paragraph",
"text": "In general, avoid making a panel’s minimize button available. People don’t usually need to minimize a panel, because it displays only when needed and disappears when the app is inactive."
},
{
"type": "paragraph",
"text": "Refer to panels by title in your interface and in help documentation. In menus, use the panel’s title without including the term panel: for example, “Show Fonts,” “Show Colors,” and “Show Inspector.” In help documentation, it can be confusing to introduce “panel” as a different type of window, so it’s generally best to refer to a panel by its title or — when it adds clarity — by appending window to the title. For example, the title “Inspector” often supplies enough context to stand on its own, whereas it can be clearer to use “Fonts window” and “Colors window” instead of just “Fonts” and “Colors.”"
}
]
},
{
"heading": "HUD-style panels",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "A HUD-style panel serves the same function as a standard panel, but its appearance is darker and translucent. HUDs work well in apps that present highly visual content or that provide an immersive experience, such as media editing or a full-screen slide show. For example, QuickTime Player uses a HUD to display inspector information without obstructing too much content."
},
{
"type": "paragraph",
"text": "Prefer standard panels. People can be distracted or confused by a HUD when there’s no logical reason for its presence. Also, a HUD might not match the current appearance setting. In general, use a HUD only:"
},
{
"type": "list",
"items": [
"In a media-oriented app that presents movies, photos, or slides",
"When a standard panel would obscure essential content",
"When you don’t need to include controls — with the exception of the disclosure triangle, most system-provided controls don’t match a HUD’s appearance."
]
},
{
"type": "paragraph",
"text": "Maintain one panel style when your app switches modes. For example, if you use a HUD when your app is in full-screen mode, prefer maintaining the HUD style when people take your app out of full-screen mode."
},
{
"type": "paragraph",
"text": "Use color sparingly in HUDs. Too much color in the dark appearance of a HUD can be distracting. Often, you need only small amounts of high-contrast color to highlight important information in a HUD."
},
{
"type": "paragraph",
"text": "Keep HUDs small. HUDs are designed to be unobtrusively useful, so letting them grow too large defeats their primary purpose. Don’t let a HUD obscure the content it adjusts, and make sure it doesn’t compete with the content for people’s attention."
},
{
"type": "paragraph",
"text": "For developer guidance, see hudWindow."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Windows"
},
{
"type": "paragraph",
"text": "Modality"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "NSPanel — AppKit"
},
{
"type": "paragraph",
"text": "hudWindow — AppKit"
}
]
}
],
"platforms": [],
"related": [
{
"title": "main window",
"url": "/design/human-interface-guidelines/windows#macOS-window-states"
},
{
"title": "Modality",
"url": "/design/human-interface-guidelines/modality"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/panels#Best-practices"
},
{
"title": "split view",
"url": "/design/human-interface-guidelines/split-views"
},
{
"title": "Window menu",
"url": "/design/human-interface-guidelines/the-menu-bar#Window-menu"
},
{
"title": "HUD-style panels",
"url": "/design/human-interface-guidelines/panels#HUD-style-panels"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/panels#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/panels#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/panels#Related"
},
{
"title": "Windows",
"url": "/design/human-interface-guidelines/windows"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/panels#Developer-documentation"
}
],
"image_count": 0
},
{
"title": "Path controls",
"url": "https://developer.apple.com/design/human-interface-guidelines/path-controls",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "For example, choosing View > Show Path Bar in the Finder displays a path bar at the bottom of the window. It shows the path of the selected item, or the path of the window’s folder if nothing is selected."
},
{
"type": "paragraph",
"text": "There are two styles of path control."
},
{
"type": "paragraph",
"text": "Standard. A linear list that includes the root disk, parent folders, and selected item. Each item appears with an icon and a name. If the list is too long to fit within the control, it hides names between the first and last items. If you make the control editable, people can drag an item onto the control to select the item and display its path in the control."
},
{
"type": "paragraph",
"text": "Pop up. A control similar to a pop-up button that shows the icon and name of the selected item. People can click the item to open a menu containing the root disk, parent folders, and selected item. If you make the control editable, the menu contains an additional Choose command that people can use to select an item and display it in the control. They can also drag an item onto the control to select it and display its path."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Use a path control in the window body, not the window frame. Path controls aren’t intended for use in toolbars or status bars. Note that the path control in the Finder appears at the bottom of the window body, not in the status bar."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iOS, iPadOS, tvOS, visionOS, or watchOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "File management"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "NSPathControl — AppKit"
}
]
}
],
"platforms": [],
"related": [
{
"title": "pop-up button",
"url": "https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/path-controls#Best-practices"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/path-controls#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/path-controls#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/path-controls#Related"
},
{
"title": "File management",
"url": "/design/human-interface-guidelines/file-management"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/path-controls#Developer-documentation"
}
],
"image_count": 0
},
{
"title": "Pop-up buttons",
"url": "https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "After people choose an item from a pop-up button’s menu, the menu closes, and the button can update its content to indicate the current selection."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Use a pop-up button to present a flat list of mutually exclusive options or states. A pop-up button helps people make a choice that affects their content or the surrounding view. Use a pull-down button instead if you need to:"
},
{
"type": "list",
"items": [
"Offer a list of actions",
"Let people select multiple items",
"Include a submenu"
]
},
{
"type": "paragraph",
"text": "Provide a useful default selection. A pop-up button can update its content to identify the current selection, but if people haven’t made a selection yet, it shows the default item you specify. When possible, make the default selection an item that most people are likely to want."
},
{
"type": "paragraph",
"text": "Give people a way to predict a pop-up button’s options without opening it. For example, you can use an introductory label or a button label that describes the button’s effect, giving context to the options."
},
{
"type": "paragraph",
"text": "Consider using a pop-up button when space is limited and you don’t need to display all options all the time. Pop-up buttons are a space-efficient way to present a wide array of choices."
},
{
"type": "paragraph",
"text": "If necessary, include a Custom option in a pop-up button’s menu to provide additional items that are useful in some situations. Offering a Custom option can help you avoid cluttering the interface with items or controls that people need only occasionally. You can also display explanatory text below the list to help people understand how the options work."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for iOS, macOS, or visionOS. Not supported in tvOS or watchOS."
}
]
},
{
"heading": "iPadOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Within a popover or modal view, consider using a pop-up button instead of a disclosure indicator to present multiple options for a list item. For example, people can quickly choose an option from the pop-up button’s menu without navigating to a detail view. Consider using a pop-up button in this scenario when you have a fairly small, well-defined set of options that work well in a menu."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Pull-down buttons"
},
{
"type": "paragraph",
"text": "Buttons"
},
{
"type": "paragraph",
"text": "Menus"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "MenuPickerStyle — SwiftUI"
},
{
"type": "paragraph",
"text": "changesSelectionAsPrimaryAction — UIKit"
},
{
"type": "paragraph",
"text": "NSPopUpButton — AppKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"October 24, 2023",
"Added artwork."
],
[
"September 14, 2022",
"Added a guideline on using a pop-up button in a popover or modal view in iPadOS."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/pop-up-buttons#Best-practices"
},
{
"title": "pull-down button",
"url": "https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/pop-up-buttons#Platform-considerations"
},
{
"title": "iPadOS",
"url": "/design/human-interface-guidelines/pop-up-buttons#iPadOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/pop-up-buttons#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/pop-up-buttons#Related"
},
{
"title": "Pull-down buttons",
"url": "/design/human-interface-guidelines/pull-down-buttons"
},
{
"title": "Buttons",
"url": "/design/human-interface-guidelines/buttons"
},
{
"title": "Menus",
"url": "/design/human-interface-guidelines/menus"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/pop-up-buttons#Developer-documentation"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/pop-up-buttons#Change-log"
}
],
"image_count": 0
},
{
"title": "Popovers",
"url": "https://developer.apple.com/design/human-interface-guidelines/popovers",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Use a popover to expose a small amount of information or functionality. Because a popover disappears after people interact with it, limit the amount of functionality in the popover to a few related tasks. For example, a calendar event popover makes it easy for people to change the date or time of an event, or to move it to another calendar. The popover disappears after the change, letting people continue reviewing the events on their calendar."
},
{
"type": "paragraph",
"text": "Consider using popovers when you want more room for content. Views like sidebars and panels take up a lot of space. If you need content only temporarily, displaying it in a popover can help streamline your interface."
},
{
"type": "paragraph",
"text": "Position popovers appropriately. Make sure a popover’s arrow points as directly as possible to the element that revealed it. Ideally, a popover doesn’t cover the element that revealed it or any essential content people may need to see while using it."
},
{
"type": "paragraph",
"text": "Use a Close button for confirmation and guidance only. A Close button, including Cancel or Done, is worth including if it provides clarity, like exiting with or without saving changes. Otherwise, a popover generally closes when people click or tap outside its bounds or select an item in the popover. If multiple selections are possible, make sure the popover remains open until people explicitly dismiss it or they click or tap outside its bounds."
},
{
"type": "paragraph",
"text": "Always save work when automatically closing a nonmodal popover. People can unintentionally dismiss a nonmodal popover by clicking or tapping outside its bounds. Discard people’s work only when they click or tap an explicit Cancel button."
},
{
"type": "paragraph",
"text": "Show one popover at a time. Displaying multiple popovers clutters the interface and causes confusion. Never show a cascade or hierarchy of popovers, in which one emerges from another. If you need to show a new popover, close the open one first."
},
{
"type": "paragraph",
"text": "Don’t show another view over a popover. Make sure nothing displays on top of a popover, except for an alert."
},
{
"type": "paragraph",
"text": "When possible, let people close one popover and open another with a single click or tap. Avoiding extra gestures is especially desirable when several different bar buttons each open a popover."
},
{
"type": "paragraph",
"text": "Avoid making a popover too big. Make a popover only big enough to display its contents and point to the place it came from. If necessary, the system can adjust the size of a popover to ensure it fits well in the interface."
},
{
"type": "paragraph",
"text": "Provide a smooth transition when changing the size of a popover. Some popovers provide both condensed and expanded views of the same information. If you adjust the size of a popover, animate the change to avoid giving the impression that a new popover replaced the old one."
},
{
"type": "paragraph",
"text": "Avoid using the word popover in help documentation. Instead, refer to a specific task or selection. For example, instead of “Select the Show button at the bottom of the popover,” you might write “Select the Show button.”"
},
{
"type": "paragraph",
"text": "Avoid using a popover to show a warning. People can miss a popover or accidentally close it. If you need to warn people, use an alert instead."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for visionOS. Not supported in tvOS or watchOS."
}
]
},
{
"heading": "iOS, iPadOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Avoid displaying popovers in compact views. Make your app or game dynamically adjust its layout based on the size class of the content area. Reserve popovers for wide views; for compact views, use all available screen space by presenting information in a full-screen modal view like a sheet instead. For related guidance, see Modality."
}
]
},
{
"heading": "macOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "You can make a popover detachable in macOS, which becomes a separate panel when people drag it. The panel remains visible onscreen while people interact with other content."
},
{
"type": "paragraph",
"text": "Consider letting people detach a popover. People might appreciate being able to convert a popover into a panel if they want to view other information while the popover remains visible."
},
{
"type": "paragraph",
"text": "Make minimal appearance changes to a detached popover. A panel that looks similar to the original popover helps people maintain context."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Sheets"
},
{
"type": "paragraph",
"text": "Action sheets"
},
{
"type": "paragraph",
"text": "Alerts"
},
{
"type": "paragraph",
"text": "Modality"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "popover(isPresented:attachmentAnchor:arrowEdge:content:) — SwiftUI"
},
{
"type": "paragraph",
"text": "UIPopoverPresentationController — UIKit"
},
{
"type": "paragraph",
"text": "NSPopover — AppKit"
}
]
}
],
"platforms": [],
"related": [
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/popovers#Best-practices"
},
{
"title": "alert",
"url": "/design/human-interface-guidelines/alerts"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/popovers#Platform-considerations"
},
{
"title": "iOS, iPadOS",
"url": "/design/human-interface-guidelines/popovers#iOS-iPadOS"
},
{
"title": "Modality",
"url": "/design/human-interface-guidelines/modality"
},
{
"title": "macOS",
"url": "/design/human-interface-guidelines/popovers#macOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/popovers#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/popovers#Related"
},
{
"title": "Sheets",
"url": "/design/human-interface-guidelines/sheets"
},
{
"title": "Action sheets",
"url": "/design/human-interface-guidelines/action-sheets"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/popovers#Developer-documentation"
}
],
"image_count": 0
},
{
"title": "Pull-down buttons",
"url": "https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "After people choose an item in a pull-down button’s menu, the menu closes, and the app performs the chosen action."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Use a pull-down button to present commands or items that are directly related to the button’s action. The menu lets you help people clarify the button’s target or customize its behavior without requiring additional buttons in your interface. For example:"
},
{
"type": "list",
"items": [
"An Add button could present a menu that lets people specify the item they want to add.",
"A Sort button could use a menu to let people select an attribute on which to sort.",
"A Back button could let people choose a specific location to revisit instead of opening the previous one."
]
},
{
"type": "paragraph",
"text": "If you need to provide a list of mutually exclusive choices that aren’t commands, use a pop-up button instead."
},
{
"type": "paragraph",
"text": "Avoid putting all of a view’s actions in one pull-down button. A view’s primary actions need to be easily discoverable, so you don’t want to hide them in a pull-down button that people have to open before they can do anything."
},
{
"type": "paragraph",
"text": "Balance menu length with ease of use. Because people have to interact with a pull-down button before they can view its menu, listing a minimum of three items can help the interaction feel worthwhile. If you need to list only one or two items, consider using alternative components to present them, such as buttons to perform actions and toggles or switches to present selections. In contrast, listing too many items in a pull-down button’s menu can slow people down because it takes longer to find a specific item."
},
{
"type": "paragraph",
"text": "Display a succinct menu title only if it adds meaning. In general, a pull-down button’s content — combined with descriptive menu items — provides all the context people need, making a menu title unnecessary."
},
{
"type": "paragraph",
"text": "Let people know when a pull-down button’s menu item is destructive, and ask them to confirm their intent. Menus use red text to highlight actions that you identify as potentially destructive. When people choose a destructive action, the system displays an action sheet (iOS) or popover (iPadOS) in which they can confirm their choice or cancel the action. Because an action sheet appears in a different location from the menu and requires deliberate dismissal, it can help people avoid losing data by mistake."
},
{
"type": "paragraph",
"text": "Include an interface icon with a menu item when it provides value. If you need to clarify an item’s meaning, you can display an icon or image after its label. Using SF Symbols for this purpose can help you provide a familiar experience while ensuring that the symbol remains aligned with the text at every scale."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for macOS or visionOS. Not supported in tvOS or watchOS."
}
]
},
{
"heading": "iOS, iPadOS",
"level": 3,
"content": [
{
"type": "note",
"text": "NoteYou can also let people reveal a pull-down menu by performing a specific gesture on a button. For example, in iOS 14 and later, Safari responds to a touch and hold gesture on the Tabs button by displaying a menu of tab-related actions, like New Tab and Close All Tabs."
},
{
"type": "paragraph",
"text": "Consider using a More pull-down button to present items that don’t need prominent positions in the main interface. A More button can help you offer a range of items where space is constrained, but it can also hinder discoverability. Although people generally understand that a More button offers additional functionality related to the current context, the ellipsis icon doesn’t necessarily help them predict its contents. To design an effective More button, weigh the convenience of its size against its impact on discoverability to find a balance that works in your app."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Pop-up buttons"
},
{
"type": "paragraph",
"text": "Buttons"
},
{
"type": "paragraph",
"text": "Menus"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "MenuPickerStyle — SwiftUI"
},
{
"type": "paragraph",
"text": "showsMenuAsPrimaryAction — UIKit"
},
{
"type": "paragraph",
"text": "pullsDown — AppKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"September 14, 2022",
"Refined guidance on designing a useful menu length."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/pull-down-buttons#Best-practices"
},
{
"title": "pop-up button",
"url": "/design/human-interface-guidelines/pop-up-buttons"
},
{
"title": "action sheet",
"url": "/design/human-interface-guidelines/action-sheets"
},
{
"title": "popover",
"url": "/design/human-interface-guidelines/popovers"
},
{
"title": "icon",
"url": "/design/human-interface-guidelines/icons"
},
{
"title": "SF Symbols",
"url": "/design/human-interface-guidelines/sf-symbols"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/pull-down-buttons#Platform-considerations"
},
{
"title": "iOS, iPadOS",
"url": "/design/human-interface-guidelines/pull-down-buttons#iOS-iPadOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/pull-down-buttons#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/pull-down-buttons#Related"
},
{
"title": "Buttons",
"url": "/design/human-interface-guidelines/buttons"
},
{
"title": "Menus",
"url": "/design/human-interface-guidelines/menus"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/pull-down-buttons#Developer-documentation"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/pull-down-buttons#Change-log"
}
],
"image_count": 0
},
{
"title": "Search fields",
"url": "https://developer.apple.com/design/human-interface-guidelines/search-fields",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "A search field is an editable text field that displays a Search icon, a Clear button, and placeholder text where people can enter what they are searching for. Search fields can use a scope control as well as tokens to help filter and refine the scope of their search. Across each platform, there are different patterns for accessing search based on the goals and design of your app."
},
{
"type": "paragraph",
"text": "For developer guidance, see Adding a search interface to your app; for guidance related to systemwide search, see Searching."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Display placeholder text that describes the type of information people can search for. For example, the Apple TV app includes the placeholder text Shows, Movies, and More. Avoid using a term like Search for placeholder text because it doesn’t provide any helpful information."
},
{
"type": "paragraph",
"text": "If possible, start search immediately when a person types. Searching while someone types makes the search experience feel more responsive because it provides results that are continuously refined as the text becomes more specific."
},
{
"type": "paragraph",
"text": "Consider showing suggested search terms before search begins, or as a person types. This can help someone search faster by suggesting common searches, even when the search itself doesn’t begin immediately."
},
{
"type": "paragraph",
"text": "Simplify search results. Provide the most relevant search results first to minimize the need for someone to scroll to find what they’re looking for. In addition to prioritizing the most likely results, consider categorizing them to help people find what they want."
},
{
"type": "paragraph",
"text": "Consider letting people filter search results. For example, you can include a scope control in the search results content area to help people quickly and easily filter search results."
}
]
},
{
"heading": "Scope controls and tokens",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Scope controls and tokens are components you can use to let someone narrow the parameters of a search either before or after they make it."
},
{
"type": "list",
"items": [
"A scope control acts like a segmented control for choosing a category for the search.",
"A token is a visual representation of a search term that someone can select and edit, and acts as a filter for any additional terms in the search."
]
},
{
"type": "paragraph",
"text": "Use a scope control to filter among clearly defined search categories. A scope control can help someone move from a broader scope to a narrower one. For example, in Mail on iPhone, a scope control helps people move from searching their entire mailbox to just the specific mailbox they’re viewing. For developer guidance, see Scoping a search operation."
},
{
"type": "paragraph",
"text": "Default to a broader scope and let people refine it as they need. A broader scope provides context for the full set of available results, which helps guide people in a useful direction when they choose to narrow the scope."
},
{
"type": "paragraph",
"text": "Use tokens to filter by common search terms or items. When you define a token, the term it represents gains a visual treatment that encapsulates it, indicating that people can select and edit it as a single item. Tokens can clarify a search term, like filtering by a specific contact in Mail, or focus a search to a specific set of attributes, like filtering by photos in Messages. For the related macOS component, see Token fields."
},
{
"type": "paragraph",
"text": "Consider pairing tokens with search suggestions. People may not know which tokens are available, so pairing them with search suggestions can help people learn how to use them."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for visionOS."
}
]
},
{
"heading": "iOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "There are three main places you can position the entry point for search:"
},
{
"type": "list",
"items": [
"In a tab bar at the bottom of the screen",
"In a toolbar at the bottom or top of the screen",
"Directly inline with content"
]
},
{
"type": "paragraph",
"text": "Where search makes the most sense depends on the layout, content, and navigation of your app."
}
]
},
{
"heading": "Search in a tab bar",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "You can place search as a visually distinct tab on the trailing side of a tab bar, which keeps search visible and always available as people switch between the sections of your app."
},
{
"type": "paragraph",
"text": "When someone navigates to the search tab, the search field that appears can start as focused or unfocused."
},
{
"type": "paragraph",
"text": "Focused"
},
{
"type": "paragraph",
"text": "Unfocused"
},
{
"type": "paragraph",
"text": "Start with the search field focused to help people quickly find what they need. When the search field starts focused, the keyboard immediately appears with the search field above it, ready to begin the search. This provides a more transient experience that brings people directly back to their previous tab after they exit search, and is ideal when you want search to resolve quickly and seamlessly."
},
{
"type": "paragraph",
"text": "Start with the search field unfocused to promote discovery and exploration. When the search field starts unfocused, the search tab expands into an unselected field at the bottom of the screen. This provides space on the rest of the screen for additional discovery or navigation before someone taps the field to begin the search. This is great for an app with a large collection of content to showcase, like Music or TV."
}
]
},
{
"heading": "Search in a toolbar",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "As an alternative to search in a tab bar, you can also place search in a toolbar either at the bottom or top of the screen."
},
{
"type": "list",
"items": [
"You can include search in a bottom toolbar either as an expanded field or as a toolbar button, depending on how much space is available and how important search is to your app. When someone taps it, it animates into a search field above the keyboard so they can begin typing.",
"You can include search in a top toolbar, also called a navigation bar, where it appears as a toolbar button. When someone taps it, it animates into a search field that appears either above the keyboard or inline at the top if there isn’t space at the bottom."
]
},
{
"type": "paragraph",
"text": "Search in a bottom toolbar"
},
{
"type": "paragraph",
"text": "Search in a top toolbar"
},
{
"type": "paragraph",
"text": "Place search at the bottom if there’s room. You can either add a search field to an existing toolbar, or as a new toolbar where search is the only item. Search at the bottom is useful in any situation where search is a priority, since it keeps the search experience easy to reach. Examples of apps with search at the bottom in various toolbar layouts include Settings, where it’s the only item, and Mail and Notes, where it fits alongside other important controls."
},
{
"type": "paragraph",
"text": "Place search at the top when itʼs important to defer to content at the bottom of the screen, or thereʼs no bottom toolbar. Use search at the top in cases where covering the content might interfere with a primary function of the app. The Wallet app, for example, includes event passes in a stack at the bottom of the screen for easy access and viewing at a glance."
}
]
},
{
"heading": "Search as an inline field",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "In some cases you might want your app to include a search field inline with content."
},
{
"type": "paragraph",
"text": "Place search as an inline field when its position alongside the content it searches strengthens that relationship. When you need to filter or search within a single view, it can be helpful to have search appear directly next to content to illustrate that the search applies to it, rather than globally. For example, although the main search in the Music app is in the tab bar, people can navigate to their library and use an inline search field to filter their songs and albums."
},
{
"type": "paragraph",
"text": "Prefer placing search at the bottom. Generally, even for search that applies to a subset of your app’s content, it’s better to locate search where people can reach it easily. The Settings app, for example, places search at the bottom both for its top-level search and for search in the section for individual apps. If there isn’t space at the bottom (because it’s occupied by a tab bar or other important UI, for example), it’s okay to place search inline at the top."
},
{
"type": "paragraph",
"text": "When at the top, position an inline search field above the list it searches, and pin it to the top toolbar when scrolling. This helps keep it distinct from search that appears in other locations."
}
]
},
{
"heading": "iPadOS, macOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "The placement and behavior of the search field in iPadOS and macOS is similar; on both platforms, clearing the field exits search and dismisses the keyboard if present. If your app is available on both iPad and Mac, try to keep the search experience as consistent as possible across both platforms."
},
{
"type": "paragraph",
"text": "iPadOS"
},
{
"type": "paragraph",
"text": "macOS"
},
{
"type": "paragraph",
"text": "Put a search field at the trailing side of the toolbar for many common uses. Many apps benefit from the familiar pattern of search in the toolbar, particularly apps with split views or apps that navigate between multiple sources, like Mail, Notes, and Voice Memos. The persistent availability of search at the side of the toolbar gives it a global presence within your app, so it’s generally appropriate to start with a global scope for the initial search."
},
{
"type": "paragraph",
"text": "Include search at the top of the sidebar when filtering content or navigation there. Apps such as Settings take advantage of search to quickly filter the sidebar and expose sections that may be multiple levels deep, providing a simple way for people to search, preview, and navigate to the section or setting they’re looking for."
},
{
"type": "paragraph",
"text": "Include search as an item in the sidebar or tab bar when you want an area dedicated to discovery. If your search is paired with rich suggestions, categories, or content that needs more space, it can be helpful to have a dedicated area for it. This is particularly true for apps where browsing and search go hand in hand, like Music and TV, where it provides a unified location to highlight suggested content, categories, and recent searches. A dedicated area also ensures search is always available as people navigate and switch sections of your app."
},
{
"type": "paragraph",
"text": "In a search field in a dedicated area, consider immediately focusing the field when a person navigates to the section to help people search faster and locate the field itself more easily. An exception to this is on iPad when only a virtual keyboard is available, in which case it’s better to leave the field unfocused to prevent the keyboard from unexpectedly covering the view."
},
{
"type": "paragraph",
"text": "Account for window resizing with the placement of the search field. On iPad, the search field fluidly resizes with the app window like it does on Mac. However, for compact views on iPad, itʼs important to ensure that search is available where it’s most contextually useful. For example, Notes and Mail place search above the column for the content list when they resize down to a compact view."
}
]
},
{
"heading": "tvOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "A search screen is a specialized keyboard screen that helps people enter search text, displaying search results beneath the keyboard in a fully customizable view. For developer guidance, see UISearchController."
},
{
"type": "paragraph",
"text": "Provide suggestions to make searching easier. People typically don’t want to do a lot of typing in tvOS. To improve the search experience, provide popular and context-specific search suggestions, including recent searches when available. For developer guidance, see Using suggested searches with a search controller."
}
]
},
{
"heading": "watchOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "When someone taps the search field, the system displays a text-input control that covers the entire screen. The app only returns to the search field after they tap the Cancel or Search button."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Searching"
},
{
"type": "paragraph",
"text": "Token fields"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Adding a search interface to your app — SwiftUI"
},
{
"type": "paragraph",
"text": "searchable(text:placement:prompt:) — SwiftUI"
},
{
"type": "paragraph",
"text": "UISearchBar — UIKit"
},
{
"type": "paragraph",
"text": "UISearchTextField — UIKit"
},
{
"type": "paragraph",
"text": "NSSearchField — AppKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"June 9, 2025",
"Updated guidance for search placement in iOS, consolidated iPadOS and macOS platform considerations, and added guidance for tokens."
],
[
"September 12, 2023",
"Combined guidance common to all platforms."
],
[
"June 5, 2023",
"Added guidance for using search fields in watchOS."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "scope control",
"url": "/design/human-interface-guidelines/search-fields#Scope-controls-and-tokens"
},
{
"title": "Searching",
"url": "/design/human-interface-guidelines/searching"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/search-fields#Best-practices"
},
{
"title": "segmented control",
"url": "/design/human-interface-guidelines/segmented-controls"
},
{
"title": "Token fields",
"url": "/design/human-interface-guidelines/token-fields"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/search-fields#Platform-considerations"
},
{
"title": "iOS",
"url": "/design/human-interface-guidelines/search-fields#iOS"
},
{
"title": "Search in a tab bar",
"url": "/design/human-interface-guidelines/search-fields#Search-in-a-tab-bar"
},
{
"title": "Search in a toolbar",
"url": "/design/human-interface-guidelines/search-fields#Search-in-a-toolbar"
},
{
"title": "Search as an inline field",
"url": "/design/human-interface-guidelines/search-fields#Search-as-an-inline-field"
},
{
"title": "iPadOS, macOS",
"url": "/design/human-interface-guidelines/search-fields#iPadOS-macOS"
},
{
"title": "tvOS",
"url": "/design/human-interface-guidelines/search-fields#tvOS"
},
{
"title": "watchOS",
"url": "/design/human-interface-guidelines/search-fields#watchOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/search-fields#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/search-fields#Related"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/search-fields#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/search-fields#Videos"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/search-fields#Change-log"
}
],
"image_count": 0
},
{
"title": "Segmented controls",
"url": "https://developer.apple.com/design/human-interface-guidelines/segmented-controls",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Within a segmented control, all segments are usually equal in width. Like buttons, segments can contain text or images. Segments can also have text labels beneath them (or beneath the control as a whole)."
},
{
"type": "paragraph",
"text": "A segmented control offers a single choice from among a set of options, or in macOS, either a single choice or multiple choices. For example, in macOS Keynote people can select only one segment in the alignment options control to align selected text. In contrast, people can choose multiple segments in the font attributes control to combine styles like bold, italics, and underline. The toolbar of a Keynote window also uses a segmented control to let people show and hide various editing panes within the main window area."
},
{
"type": "paragraph",
"text": "Single choice"
},
{
"type": "paragraph",
"text": "Multiple choices"
},
{
"type": "paragraph",
"text": "In addition to representing the state of a single or multiple-choice selection, a segmented control can function as a set of buttons that perform actions without showing a selection state. For example, the Reply, Reply all, and Forward buttons in macOS Mail. For developer guidance, see isMomentary and NSSegmentedControl.SwitchTracking.momentary."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Use a segmented control to provide closely related choices that affect an object, state, or view. For example, a segmented control in an inspector could let people choose one or more attributes to apply to a selection, or a segmented control in a toolbar could offer a set of actions to perform on the current view."
},
{
"type": "paragraph",
"text": "In the iOS Health app, a segmented control provides a choice of time ranges for the activity graphs to display."
},
{
"type": "paragraph",
"text": "Consider a segmented control when it’s important to group functions together, or to clearly show their selection state. Unlike other button styles, segmented controls preserve their grouping regardless of the view size or where they appear. This grouping can also help people understand at a glance which controls are currently selected."
},
{
"type": "paragraph",
"text": "Keep control types consistent within a single segmented control. Don’t assign actions to segments in a control that otherwise represents selection state, and don’t show a selection state for segments in a control that otherwise performs actions."
},
{
"type": "paragraph",
"text": "Limit the number of segments in a control. Too many segments can be hard to parse and time-consuming to navigate. Aim for no more than about five to seven segments in a wide interface and no more than about five segments on iPhone."
},
{
"type": "paragraph",
"text": "In general, keep segment size consistent. When all segments have equal width, a segmented control feels balanced. To the extent possible, it’s best to keep icon and title widths consistent too."
}
]
},
{
"heading": "Content",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Prefer using either text or images — not a mix of both — in a single segmented control. Although individual segments can contain text labels or images, mixing the two in a single control can lead to a disconnected and confusing interface."
},
{
"type": "paragraph",
"text": "As much as possible, use content with a similar size in each segment. Because all segments typically have equal width, it doesn’t look good if content fills some segments but not others."
},
{
"type": "paragraph",
"text": "Use nouns or noun phrases for segment labels. Write text that describes each segment and uses title-style capitalization. A segmented control that displays text labels doesn’t need introductory text."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in watchOS."
}
]
},
{
"heading": "iOS, iPadOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Consider a segmented control to switch between closely related subviews. A segmented control can be useful as a way to quickly switch between related subviews. For example, the segmented control in Calendar’s New Event sheet switches between the subviews for creating a new event and a new reminder. For switching between completely separate sections of an app, use a tab bar instead."
}
]
},
{
"heading": "macOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Consider using introductory text to clarify the purpose of a segmented control. When the control uses symbols or interface icons, you could also add a label below each segment to clarify its meaning. If your app includes tooltips, provide one for each segment in a segmented control."
},
{
"type": "paragraph",
"text": "Use a tab view in the main window area — instead of a segmented control — for view switching. A tab view supports efficient view switching and is similar in appearance to a box combined with a segmented control. Consider using a segmented control to help people switch views in a toolbar or inspector pane."
},
{
"type": "paragraph",
"text": "Consider supporting spring loading. On a Mac equipped with a Magic Trackpad, spring loading lets people activate a segment by dragging selected items over it and force clicking without dropping the selected items. People can also continue dragging the items after a segment activates."
}
]
},
{
"heading": "tvOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Consider using a split view instead of a segmented control on screens that perform content filtering. People generally find it easy to navigate back and forth between content and filtering options using a split view. Depending on its placement, a segmented control may not be as easy to access."
},
{
"type": "paragraph",
"text": "Avoid putting other focusable elements close to segmented controls. Segments become selected when focus moves to them, not when people click them. Carefully consider where you position a segmented control relative to other interface elements. If other focusable elements are too close, people might accidentally focus on them when attempting to switch between segments."
}
]
},
{
"heading": "visionOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "When people look at a segmented control that uses icons, the system displays a tooltip that contains the descriptive text you supply."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Split views"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "segmented — SwiftUI"
},
{
"type": "paragraph",
"text": "UISegmentedControl — UIKit"
},
{
"type": "paragraph",
"text": "NSSegmentedControl — AppKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"June 21, 2023",
"Updated to include guidance for visionOS."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "buttons",
"url": "/design/human-interface-guidelines/buttons"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/segmented-controls#Best-practices"
},
{
"title": "Content",
"url": "/design/human-interface-guidelines/segmented-controls#Content"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/segmented-controls#Platform-considerations"
},
{
"title": "iOS, iPadOS",
"url": "/design/human-interface-guidelines/segmented-controls#iOS-iPadOS"
},
{
"title": "tab bar",
"url": "/design/human-interface-guidelines/tab-bars"
},
{
"title": "macOS",
"url": "/design/human-interface-guidelines/segmented-controls#macOS"
},
{
"title": "tab view",
"url": "/design/human-interface-guidelines/tab-views"
},
{
"title": "box",
"url": "/design/human-interface-guidelines/boxes"
},
{
"title": "tvOS",
"url": "/design/human-interface-guidelines/segmented-controls#tvOS"
},
{
"title": "visionOS",
"url": "/design/human-interface-guidelines/segmented-controls#visionOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/segmented-controls#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/segmented-controls#Related"
},
{
"title": "Split views",
"url": "/design/human-interface-guidelines/split-views"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/segmented-controls#Developer-documentation"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/segmented-controls#Change-log"
}
],
"image_count": 0
},
{
"title": "Status bars",
"url": "https://developer.apple.com/design/human-interface-guidelines/status-bars",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Obscure content under the status bar. By default, the background of the status bar is transparent, allowing content beneath to show through. This transparency can make it difficult to see information presented in the status bar. If controls are visible behind the status bar, people may attempt to interact with them and be unable to do so. Be sure to keep the status bar readable, and don’t imply that content behind it is interactive. Prefer using a scroll edge effect to place a blurred view behind the status bar. For developer guidance, see ScrollEdgeEffectStyle and UIScrollEdgeEffect."
},
{
"type": "paragraph",
"text": "Consider temporarily hiding the status bar when displaying full-screen media. A status bar can be distracting when people are paying attention to media. Temporarily hide these elements to provide a more immersive experience. The Photos app, for example, hides the status bar and other interface elements when people browse full-screen photos."
},
{
"type": "paragraph",
"text": "The Photos app with the status bar visible"
},
{
"type": "paragraph",
"text": "The Photos app with the status bar hidden"
},
{
"type": "paragraph",
"text": "Avoid permanently hiding the status bar. Without a status bar, people have to leave your app to check the time or see if they have a Wi-Fi connection. Let people redisplay a hidden status bar with a simple, discoverable gesture. For example, when browsing full-screen photos in the Photos app, a single tap shows the status bar again."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for iOS or iPadOS. Not supported in macOS, tvOS, visionOS, or watchOS."
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "UIStatusBarStyle — UIKit"
},
{
"type": "paragraph",
"text": "preferredStatusBarStyle — UIKit"
}
]
}
],
"platforms": [],
"related": [
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/status-bars#Best-practices"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/status-bars#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/status-bars#Resources"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/status-bars#Developer-documentation"
}
],
"image_count": 0
},
{
"title": "The menu bar",
"url": "https://developer.apple.com/design/human-interface-guidelines/the-menu-bar",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Mac users are very familiar with the macOS menu bar, and they rely on it to help them learn what an app does and find the commands they need. To help your app or game feel at home in macOS, it’s essential to provide a consistent menu bar experience."
},
{
"type": "paragraph",
"text": "Menu bar menus on iPad are similar to those on Mac, appearing in the same order and with familiar sets of menu items. When you adopt the menu structure that people expect from their experience on Mac, it helps them immediately understand and take advantage of the menu bar on iPad as well."
},
{
"type": "paragraph",
"text": "Keyboard shortcuts in iPadOS use the same patterns as in macOS. For guidance, see Standard keyboard shortcuts."
},
{
"type": "paragraph",
"text": "Menus in the menu bar share most of the appearance and behavior characteristics that all menu types have. To learn about menus in general — and how to organize and label menu items — see Menus."
}
]
},
{
"heading": "Anatomy",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "When present in the menu bar, the following menus appear in the order listed below."
},
{
"type": "list",
"items": [
"YourAppName (you supply a short version of your app’s name for this menu’s title)",
"File",
"Edit",
"Format",
"View",
"App-specific menus, if any",
"Window",
"Help"
]
},
{
"type": "paragraph",
"text": "In addition, the macOS menu bar includes the Apple menu on the leading side and menu bar extras on the trailing side. See macOS Platform considerations for guidance."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Support the default system-defined menus and their ordering. People expect to find menus and menu items in an order they’re familiar with. In many cases, the system implements the functionality of standard menu items so you don’t have to. For example, when people select text in a standard text field, the system makes the Edit > Copy menu item available."
},
{
"type": "paragraph",
"text": "Always show the same set of menu items. Keeping menu items visible helps people learn what actions your app supports, even if they’re unavailable in the current context. If a menu bar item isn’t actionable, disable the action instead of hiding it from the menu."
},
{
"type": "paragraph",
"text": "Represent menu item actions with familiar icons. Icons help people recognize common actions throughout your app. Use the same icons as the system to represent actions such as Copy, Share, and Delete, wherever they appear. For a list of icons that represent common actions, see Standard icons. For additional guidance, see Menus."
},
{
"type": "paragraph",
"text": "Support the keyboard shortcuts defined for the standard menu items you include. People expect to use the keyboard shortcuts they already know for standard menu items, like Copy, Cut, Paste, Save, and Print. Define custom keyboard shortcuts only when necessary. For guidance, see Standard keyboard shortcuts."
},
{
"type": "paragraph",
"text": "Prefer short, one-word menu titles. Various factors — like different display sizes and the presence of menu bar extras — can affect the spacing and appearance of your menus. One-word menu titles work especially well in the menu bar because they take little space and are easy for people to scan. If you need to use more than one word in the menu title, use title-style capitalization."
}
]
},
{
"heading": "App menu",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "The app menu lists items that apply to your app or game as a whole, rather than to a specific task, document, or window. To help people quickly identify the active app, the menu bar displays your app name in bold."
},
{
"type": "paragraph",
"text": "The app menu typically contains the following menu items listed in the following order."
},
{
"type": "table",
"rows": [
[
"Menu item",
"Action",
"Guidance"
],
[
"About YourAppName",
"Displays the About window for your app, which includes copyright and version information.",
"Prefer a short name of 16 characters or fewer. Don’t include a version number."
],
[
"Settings…",
"Opens your settings window, or your app’s page in iPadOS Settings.",
"Use only for app-level settings. If you also offer document-specific settings, put them in the File menu."
],
[
"Optional app-specific items",
"Performs custom app-level setting or configuration actions.",
"List custom app-configuration items after the Settings item and within the same group."
],
[
"Services (macOS only)",
"Displays a submenu of services from the system and other apps that apply to the current context.",
""
],
[
"Hide YourAppName (macOS only)",
"Hides your app and all of its windows, and then activates the most recently used app.",
"Use the same short app name you supply for the About item."
],
[
"Hide Others (macOS only)",
"Hides all other open apps and their windows.",
""
],
[
"Show All (macOS only)",
"Shows all other open apps and their windows behind your app’s windows.",
""
],
[
"Quit YourAppName",
"Quits your app. Pressing Option changes Quit YourAppName to Quit and Keep Windows.",
"Use the same short app name you supply for the About item."
]
]
},
{
"type": "paragraph",
"text": "Display the About menu item first. Include a separator after the About menu item so that it appears by itself in a group."
}
]
},
{
"heading": "File menu",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "The File menu contains commands that help people manage the files or documents an app supports. If your app doesn’t handle any types of files, you can rename or eliminate this menu."
},
{
"type": "paragraph",
"text": "The File menu typically contains the following menu items listed in the following order."
},
{
"type": "table",
"rows": [
[
"Menu item",
"Action",
"Guidance"
],
[
"New Item",
"Creates a new document, file, or window.",
"For Item, use a term that names the type of item your app creates. For example, Calendar uses Event and Calendar."
],
[
"Open",
"Can open the selected item or present an interface in which people select an item to open.",
"If people need to select an item in a separate interface, an ellipsis follows the command to indicate that more input is required."
],
[
"Open Recent",
"Displays a submenu that lists recently opened documents and files that people can select, and typically includes a Clear Menu item.",
"List document and filenames that people recognize in the submenu; don’t display file paths. List the documents in the order people last opened them, with the most recently opened document first."
],
[
"Close",
"Closes the current window or document. Pressing Option changes Close to Close All. For a tab-based window, Close Tab replaces Close.",
"In a tab-based window, consider adding a Close Window item to let people close the entire window with one click or tap."
],
[
"Close Tab",
"Closes the current tab in a tab-based window. Pressing Option changes Close Tab to Close Other Tabs.",
""
],
[
"Close File",
"Closes the current file and all its associated windows.",
"Consider supporting this menu item if your app can open multiple views of the same file."
],
[
"Save",
"Saves the current document or file.",
"Automatically save changes periodically as people work so they don’t need to keep choosing File > Save. For a new document, prompt people for a name and location. If you need to let people save a file in multiple formats, prefer a pop-up menu that lets people choose a format in the Save sheet."
],
[
"Save All",
"Saves all open documents.",
""
],
[
"Duplicate",
"Duplicates the current document, leaving both documents open. Pressing Option changes Duplicate to Save As.",
"Prefer Duplicate to menu items like Save As, Export, Copy To, and Save To because these items don’t clarify the relationship between the original file and the new one."
],
[
"Rename…",
"Lets people change the name of the current document.",
""
],
[
"Move To…",
"Prompts people to choose a new location for the document.",
""
],
[
"Export As…",
"Prompts people for a name, output location, and export file format. After exporting the file, the current document remains open; the exported file doesn’t open.",
"Reserve the Export As item for when you need to let people export content in a format your app doesn’t typically handle."
],
[
"Revert To",
"When people turn on autosaving, displays a submenu that lists recent document versions and an option to display the version browser. After people choose a version to restore, it replaces the current document.",
""
],
[
"Page Setup…",
"Opens a panel for specifying printing parameters like paper size and printing orientation. A document can save the printing parameters that people specify.",
"Include the Page Setup item if you need to support printing parameters that apply to a specific document. Parameters that are global in nature, like a printer’s name, or that people change frequently, like the number of copies to print, belong in the Print panel."
],
[
"Print…",
"Opens the standard Print panel, which lets people print to a printer, send a fax, or save as a PDF.",
""
]
]
}
]
},
{
"heading": "Edit menu",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "The Edit menu lets people make changes to content in the current document or text container, and provides commands for interacting with the Clipboard. Because many editing commands apply to any editable content, the Edit menu is useful even in apps that aren’t document-based."
},
{
"type": "paragraph",
"text": "Determine whether Find menu items belong in the Edit menu. For example, if your app lets people search for files or other types of objects, Find menu items might be more appropriate in the File menu."
},
{
"type": "paragraph",
"text": "The Edit menu typically contains the following top-level menu items, listed in the following order."
},
{
"type": "table",
"rows": [
[
"Menu item",
"Action",
"Guidance"
],
[
"Undo",
"Reverses the effect of the previous user operation.",
"Clarify the target of the undo. For example, if people just selected a menu item, you can append the item’s title, such as Undo Paste and Match Style. For a text entry operation, you might append the word Typing to give Undo Typing."
],
[
"Redo",
"Reverses the effect of the previous Undo operation.",
"Clarify the target of the redo. For example, if people just reversed a menu item selection, you can append the item’s title, such as Redo Paste and Match Style. For a text entry operation, you might append the word Typing to give Redo Typing."
],
[
"Cut",
"Removes the selected data and stores it on the Clipboard, replacing the previous contents of the Clipboard.",
""
],
[
"Copy",
"Duplicates the selected data and stores it on the Clipboard.",
""
],
[
"Paste",
"Inserts the contents of the Clipboard at the current insertion point. The Clipboard contents remain unchanged, permitting people to choose Paste multiple times.",
""
],
[
"Paste and Match Style",
"Inserts the contents of the Clipboard at the current insertion point, matching the style of the inserted text to the surrounding text.",
""
],
[
"Delete",
"Removes the selected data, but doesn’t place it on the Clipboard.",
"Provide a Delete menu item instead of an Erase or Clear menu item. Choosing Delete is the equivalent of pressing the Delete key, so it’s important for the naming to be consistent."
],
[
"Select All",
"Highlights all selectable content in the current document or text container.",
""
],
[
"Find",
"Displays a submenu containing menu items for performing search operations in the current document or text container. Standard submenus include: Find, Find and Replace, Find Next, Find Previous, Use Selection for Find, and Jump to Selection.",
""
],
[
"Spelling and Grammar",
"Displays a submenu containing menu items for checking for and correcting spelling and grammar in the current document or text container. Standard submenus include: Show Spelling and Grammar, Check Document Now, Check Spelling While Typing, Check Grammar With Spelling, and Correct Spelling Automatically.",
""
],
[
"Substitutions",
"Displays a submenu containing items that let people toggle automatic substitutions while they type in a document or text container. Standard submenus include: Show Substitutions, Smart Copy/Paste, Smart Quotes, Smart Dashes, Smart Links, Data Detectors, and Text Replacement.",
""
],
[
"Transformations",
"Displays a submenu containing items that transform selected text. Standard submenus include: Make Uppercase, Make Lowercase, and Capitalize.",
""
],
[
"Speech",
"Displays a submenu containing Start Speaking and Stop Speaking items, which control when the system audibly reads selected text.",
""
],
[
"Start Dictation",
"Opens the dictation window and converts spoken words into text that’s added at the current insertion point. The system automatically adds the Start Dictation menu item at the bottom of the Edit menu.",
""
],
[
"Emoji & Symbols",
"Displays a Character Viewer, which includes emoji, symbols, and other characters people can insert at the current insertion point. The system automatically adds the Emoji & Symbols menu item at the bottom of the Edit menu.",
""
]
]
}
]
},
{
"heading": "Format menu",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "The Format menu lets people adjust text formatting attributes in the current document or text container. You can exclude this menu if your app doesn’t support formatted text editing."
},
{
"type": "paragraph",
"text": "The Format menu typically contains the following top-level menu items, listed in the following order."
},
{
"type": "table",
"rows": [
[
"Menu item",
"Action"
],
[
"Font",
"Displays a submenu containing items for adjusting font attributes of the selected text. Standard submenus include: Show Fonts, Bold, Italic, Underline, Bigger, Smaller, Show Colors, Copy Style, and Paste Style."
],
[
"Text",
"Displays a submenu containing items for adjusting text attributes of the selected text. Standard submenus include: Align Left, Align Center, Justify, Align Right, Writing Direction, Show Ruler, Copy Ruler, and Paste Ruler."
]
]
}
]
},
{
"heading": "View menu",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "The View menu lets people customize the appearance of all an app’s windows, regardless of type."
},
{
"type": "important",
"text": "ImportantThe View menu doesn’t include items for navigating between or managing specific windows; the Window menu provides these commands."
},
{
"type": "paragraph",
"text": "Provide a View menu even if your app supports only a subset of the standard view functions. For example, if your app doesn’t include a tab bar, toolbar, or sidebar, but does support full-screen mode, provide a View menu that includes only the Enter/Exit Full Screen menu item."
},
{
"type": "paragraph",
"text": "Ensure that each show/hide item title reflects the current state of the corresponding view. For example, when the toolbar is hidden, provide a Show Toolbar menu item; when the toolbar is visible, provide a Hide Toolbar menu item."
},
{
"type": "paragraph",
"text": "The View menu typically contains the following top-level menu items, listed in the following order."
},
{
"type": "table",
"rows": [
[
"Menu item",
"Action"
],
[
"Show/Hide Tab Bar",
"Toggles the visibility of the tab bar above the body area in a tab-based window"
],
[
"Show All Tabs/Exit Tab Overview",
"Enters and exits a view (similar to Mission Control) that provides an overview of all open tabs in a tab-based window"
],
[
"Show/Hide Toolbar",
"In a window that includes a toolbar, toggles the toolbar’s visibility"
],
[
"Customize Toolbar",
"In a window that includes a toolbar, opens a view that lets people customize toolbar items"
],
[
"Show/Hide Sidebar",
"In a window that includes a sidebar, toggles the sidebar’s visibility"
],
[
"Enter/Exit Full Screen",
"In an app that supports a full-screen experience, opens the window at full-screen size in a new space"
]
]
}
]
},
{
"heading": "App-specific menus",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Your app’s custom menus appear in the menu bar between the View menu and the Window menu. For example, Safari’s menu bar includes app-specific History and Bookmarks menus."
},
{
"type": "paragraph",
"text": "Provide app-specific menus for custom commands. People look in the menu bar when searching for app-specific commands, especially when using an app for the first time. Even when commands are available elsewhere in your app, it’s important to list them in the menu bar. Putting commands in the menu bar makes them easier for people to find, lets you assign keyboard shortcuts to them, and makes them more accessible to people using Full Keyboard Access. Excluding commands from the menu bar — even infrequently used or advanced commands — risks making them difficult for everyone to find."
},
{
"type": "paragraph",
"text": "As much as possible, reflect your app’s hierarchy in app-specific menus. For example, Mail lists the Mailbox, Message, and Format menus in an order that mirrors the relationships of these items: mailboxes contain messages, and messages contain formatting."
},
{
"type": "paragraph",
"text": "Aim to list app-specific menus in order from most to least general or commonly used. People tend to expect menus in the leading end of a list to be more specialized than menus in the trailing end."
}
]
},
{
"heading": "Window menu",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "The Window menu lets people navigate, organize, and manage an app’s windows."
},
{
"type": "important",
"text": "ImportantThe Window menu doesn’t help people customize the appearance of windows or close them. To customize a window, people use commands in the View menu; to close a window, people choose Close in the File menu."
},
{
"type": "paragraph",
"text": "Provide a Window menu even if your app has only one window. Include the Minimize and Zoom menu items so people using Full Keyboard Access can use the keyboard to invoke these functions."
},
{
"type": "paragraph",
"text": "Consider including menu items for showing and hiding panels. A panel provides information, configuration options, or tools for interacting with content in a primary window, and typically appears only when people need it. There’s no need to provide access to the font panel or text color panel because the Format menu lists these panels."
},
{
"type": "paragraph",
"text": "The Window menu typically contains the following top-level menu items, listed in the following order."
},
{
"type": "table",
"rows": [
[
"Menu item",
"Action",
"Guidance"
],
[
"Minimize",
"Minimizes the active window to the Dock. Pressing the Option key changes this item to Minimize All.",
""
],
[
"Zoom",
"Toggles between a predefined size appropriate to the window’s content and the window size people set. Pressing the Option key changes this item to Zoom All.",
"Avoid using Zoom to enter or exit full-screen mode. The View menu supports these functions."
],
[
"Show Previous Tab",
"Shows the tab before the current tab in a tab-based window.",
""
],
[
"Show Next Tab",
"Shows the tab after the current tab in a tab-based window.",
""
],
[
"Move Tab to New Window",
"Opens the current tab in a new window.",
""
],
[
"Merge All Windows",
"Combines all open windows into a single tabbed window.",
""
],
[
"Enter/Exit Full Screen",
"In an app that supports a full-screen experience, opens the window at full-screen size in a new space.",
"Include this item in the Window menu only if your app doesn’t have a View menu. In this scenario, continue to provide separate Minimize and Zoom menu items."
],
[
"Bring All to Front",
"Brings all an app’s open windows to the front, maintaining their onscreen location, size, and layering order. (Clicking the app icon in the Dock has the same effect.) Pressing the Option key changes this item to Arrange in Front, which brings an app’s windows to the front in a neatly tiled arrangement.",
""
],
[
"Name of an open app-specific window",
"Brings the selected window to the front.",
"List the currently open windows in alphabetical order for easy scanning. Avoid listing panels or other modal views."
]
]
}
]
},
{
"heading": "Help menu",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "The Help menu — located at the trailing end of the menu bar — provides access to an app’s help documentation. When you use the Help Book format for this documentation, macOS automatically includes a search field at the top of the Help menu."
},
{
"type": "table",
"rows": [
[
"Menu item",
"Action",
"Guidance"
],
[
"Send YourAppName Feedback to Apple",
"Opens the Feedback Assistant, in which people can provide feedback.",
""
],
[
"YourAppName Help",
"When the content uses the Help Book format, opens the content in the built-in Help Viewer.",
""
],
[
"Additional Item",
"",
"Use a separator between your primary help documentation and additional items, which might include registration information or release notes. Keep the total the number of items you list in the Help menu small to avoid overwhelming people with too many choices when they need help. Alternatively, consider linking to additional items from within your help documentation."
]
]
},
{
"type": "paragraph",
"text": "For guidance, see Offering help; for developer guidance, see NSHelpManager."
}
]
},
{
"heading": "Dynamic menu items",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "In rare cases, it can make sense to present a dynamic menu item, which is a menu item that changes its behavior when people choose it while pressing a modifier key (Control, Option, Shift, or Command). For example, the Minimize item in the Window menu changes to Minimize All when people press the Option key."
},
{
"type": "paragraph",
"text": "Avoid making a dynamic menu item the only way to accomplish a task. Dynamic menu items are hidden by default, so they’re best suited to offer shortcuts to advanced actions that people can accomplish in other ways. For example, if someone hasn’t discovered the Minimize All dynamic menu item in the Window menu, they can still minimize each open window."
},
{
"type": "paragraph",
"text": "Use dynamic menu items primarily in menu bar menus. Adding a dynamic menu item to contextual or Dock menus can make the item even harder for people to discover."
},
{
"type": "paragraph",
"text": "Require only a single modifier key to reveal a dynamic menu item. It can be physically awkward to press more than one key while simultaneously opening a menu and choosing a menu item, in addition to reducing the discoverability of the dynamic behavior. For developer guidance, see isAlternate."
},
{
"type": "tip",
"text": "TipmacOS automatically sets the width of a menu to hold the widest item, including dynamic menu items."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iOS, tvOS, visionOS, or watchOS."
}
]
},
{
"heading": "iPadOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "The menu bar displays the top-level menus for your app or game, including both system-provided menus and any custom ones you choose to add. People reveal the menu bar by moving the pointer to the top edge of the screen, or swiping down from it. When visible, the menu bar occupies the same vertical space as the status bar at the top edge of the screen."
},
{
"type": "paragraph",
"text": "As with the macOS menu bar, the iPadOS menu bar provides a familiar way for people to learn what an app does, find the commands they need, and discover keyboard shortcuts. While they are similar in most respects, there are a few key differences between the menu bars on each platform."
},
{
"type": "table",
"rows": [
[
"",
"iPadOS",
"macOS"
],
[
"Menu bar visibility",
"Hidden until revealed",
"Visible by default"
],
[
"Horizontal alignment",
"Centered",
"Leading side"
],
[
"Menu bar extras",
"Not available",
"System default and custom"
],
[
"Window controls",
"In the menu bar when the app is full screen",
"Never in the menu bar"
],
[
"Apple menu",
"Not available",
"Always available"
],
[
"App menu",
"About, Services, and app visibility-related items not available",
"Always available"
]
]
},
{
"type": "paragraph",
"text": "Because the menu bar is often hidden when running an app full screen, ensure that people can access all of your app’s functions through its UI. In particular, always offer other ways to accomplish tasks assigned to dynamic menu items, since these are only available when a hardware keyboard is connected. Avoid using the menu bar as a catch-all location for functionality that doesn’t fit in elsewhere."
},
{
"type": "paragraph",
"text": "Reserve the YourAppName > Settings menu item for opening your app’s page in iPadOS Settings. If your app includes its own internal preferences area, link to it with a separate menu item beneath Settings in the same group. Place any other custom app-wide configuration options in this section as well."
},
{
"type": "paragraph",
"text": "For apps with tab-style navigation, consider adding each tab as a menu item in the View menu. Since each tab is a different view of the app, the View menu is a natural place to offer an additional way to navigate between tabs. If you do this, consider assigning key bindings to each tab to make navigation even more convenient."
},
{
"type": "paragraph",
"text": "Consider grouping menu items into submenus to conserve vertical space. Menu item rows on iPad use more space than on Mac to make them easier to tap. Because of this, and the smaller screen sizes of some iPads, it can be helpful to group related items into submenus more frequently than in the menu bar on Mac."
}
]
},
{
"heading": "macOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "The menu bar in macOS includes the Apple menu, which is always the first item on the leading side of the menu bar. The Apple menu includes system-defined menu items that are always available, and you can’t modify or remove it. Space permitting, the system can also display menu bar extras in the trailing end of the menu bar. For guidance, see Menu bar extras."
},
{
"type": "paragraph",
"text": "When menu bar space is constrained, the system prioritizes the display of menus and essential menu bar extras. To ensure that menus remain readable, the system may decrease the space between the titles, truncating them if necessary."
},
{
"type": "paragraph",
"text": "When people enter full-screen mode, the menu bar typically hides until they reveal it by moving the pointer to the top of the screen. For guidance, see Going full screen."
}
]
},
{
"heading": "Menu bar extras",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "A menu bar extra exposes app-specific functionality using an icon that appears in the menu bar when your app is running, even when it’s not the frontmost app. Menu bar extras are on the opposite side of the menu bar from your app’s menus. For developer guidance, see MenuBarExtra."
},
{
"type": "paragraph",
"text": "When necessary, the system hides menu bar extras to make room for app menus. Similarly, if there are too many menu bar extras, the system may hide some to avoid crowding app menus."
},
{
"type": "paragraph",
"text": "Consider using a symbol to represent your menu bar extra. You can create an icon or you can choose one of the SF Symbols, using it as-is or customizing it to suit your needs. Both interface icons and symbols use black and clear colors to define their shapes; the system can apply other colors to the black areas in each image so it looks good on both dark and light menu bars, and when your menu bar extra is selected. The menu bar’s height is 24 pt."
},
{
"type": "paragraph",
"text": "Display a menu — not a popover — when people click your menu bar extra. Unless the app functionality you want to expose is too complex for a menu, avoid presenting it in a popover."
},
{
"type": "paragraph",
"text": "Let people — not your app — decide whether to put your menu bar extra in the menu bar. Typically, people add a menu bar extra to the menu bar by changing a setting in an app’s settings window. To ensure discoverability, however, consider giving people the option of doing so during setup."
},
{
"type": "paragraph",
"text": "Avoid relying on the presence of menu bar extras. The system hides and shows menu bar extras regularly, and you can’t be sure which other menu bar extras people have chosen to display or predict the location of your menu bar extra."
},
{
"type": "paragraph",
"text": "Consider exposing app-specific functionality in other ways, too. For example, you can provide a Dock menu that appears when people Control-click your app’s Dock icon. People can hide or choose not to use your menu bar extra, but a Dock menu is aways available when your app is running."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Menus"
},
{
"type": "paragraph",
"text": "Dock menus"
},
{
"type": "paragraph",
"text": "Standard keyboard shortcuts"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "CommandMenu — SwiftUI"
},
{
"type": "paragraph",
"text": "Adding menus and shortcuts to the menu bar and user interface — UIKit"
},
{
"type": "paragraph",
"text": "NSStatusBar — AppKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"June 9, 2025",
"Added guidance for the menu bar in iPadOS."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "Standard keyboard shortcuts",
"url": "/design/human-interface-guidelines/keyboards#Standard-keyboard-shortcuts"
},
{
"title": "Menus",
"url": "/design/human-interface-guidelines/menus"
},
{
"title": "Anatomy",
"url": "/design/human-interface-guidelines/the-menu-bar#Anatomy"
},
{
"title": "macOS Platform considerations",
"url": "/design/human-interface-guidelines/the-menu-bar#macOS"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/the-menu-bar#Best-practices"
},
{
"title": "Standard icons",
"url": "/design/human-interface-guidelines/icons#Standard-icons"
},
{
"title": "App menu",
"url": "/design/human-interface-guidelines/the-menu-bar#App-menu"
},
{
"title": "settings",
"url": "/design/human-interface-guidelines/settings"
},
{
"title": "File menu",
"url": "/design/human-interface-guidelines/the-menu-bar#File-menu"
},
{
"title": "Edit menu",
"url": "/design/human-interface-guidelines/the-menu-bar#Edit-menu"
},
{
"title": "Format menu",
"url": "/design/human-interface-guidelines/the-menu-bar#Format-menu"
},
{
"title": "View menu",
"url": "/design/human-interface-guidelines/the-menu-bar#View-menu"
},
{
"title": "Window menu",
"url": "/design/human-interface-guidelines/the-menu-bar#Window-menu"
},
{
"title": "tab bar",
"url": "/design/human-interface-guidelines/tab-bars"
},
{
"title": "toolbar",
"url": "/design/human-interface-guidelines/toolbars"
},
{
"title": "sidebar",
"url": "/design/human-interface-guidelines/sidebars"
},
{
"title": "full-screen experience",
"url": "/design/human-interface-guidelines/going-full-screen"
},
{
"title": "App-specific menus",
"url": "/design/human-interface-guidelines/the-menu-bar#App-specific-menus"
},
{
"title": "panel",
"url": "/design/human-interface-guidelines/panels"
},
{
"title": "Help menu",
"url": "/design/human-interface-guidelines/the-menu-bar#Help-menu"
},
{
"title": "Offering help",
"url": "/design/human-interface-guidelines/offering-help"
},
{
"title": "Dynamic menu items",
"url": "/design/human-interface-guidelines/the-menu-bar#Dynamic-menu-items"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/the-menu-bar#Platform-considerations"
},
{
"title": "iPadOS",
"url": "/design/human-interface-guidelines/the-menu-bar#iPadOS"
},
{
"title": "status bar",
"url": "/design/human-interface-guidelines/status-bars"
},
{
"title": "Menu bar extras",
"url": "/design/human-interface-guidelines/the-menu-bar#Menu-bar-extras"
},
{
"title": "icon",
"url": "/design/human-interface-guidelines/icons"
},
{
"title": "SF Symbols",
"url": "/design/human-interface-guidelines/sf-symbols"
},
{
"title": "popover",
"url": "/design/human-interface-guidelines/popovers"
},
{
"title": "Dock menu",
"url": "https://developer.apple.com/design/human-interface-guidelines/dock-menus"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/the-menu-bar#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/the-menu-bar#Related"
},
{
"title": "Dock menus",
"url": "/design/human-interface-guidelines/dock-menus"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/the-menu-bar#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/the-menu-bar#Videos"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/the-menu-bar#Change-log"
}
],
"image_count": 0
},
{
"title": "Token fields",
"url": "https://developer.apple.com/design/human-interface-guidelines/token-fields",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"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": "paragraph",
"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": "paragraph",
"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": "paragraph",
"text": "Tokens can also represent search terms in some situations; for guidance, see Search fields."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Add value with a context menu. People often benefit from a context menu with additional options or information about a token."
},
{
"type": "paragraph",
"text": "Consider providing additional ways to convert text into tokens. 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": "paragraph",
"text": "Consider customizing the delay the system uses before showing suggested tokens. 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."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iOS, iPadOS, tvOS, visionOS, and watchOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Text fields"
},
{
"type": "paragraph",
"text": "Search fields"
},
{
"type": "paragraph",
"text": "Context menus"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "NSTokenField — AppKit"
}
]
}
],
"platforms": [],
"related": [
{
"title": "Search fields",
"url": "/design/human-interface-guidelines/search-fields"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/token-fields#Best-practices"
},
{
"title": "context menu",
"url": "https://developer.apple.com/design/human-interface-guidelines/context-menus"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/token-fields#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/token-fields#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/token-fields#Related"
},
{
"title": "Text fields",
"url": "/design/human-interface-guidelines/text-fields"
},
{
"title": "Context menus",
"url": "/design/human-interface-guidelines/context-menus"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/token-fields#Developer-documentation"
}
],
"image_count": 0
},
{
"title": "Toolbars",
"url": "https://developer.apple.com/design/human-interface-guidelines/toolbars",
"category": "general",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "A toolbar consists of one or more sets of controls arranged horizontally along the top or bottom edge of the view, grouped into logical sections."
},
{
"type": "paragraph",
"text": "Toolbars act on content in the view, facilitate navigation, and help orient people in the app. They include three types of content:"
},
{
"type": "list",
"items": [
"The title of the current view",
"Navigation controls, like back and forward, and search fields",
"Actions, or bar items, like buttons and menus"
]
},
{
"type": "paragraph",
"text": "In contrast to a toolbar, a tab bar is specifically for navigating between areas of an app."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Choose items deliberately to avoid overcrowding. People need to be able to distinguish and activate each item, so you don’t want to put too many items in the toolbar. To accommodate variable view widths, define which items move to the overflow menu as the toolbar becomes narrower."
},
{
"type": "note",
"text": "NoteThe system automatically adds an overflow menu in macOS or iPadOS when items no longer fit. Don’t add an overflow menu manually, and avoid layouts that cause toolbar items to overflow by default."
},
{
"type": "paragraph",
"text": "Add a More menu to contain additional actions. Prioritize less important actions for inclusion in the More menu. Try to include all actions in the toolbar if possible, and only add this menu if you really need it."
},
{
"type": "paragraph",
"text": "The standard toolbar in macOS Notes includes a More menu with extra commands."
},
{
"type": "paragraph",
"text": "As the window narrows, the More menu moves into an overflow menu along with other toolbar items that no longer fit."
},
{
"type": "paragraph",
"text": "In iPadOS and macOS apps, consider letting people customize the toolbar to include their most common items. Toolbar customization is especially useful in apps that provide a lot of items — or that include advanced functionality that not everyone needs — and in apps that people tend to use for long periods of time. For example, it works well to make a range of editing actions available for toolbar customization, because people often use different types of editing commands based on their work style and their current project."
},
{
"type": "paragraph",
"text": "Reduce the use of toolbar backgrounds and tinted controls. Any custom backgrounds and appearances you use might overlay or interfere with background effects that the system provides. Instead, use the content layer to inform the color and appearance of the toolbar, and use a ScrollEdgeEffectStyle when necessary to distinguish the toolbar area from the content area. This approach helps your app express its unique personality without distracting from content."
},
{
"type": "paragraph",
"text": "Avoid applying a similar color to toolbar item labels and content layer backgrounds. If your app already has bright, colorful content in the content layer, prefer using the default monochromatic appearance of toolbars. For more guidance, see Liquid Glass color."
},
{
"type": "paragraph",
"text": "Prefer using standard components in a toolbar. By default, standard buttons, text fields, headers, and footers have corner radii that are concentric with bar corners. If you need to create a custom component, ensure that its corner radius is also concentric with the bar’s corners."
},
{
"type": "paragraph",
"text": "Consider temporarily hiding toolbars for a distraction-free experience. Sometimes people appreciate a minimal interface to reduce distractions or reveal more content. If you support this, do so contextually when it makes the most sense, and offer ways to reliably restore hidden interface elements. For guidance, see Going full screen. For guidance specific to visionOS, see Immersive experiences."
}
]
},
{
"heading": "Titles",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Provide a useful title for each window. A title helps people confirm their location as they navigate your app, and differentiates between the content of multiple open windows. If titling a toolbar seems redundant, you can leave the title area empty. For example, Notes doesn’t title the current note when a single window is open, because the first line of content typically supplies sufficient context. However, when opening notes in separate windows, the system titles them with the first line of content so people can tell them apart."
},
{
"type": "paragraph",
"text": "Don’t title windows with your app name. Your app’s name doesn’t provide useful information about your content hierarchy or any window or area in your app, so it doesn’t work well as a title."
},
{
"type": "paragraph",
"text": "Write a concise title. Aim for a word or short phrase that distills the purpose of the window or view, and keep the title under 15 characters long so you leave enough room for other controls."
}
]
},
{
"heading": "Navigation",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "A toolbar with navigation controls appears at the top of a window, helping people move through a hierarchy of content. A toolbar also often contains a search field for quick navigation between areas or pieces of content. In iOS, a navigation-specific toolbar is sometimes called a navigation bar."
},
{
"type": "paragraph",
"text": "Use the standard Back and Close buttons. People know that the standard Back button lets them retrace their steps through a hierarchy of information, and the standard Close button closes a modal view. Prefer the standard symbols for each, and don’t use a text label that says Back or Close. If you create a custom version of either, make sure it still looks the same, behaves as people expect, and matches the rest of your interface, and ensure you consistently implement it throughout your app or game. For guidance, see Icons."
}
]
},
{
"heading": "Actions",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Provide actions that support the main tasks people perform. In general, prioritize the commands that people are most likely to want. These commands are often the ones people use most frequently, but in some apps it might make sense to prioritize commands that map to the highest level or most important objects people work with."
},
{
"type": "paragraph",
"text": "Make sure the meaning of each control is clear. Don’t make people guess or experiment to figure out what a toolbar item does. Prefer simple, recognizable symbols for items instead of text, except for actions like edit that aren’t well-represented by symbols. For guidance on symbols that represent common actions, see Standard icons."
},
{
"type": "paragraph",
"text": "Prefer system-provided symbols without borders. System-provided symbols are familiar, automatically receive appropriate coloring and vibrancy, and respond consistently to user interactions. Borders (like outlined circle symbols) aren’t necessary because the section provides a visible container, and the system defines hover and selection state appearances automatically. For guidance, see SF Symbols."
},
{
"type": "paragraph",
"text": "Use the .prominent style for key actions such as Done or Submit. This separates and tints the action so there’s a clear focal point. Only specify one primary action, and put it on the trailing side of the toolbar."
}
]
},
{
"heading": "Item groupings",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "You can position toolbar items in three locations: the leading edge, center area, and trailing edge of the toolbar. These areas provide familiar homes for navigation controls, window or document titles, common actions, and search."
},
{
"type": "list",
"items": [
"Leading edge. Elements that let people return to the previous document and show or hide a sidebar appear at the far leading edge, followed by the view title. Next to the title, the toolbar can include a document menu that contains standard and app-specific commands that affect the document as a whole, such as Duplicate, Rename, Move, and Export. To ensure that these items are always available, items on the toolbar’s leading edge aren’t customizable.",
"Center area. Common, useful controls appear in the center area, and the view title can appear here if it’s not on the leading edge. In macOS and iPadOS, people can add, remove, and rearrange items here if you let them customize the toolbar, and items in this section automatically collapse into the system-managed overflow menu when the window shrinks enough in size.",
"Trailing edge. The trailing edge contains important items that need to remain available, buttons that open nearby inspectors, an optional search field, and the More menu that contains additional items and supports toolbar customization. It also includes a primary action like Done when one exists. Items on the trailing edge remain visible at all window sizes."
]
},
{
"type": "paragraph",
"text": "To position items in the groupings you want, pin them to the leading edge, center, or trailing edge, and insert space between buttons or other items where appropriate."
},
{
"type": "paragraph",
"text": "Group toolbar items logically by function and frequency of use. For example, Keynote includes several sections that are based on functionality, including one for presentation-level commands, one for playback commands, and one for object insertion."
},
{
"type": "paragraph",
"text": "Group navigation controls and critical actions like Done, Close, or Save in dedicated, familiar, and visually distinct sections. This reflects their importance and helps people discover and understand these actions."
},
{
"type": "paragraph",
"text": "Keep consistent groupings and placement across platforms. This helps people develop familiarity with your app and trust that it behaves similarly regardless of where they use it."
},
{
"type": "paragraph",
"text": "Minimize the number of groups. Too many groups of controls can make a toolbar feel cluttered and confusing, even with the added space on iPad and Mac. In general, aim for a maximum of three."
},
{
"type": "paragraph",
"text": "Keep actions with text labels separate. Placing an action with a text label next to an action with a symbol can create the illusion of a single action with a combined text and symbol, leading to confusion and misinterpretation. If your toolbar includes multiple text-labeled buttons, the text of those buttons may appear to run together, making the buttons indistinguishable. Add separation by inserting fixed space between the buttons. For developer guidance, see UIBarButtonItem.SystemItem.fixedSpace."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for tvOS."
}
]
},
{
"heading": "iOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Prioritize only the most important items for inclusion in the main toolbar area. Because space is so limited, carefully consider which actions are essential to your app and include those first. Create a More menu to include additional items."
},
{
"type": "paragraph",
"text": "Use a large title to help people stay oriented as they navigate and scroll. By default, a large title transitions to a standard title as people begin scrolling the content, and transitions back to large when people scroll to the top, reminding them of their current location. For developer guidance, see prefersLargeTitles."
}
]
},
{
"heading": "iPadOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Consider combining a toolbar with a tab bar. In iPadOS, a toolbar and a tab bar can coexist in the same horizontal space at the top of the view. This is particularly useful for layouts where you want to navigate between a few main app areas while keeping the full width of the window available for content. For guidance, see Layout and Windows."
}
]
},
{
"heading": "macOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "In a macOS app, the toolbar resides in the frame at the top of a window, either below or integrated with the title bar. Note that window titles can display inline with controls, and toolbar items don’t include a bezel."
},
{
"type": "paragraph",
"text": "Make every toolbar item available as a command in the menu bar. Because people can customize the toolbar or hide it, it can’t be the only place that presents a command. In contrast, it doesn’t make sense to provide a toolbar item for every menu item, because not all menu commands are important enough or used often enough to warrant space in the toolbar."
}
]
},
{
"heading": "visionOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "In visionOS, the system-provided toolbar appears along the bottom edge of a window, above the window-management controls, and in a parallel plane that’s slightly in front of the window along the z-axis."
},
{
"type": "paragraph",
"text": "To maintain the legibility of toolbar items as content scrolls behind them, visionOS uses a variable blur in the bar background. The variable blur anchors the bar above the scrolling content while letting the view’s glass material remain uniform and undivided."
},
{
"type": "paragraph",
"text": "In visionOS, you can supply either a symbol or a text label for each toolbar item. When people look at a toolbar item that contains a symbol, visionOS reveals the text label, providing additional information."
},
{
"type": "paragraph",
"text": "Prefer using a system-provided toolbar. The standard toolbar has a consistent and familiar appearance and is optimized to work well with eye and hand input. In addition, the system automatically places a standard toolbar in the correct position in relation to its window."
},
{
"type": "paragraph",
"text": "Avoid creating a vertical toolbar. In visionOS, tab bars are vertical, so presenting a vertical toolbar could confuse people."
},
{
"type": "paragraph",
"text": "Try to prevent windows from resizing below the width of the toolbar. visionOS doesn’t include a menu bar where each app lists all its actions, so it’s important for the toolbar to provide reliable access to essential controls regardless of a window’s size."
},
{
"type": "paragraph",
"text": "If your app can enter a modal state, consider offering contextually relevant toolbar controls. For example, a photo-editing app might enter a modal state to help people perform a multistep editing task. In this scenario, the controls in the modal editing view are different from the controls in the main window. Be sure to reinstate the window’s standard toolbar controls when the app exits the modal state."
},
{
"type": "paragraph",
"text": "Avoid using a pull-down menu in a toolbar. A pull-down menu lets you offer additional actions related to a toolbar item, but can be difficult for people to discover and may clutter your interface. Because a toolbar is located at the bottom edge of a window in visionOS, a pull-down menu might obscure the standard window controls that appear below the bottom edge. For guidance, see Pull-down buttons."
}
]
},
{
"heading": "watchOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "A toolbar button lets you offer important app functionality in a view that displays related content. You can place toolbar buttons in the top corners or along the bottom. If you place these buttons above scrolling content, the buttons always remain visible, as the content scrolls under them."
},
{
"type": "paragraph",
"text": "Top toolbar buttons"
},
{
"type": "paragraph",
"text": "Bottom toolbar buttons"
},
{
"type": "paragraph",
"text": "For developer guidance, see topBarLeading, topBarTrailing, or bottomBar."
},
{
"type": "paragraph",
"text": "You can also place a button in the scrolling view. By default, a scrolling toolbar button remains hidden until people reveal it by scrolling up. People frequently scroll to the top of a scrolling view, so discovering a toolbar button is automatic."
},
{
"type": "paragraph",
"text": "Toolbar button hidden"
},
{
"type": "paragraph",
"text": "Toolbar button shown"
},
{
"type": "paragraph",
"text": "For developer guidance, see primaryAction."
},
{
"type": "paragraph",
"text": "Use a scrolling toolbar button for an important action that isn’t a primary app function. A toolbar button gives you the flexibility to offer important functionality in a view whose primary purpose is related to that functionality, but may not be the same. For example, Mail provides the essential New Message action in a toolbar button at the top of the Inbox view. The primary purpose of the Inbox is to display a scrollable list of email messages, so it makes sense to offer the closely related compose action in a toolbar button at the top of the view."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Sidebars"
},
{
"type": "paragraph",
"text": "Tab bars"
},
{
"type": "paragraph",
"text": "Layout"
},
{
"type": "paragraph",
"text": "Buttons"
},
{
"type": "paragraph",
"text": "Search fields"
},
{
"type": "paragraph",
"text": "Apple Design Resources"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Toolbars — SwiftUI"
},
{
"type": "paragraph",
"text": "UIToolbar — UIKit"
},
{
"type": "paragraph",
"text": "NSToolbar — AppKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"December 16, 2025",
"Updated guidance for Liquid Glass."
],
[
"June 9, 2025",
"Added guidance for grouping bar items, updated guidance for using symbols, and incorporated navigation bar guidance."
],
[
"June 21, 2023",
"Updated to include guidance for visionOS."
],
[
"June 5, 2023",
"Updated guidance for using toolbars in watchOS."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "search fields",
"url": "/design/human-interface-guidelines/search-fields"
},
{
"title": "buttons",
"url": "/design/human-interface-guidelines/buttons"
},
{
"title": "menus",
"url": "/design/human-interface-guidelines/menus"
},
{
"title": "tab bar",
"url": "/design/human-interface-guidelines/tab-bars"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/toolbars#Best-practices"
},
{
"title": "Liquid Glass color",
"url": "/design/human-interface-guidelines/color#Liquid-Glass-color"
},
{
"title": "Going full screen",
"url": "/design/human-interface-guidelines/going-full-screen"
},
{
"title": "Immersive experiences",
"url": "/design/human-interface-guidelines/immersive-experiences"
},
{
"title": "Titles",
"url": "/design/human-interface-guidelines/toolbars#Titles"
},
{
"title": "Navigation",
"url": "/design/human-interface-guidelines/toolbars#Navigation"
},
{
"title": "Icons",
"url": "/design/human-interface-guidelines/icons"
},
{
"title": "Actions",
"url": "/design/human-interface-guidelines/toolbars#Actions"
},
{
"title": "Standard icons",
"url": "/design/human-interface-guidelines/icons#Standard-icons"
},
{
"title": "SF Symbols",
"url": "/design/human-interface-guidelines/sf-symbols"
},
{
"title": "Item groupings",
"url": "/design/human-interface-guidelines/toolbars#Item-groupings"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/toolbars#Platform-considerations"
},
{
"title": "iOS",
"url": "/design/human-interface-guidelines/toolbars#iOS"
},
{
"title": "iPadOS",
"url": "/design/human-interface-guidelines/toolbars#iPadOS"
},
{
"title": "Layout",
"url": "/design/human-interface-guidelines/layout"
},
{
"title": "Windows",
"url": "/design/human-interface-guidelines/windows"
},
{
"title": "macOS",
"url": "/design/human-interface-guidelines/toolbars#macOS"
},
{
"title": "visionOS",
"url": "/design/human-interface-guidelines/toolbars#visionOS"
},
{
"title": "Pull-down buttons",
"url": "/design/human-interface-guidelines/pull-down-buttons"
},
{
"title": "watchOS",
"url": "/design/human-interface-guidelines/toolbars#watchOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/toolbars#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/toolbars#Related"
},
{
"title": "Sidebars",
"url": "/design/human-interface-guidelines/sidebars"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/toolbars#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/toolbars#Videos"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/toolbars#Change-log"
}
],
"image_count": 0
}
]
}
Reference in New Issue View Git Blame Copy Permalink