Hig Components Menus

Apple HIG: Menus and Buttons

Check for .claude/apple-design-context.md before asking questions. Use existing context and only ask for information not already covered.

Key Principles

1. Menus should be contextual and predictable. Standard items in standard locations. Follow platform conventions for ordering and grouping.

2. Use standard button styles. System-defined styles communicate affordance and maintain visual consistency. Prefer them over custom designs.

3. Toolbars for frequent actions. Most commonly used commands in the toolbar. Rarely used actions belong in menus.

4. Menu bar is the primary command interface on macOS. Every command reachable from the menu bar. Toolbars and context menus supplement, not replace.

5. Context menus for secondary actions. Right-click or long-press, relevant to the item under the pointer. Never put a command only in a context menu.

6. Pop-up buttons for mutually exclusive choices. Select exactly one option from a set.

7. Pull-down buttons for action lists. No current selection; they offer a set of commands.

8. Action buttons consolidate related actions behind a single icon in toolbars or title bars.

9. Disclosure controls for progressive disclosure. Show or hide additional content.

10. Dock menus: short and focused on the most useful actions when the app is running.

Reference Index

Output Format

1. Component recommendation -- which menu or button type and why. 2. Visual hierarchy -- placement, sizing, grouping within the interface. 3. Platform-specific behavior across iOS, iPadOS, macOS, visionOS. 4. Keyboard shortcuts (macOS) -- standard and custom shortcuts for menu items and toolbar actions.

Questions to Ask

1. Which platforms? 2. Primary or secondary action? 3. How many actions need to be available? 4. macOS menu bar app?

Related Skills

• hig-components-search -- Search fields, page controls alongside toolbars and menus
• hig-components-controls -- Toggles, pickers, segmented controls complementing buttons
• hig-components-dialogs -- Alerts, sheets, popovers triggered by menu items or buttons
• hig-inputs -- Keyboard shortcuts and pointer interactions with menus and toolbars

---

Built by [Raintree Technology](https://raintree.technology) · [More developer tools](https://raintree.technology)

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/action-button.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Action button

Best practices

Support the Action button with a set of your app’s essential functions.

For each action you support, write a short label that succinctly describes it.

Prefer letting the system show people how to use the Action button with your app.

Platform considerations

iOS

Let people use your actions without leaving their current context.

watchOS

Consider offering a secondary function that supports or advances the primary action people choose.

Prefer using subsequent button presses to support additional functionality rather than to stop or conclude a function.

Pause the current function when people press the Action button and side button together.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/action-button

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/buttons.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Buttons

• Style. A visual style based on size, color, and shape.

• Content. A symbol (or icon), text label, or both that a button displays to convey its purpose.

• Role. A system-defined role that identifies a button’s semantic meaning and can affect its appearance.

Best practices

Make buttons easy for people to use.

Always include a press state for a custom button.

Style

In general, use a button that has a prominent visual style for the most likely action in a view.

Use style — not size — to visually distinguish the preferred choice among multiple options.

Avoid applying a similar color to button labels and content layer backgrounds.

Content

Ensure that each button clearly communicates its purpose.

Try to associate familiar actions with familiar icons.

Consider using text when a short label communicates more clearly than an icon.

Role

• Normal. No specific meaning.

• Primary. The button is the default button — the button people are most likely to choose.

• Cancel. The button cancels the current action.

• Destructive. The button performs an action that can result in data destruction.

Assign the primary role to the button people are most likely to choose.

Don’t assign the primary role to a button that performs a destructive action, even if that action is the most likely choice.

Platform considerations

iOS, iPadOS

Configure a button to display an activity indicator when you need to provide feedback about an action that doesn’t instantly complete.

macOS

Push buttons

Use a flexible-height push button only when you need to display tall or variable height content.

Append a trailing ellipsis to the title when a push button opens another window, view, or app.

Consider supporting spring loading.

Square buttons

Use square buttons in a view, not in the window frame.

Prefer using a symbol in a square button.

Avoid using labels to introduce square buttons.

Help buttons

Use the system-provided help button to display your help documentation.

When possible, open the help topic that’s related to the current context.

Include no more than one help button per window.

Position help buttons where people expect to find them.

Use a help button within a view, not in the window frame.

Avoid displaying text that introduces a help button.

Image buttons

Use an image button in a view, not in the window frame.

Include about 10 pixels of padding between the edges of the image and the button edges.

If you need to include a label, position it below the image button.

visionOS

Prefer buttons that have a discernible background shape and fill.

• When a button appears on top of a glass window, use the `thin` material as the button’s background.

• When a button appears floating in space, use the glass material for its background.

Avoid creating a custom button that uses a white background fill and black text or icons.

In general, prefer circular or capsule-shape buttons.

Provide enough space around a button to make it easy for people to look at it.

Choose the right shape if you need to display text-labeled buttons in a stack or row.

Use standard controls to take advantage of the audible feedback sounds people already know.

watchOS

Use a toolbar to place buttons in the corners.

Prefer buttons that span the width of the screen for primary actions in your app.

Use toolbar buttons to provide either navigation to related areas or contextual actions for the view’s content.

Use the same height for vertical stacks of one- and two-line text buttons.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/buttons

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/context-menus.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Context menus

• 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

Best practices

Prioritize relevancy when choosing items to include in a context menu.

Aim for a small number of menu items.

Support context menus consistently throughout your app.

Always make context menu items available in the main interface, too.

If you need to use submenus to manage a menu’s complexity, keep them to one level.

Hide unavailable menu items, don’t dim them.

Aim to place the most frequently used menu items where people are likely to encounter them first.

Show keyboard shortcuts in your app’s main menus, not in context menus.

Follow best practices for using separators.

In iOS, iPadOS, and visionOS, warn people about context menu items that can destroy data.

Content

Include a title in a context menu only if doing so clarifies the menu’s effect.

Represent menu item actions with familiar icons.

Platform considerations

iOS, iPadOS

Provide either a context menu or an edit menu for an item, but not both.

In iPadOS, consider using a context menu to let people create a new object in your app.

Prefer a graphical preview that clarifies the target of a context menu’s commands.

Ensure that your preview looks good as it animates.

visionOS

Consider using a context menu instead of a panel or inspector window to present frequently used functionality.

In general, avoid letting a context menu’s height exceed the height of the window.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/context-menus

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/disclosure-controls.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Disclosure controls

Best practices

Use a disclosure control to hide details until they’re relevant.

Disclosure triangles

• Collapsed
• Expanded

Provide a descriptive label when using a disclosure triangle.

Disclosure buttons

• Collapsed
• Expanded

Place a disclosure button near the content that it shows and hides.

Use no more than one disclosure button in a single view.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/disclosure-controls

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/dock-menus.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Dock menus

Best practices

Make custom Dock menu items available in other places, too.

Prefer high-value custom items for your Dock menu.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/dock-menus

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/edit-menus.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Edit menus

• 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.

Best practices

Prefer the system-provided edit menu.

Let people reveal an edit menu using the system-defined interactions they already know.

Offer commands that are relevant in the current context, removing or dimming commands that don’t apply.

List custom commands near relevant system-provided ones.

When it makes sense, let people select and copy noneditable text.

Support undo and redo when possible.

In general, avoid implementing other controls that perform the same functions as edit menu items.

Differentiate different types of deletion commands when necessary.

Content

Create short labels for custom commands.

Platform considerations

iOS, iPadOS

Ensure your edit menu works well in both styles.

Adjust an edit menu’s placement, if necessary.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/edit-menus

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/menus.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Menus

Labels

For each menu item, write a label that clearly and succinctly describes it.

To be consistent with platform experiences, use title-style capitalization.

Remove articles like _a_ , _an_ , and _the_ from menu-item labels to save space.

Show people when a menu item is unavailable.

Append an ellipsis to a menu item’s label when the action requires more information before it can complete.

Icons

Represent menu item actions with familiar icons.

Don’t display an icon if you can’t find one that clearly represents the menu item.

Use a single icon to introduce a group of similar items.

Organization

Prefer listing important or frequently used menu items first.

Consider grouping logically related items.

Prefer keeping all logically related commands in the same group, even if the commands don’t all have the same importance.

Be mindful of menu length.

Submenus

Use submenus sparingly.

Limit the depth and length of submenus.

Make sure a submenu remains available even when its nested menu items are unavailable.

Prefer using a submenu to indenting menu items.

Toggled items

Consider using a changeable label that describes an item’s current state.

Include a verb if a changeable label isn’t clear enough.

If necessary, display both menu items instead of one toggled item.

Consider using a checkmark to show that an attribute is currently in effect.

Consider offering a menu item that makes it easy to remove multiple toggled attributes.

In-game menus

Let players navigate in-game menus using the platform’s default interaction method.

Make sure your menus remain easy to open and read on all platforms you support.

Platform considerations

iOS, iPadOS

• Small. A row of four items appears at the top of the menu, above a list that contains the remaining items. For each item in the top row, the menu displays a symbol or icon, but no label.

• Medium. A row of three items appears at the top of the menu, above a list that contains the remaining items. For each item in the top row, the menu displays a symbol or icon above a short label.

• Large (the default). The menu displays all items in a list.

Choose a small or medium menu layout when it can help streamline people’s choices.

visionOS

Prefer displaying a menu near the content it controls.

Prefer the subtle breakthrough effect in most cases.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/menus

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Pop-up buttons

Best practices

Use a pop-up button to present a flat list of mutually exclusive options or states.

• Offer a list of actions

• Let people select multiple items

• Include a submenu

Provide a useful default selection.

Give people a way to predict a pop-up button’s options without opening it.

Consider using a pop-up button when space is limited and you don’t need to display all options all the time.

If necessary, include a Custom option in a pop-up button’s menu to provide additional items that are useful in some situations.

Platform considerations

iPadOS

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.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/pop-up-buttons

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Pull-down buttons

Best practices

Use a pull-down button to present commands or items that are directly related to the button’s action.

• 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.

Avoid putting all of a view’s actions in one pull-down button.

Balance menu length with ease of use.

Display a succinct menu title only if it adds meaning.

Let people know when a pull-down button’s menu item is destructive, and ask them to confirm their intent.

Include an interface icon with a menu item when it provides value.

Platform considerations

iOS, iPadOS

Consider using a More pull-down button to present items that don’t need prominent positions in the main interface.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/pull-down-buttons

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/the-menu-bar.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

The menu bar

Anatomy

• _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

Best practices

Support the default system-defined menus and their ordering.

Always show the same set of menu items.

Represent menu item actions with familiar icons.

Support the keyboard shortcuts defined for the standard menu items you include.

Prefer short, one-word menu titles.

App menu

Display the About menu item first.

Edit menu

Determine whether Find menu items belong in the Edit menu.

View menu

Provide a View menu even if your app supports only a subset of the standard view functions.

Ensure that each show/hide item title reflects the current state of the corresponding view.

App-specific menus

Provide app-specific menus for custom commands.

As much as possible, reflect your app’s hierarchy in app-specific menus.

Aim to list app-specific menus in order from most to least general or commonly used.

Window menu

Provide a Window menu even if your app has only one window.

Consider including menu items for showing and hiding panels.

Dynamic menu items

Avoid making a dynamic menu item the only way to accomplish a task.

Use dynamic menu items primarily in menu bar menus.

Require only a single modifier key to reveal a dynamic menu item.

Platform considerations

iPadOS

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.

Reserve the YourAppName > Settings menu item for opening your app’s page in iPadOS Settings.

For apps with tab-style navigation, consider adding each tab as a menu item in the View menu.

Consider grouping menu items into submenus to conserve vertical space.

macOS

Menu bar extras

Consider using a symbol to represent your menu bar extra.

Display a menu — not a popover — when people click your menu bar extra.

Let people — not your app — decide whether to put your menu bar extra in the menu bar.

Avoid relying on the presence of menu bar extras.

Consider exposing app-specific functionality in other ways, too.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/the-menu-bar

<!-- hig-doctor:attribution -->

Source: Apple Inc. Canonical content at https://developer.apple.com/design/human-interface-guidelines/toolbars.

This file is a structured index of that content, snapshot 2025-02-02.

Apple HIG text and imagery are © Apple Inc.; this repository provides organization and cross-referencing for AI agent consumption only.

Toolbars

• The title of the current view

• Navigation controls, like back and forward, and search fields

• Actions, or bar items, like buttons and menus

Best practices

Choose items deliberately to avoid overcrowding.

Add a More menu to contain additional actions.

• Standard
• Compact

In iPadOS and macOS apps, consider letting people customize the toolbar to include their most common items.

Reduce the use of toolbar backgrounds and tinted controls.

Avoid applying a similar color to toolbar item labels and content layer backgrounds.

Prefer using standard components in a toolbar.

Consider temporarily hiding toolbars for a distraction-free experience.

Titles

Provide a useful title for each window.

Don’t title windows with your app name.

Write a concise title.

Navigation

Use the standard Back and Close buttons.

Actions

Provide actions that support the main tasks people perform.

Make sure the meaning of each control is clear.

Prefer system-provided symbols without borders.

Use the`.prominent` style for key actions such as Done or Submit.

Item groupings

• 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.

Group toolbar items logically by function and frequency of use.

Group navigation controls and critical actions like Done, Close, or Save in dedicated, familiar, and visually distinct sections.

Keep consistent groupings and placement across platforms.

Minimize the number of groups.

Keep actions with text labels separate.

Platform considerations

iOS

Prioritize only the most important items for inclusion in the main toolbar area.

Use a large title to help people stay oriented as they navigate and scroll.

iPadOS

Consider combining a toolbar with a tab bar.

macOS

Make every toolbar item available as a command in the menu bar.

visionOS

Prefer using a system-provided toolbar.

Avoid creating a vertical toolbar.

Try to prevent windows from resizing below the width of the toolbar.

If your app can enter a modal state, consider offering contextually relevant toolbar controls.

Avoid using a pull-down menu in a toolbar.

watchOS

Use a scrolling toolbar button for an important action that isn’t a primary app function.

---

<!-- hig-doctor:canonical-footer --> For the complete guidance, including worked examples and illustrations, see the canonical page: https://developer.apple.com/design/human-interface-guidelines/toolbars