Menu Item Images Disappear in macOS 27 and iPadOS 27

A menu item with an image and no title renders as nothing in macOS 27 if you link against the macOS 27 SDK. Apple protects that case on earlier SDKs, automatically showing the image when a menu item’s title and attributed title are both empty.¹ Rebuild against 27 and the protection stops applying.

macOS 27 and iPadOS 27 hide most menu item images by default, and what vanishes depends on which SDK you linked against. Apple describes the result as “similar to the behavior prior to macOS 26.0,” which is to say macOS 26 added menu images broadly and 27 takes most of them back.¹

Three frameworks are affected and each has a different opt-out. If you searched for preferredImageVisibility and write SwiftUI, that property does not exist for you.

TL;DR

macOS 27 hides menu item symbol images by default for apps linked on macOS 26.0 and later; apps linked on the macOS 27 SDK also lose non-symbol images.¹² Icon-only menu items are automatically protected on pre-27 SDKs and lose that protection on a 27 rebuild.³ iPadOS 27 hides images set on menu elements by default.⁴ AppKit and UIKit expose preferredImageVisibility with .automatic, .visible, and .hidden; SwiftUI uses labelStyle(.titleAndIcon) instead.⁵ Settings, Share, and Print keep their images system-wide, so you will see some icons and may conclude yours are broken.

What Actually Changes, by SDK

The AppKit behavior arrived in three separate release-note entries, two of them filed as fixes, which is why summaries of this change disagree with each other.

The baseline entry states that NSMenu hides all menu item symbol images by default while non-symbol images remain visible, and that the change applies to applications linked on macOS 26.0 and later.¹

A second entry extends the hiding: “For applications linked on the macOS 27 SDK, both symbol and non-symbol menu item images are now automatically hidden. For applications linked on earlier SDKs, non-symbol images remain automatically visible, preserving compatibility with existing application behavior.”²

The third entry is the one worth reading twice:³

“For applications linked on SDKs prior to macOS 27, NSMenu now automatically shows menu item images if the menu item title and attributed title are both empty. This preserves existing application behavior when the image is the only representation of the menu item content. When linking against the macOS 27 SDK, these images will automatically be hidden; a menu with this design should use the preferredImageVisibility API to ensure that the menu item images remain visible.”

Apple built a safety net for icon-only menu items, then documented that the net does not extend to the new SDK. A menu item whose entire content is an image renders empty after a rebuild. Nothing in your source changes. The trigger is the SDK you compiled against.

Icon-only menu items are less exotic than they sound. Color swatches in a formatting menu, where the swatch is the choice. Device or account pickers that identify each entry by avatar or status glyph. Reaction and emoji rows built as a horizontal strip of image-only items. Recent-documents lists that show file-type icons with the name rendered separately. In each case the image is not decoration attached to a label, it is the label.

Those menus degrade to a column of empty rows that still respond to clicks. The menu keeps its height, its separators, and its hit targets, so it does not read as a rendering failure to the automated eye. A UI test asserting that a menu has six items still passes. A screenshot diff catches it; an assertion on item count does not.

The quietness is the family resemblance. macOS 27 also denies cross-team container access without prompting, where the API hands back a valid-looking URL and the failure waits for the read. Both changes replace a visible signal with silence, and both surface as something other than what they are.

Three Frameworks, Three Fixes

AppKit and UIKit share the shape. Both properties take an ImageVisibility enum with .automatic, .visible, and .hidden, both RawRepresentable over NSInteger, both Sendable.⁶⁷

// AppKit
menuItem.preferredImageVisibility = .visible

// UIKit — also available on the updated initializers
// for UIMenu, UIAction, UICommand, and UIKeyCommand
let action = UIAction(title: "Export", image: exportImage) { _ in export() }
action.preferredImageVisibility = .visible

SwiftUI takes a different route. Its release note says to “use the labelStyle(_:) view modifier with the .titleAndIcon style to indicate that a menu item Label’s icon should always be shown.”⁵

Menu("File") {
    Button {
        openDocument()
    } label: {
        Label("Open Document", systemImage: "doc")
    }
    .labelStyle(.titleAndIcon)
}

Note also that SwiftUI’s default matches the AppKit baseline rather than the 27-SDK behavior: symbol images hidden, non-symbol images still visible.⁵ The SDK-linkage table above describes AppKit. Do not assume it transfers.

The Scope Is Narrower Than It Sounds

Read the platform wording carefully, because the entries differ.

The UIKit entry covers “the menu bar and context menus” on iPadOS 27.0 and macOS 27.0.⁴ The SwiftUI entry is more specific: the menu bar on iPadOS 27.0 and macOS 27.0, “as well as context menus on macOS 27.0.”⁵ SwiftUI context menus on iPadOS are not named.

UIMenuElement.preferredImageVisibility is available on iOS, iPadOS, Mac Catalyst, tvOS, and visionOS 27.0.⁷ The API shipping on a platform does not mean the hiding behavior is active there. Apple’s release notes describe the behavior for iPadOS and macOS. Treat tvOS and visionOS as unstated rather than confirmed.

The Interface Builder Surface

One detail has no code equivalent. For menu items created from a xib file, NSMenu observes a “macOS 26.0 only” checkbox in the menu item inspector: unchecked keeps the image visible, checked hides it.¹

A property in Interface Builder now changes runtime image visibility. If your menus come from xibs, the audit is not a code search. Someone has to open the inspector.

Why Some Icons Survive

Both AppKit and UIKit continue to provide default visible images for common system-wide menu items such as Settings, Share, and Print.¹⁴ SwiftUI does the same.⁵

The practical effect is diagnostic confusion. You update, open a menu, and see icons next to Settings and Share but not next to your own items. The reasonable conclusion is that your images failed to load, or your asset catalog broke, or the symbol names are wrong. None of that is happening. The system is applying a policy that exempts a handful of well-known items.

Deciding Which Icons to Keep

All five release-note entries tell developers to review the updated Human Interface Guidelines to decide which menu items should still display images.¹⁴⁵ I could not verify what that guidance says: the HIG menus page renders client-side and returns almost no text to a fetcher, and there is no JSON endpoint for HIG content the way there is for API reference. Check it yourself rather than taking a summary’s word for it, including this one.

The one concrete heuristic in the release notes themselves comes from the SwiftUI entry, which suggests showing the icon when a menu item “represents an object or a concept rather than an action.”⁵

That rule is usable. A menu listing open documents, available devices, or saved filters is naming objects, and an icon carries identity there. A menu of verbs, which is most menus, does not gain much from an icon next to every entry. Apple appears to have concluded that macOS 26 over-applied images, and 27 is the correction.

What to Do Before You Ship on the 27 SDK

Find your icon-only menu items first. They are the ones that break hardest, because the image is the entire content. Any NSMenuItem with an image and an empty title, and any UIMenu element built the same way, needs .visible set explicitly.

Decide per item, not globally. Setting .visible everywhere reverts a deliberate platform change and puts you back where macOS 26 was. The object-versus-action rule is a better filter than a blanket override.

Search the xibs separately. The “macOS 26.0 only” checkbox is not greppable in the same way as a property assignment, and it changes behavior.

Test on both SDK generations if you support them. A build against 26 and a build against 27 render differently from identical source. That makes screenshots and UI tests SDK-dependent in a way they were not before.

SDK linkage deciding behavior is becoming a recurring shape in this release. The iOS 27 canOpenURL deprecation turns on the same axis, and the practical lesson repeats: your compile-time choice, not your source, determines what users see.

Expect the release notes to move. Two of the three AppKit entries are filed as fixes, meaning the behavior already changed once during the beta cycle. I re-verified all five entries against the Beta 4 notes on 2026-08-01 and they read as quoted here. Confirm against current notes before acting on any of it.

Auditing an Existing Codebase

The change is mechanical enough to audit systematically, and worth doing before the rebuild rather than after a tester reports a blank menu.

Start with the highest-severity case. An NSMenuItem carrying an image with an empty title is the only failure that produces a visibly broken menu rather than a plainer one. In code, look for image assignment without a corresponding title:

# Menu items constructed with an image and no title argument
rg 'NSMenuItem\(' --type swift -A3 | rg -B1 'image ='
rg 'setImage|\.image\s*=' --type swift | rg -i 'menu'

Neither pattern is exhaustive, because a title can be set three lines later or read from a localized table. Treat the results as a candidate list to inspect, not a finding.

Then the xibs. No grep helps with the “macOS 26.0 only” checkbox, which lives in the menu item inspector rather than in any attribute your build can see. If your menus come from Interface Builder, the audit means opening each menu and checking each item.

Then the UIKit menu builders. UIMenu, UIAction, UICommand, and UIKeyCommand all gained updated initializers taking preferredImageVisibility, so the fix can go at construction rather than as a follow-up assignment.⁴

Then SwiftUI Label usage inside menus. These are the easiest to overlook, because a Label in a menu looks identical in source to a Label anywhere else. The modifier goes on the label, and only where you want the icon kept.

Build twice and compare. The most reliable check does not involve reading code at all. Build against the 26 SDK and the 27 SDK, open the same menus, and photograph both. Identical source producing two different menus is the whole point of this change, and a side-by-side finds what a grep will not.

That last step also protects your screenshots. Marketing images, documentation, and App Store assets showing menus were captured under whatever SDK was current when someone took them. If they show icons your shipping build no longer renders, they are now wrong, and nothing in your build process will flag it.

Key Takeaways

For AppKit developers: - Linking against the macOS 27 SDK hides non-symbol images too, not just symbols. Auditing only your SF Symbols misses half of it. - Icon-only menu items lose their automatic protection on the 27 SDK and render empty. Set preferredImageVisibility = .visible on each one. - Menus defined in xibs carry a “macOS 26.0 only” checkbox that changes visibility outside of any code path.

For UIKit developers: - preferredImageVisibility is on UIMenuElement and on the updated initializers for UIMenu, UIAction, UICommand, and UIKeyCommand. - The property exists on tvOS and visionOS, but Apple documents the behavior for iPadOS and macOS. Verify before assuming.

For SwiftUI developers: - preferredImageVisibility is not your API. Use labelStyle(.titleAndIcon) on the Label. - SwiftUI’s default hides symbol images and keeps non-symbol images, matching the AppKit baseline rather than the 27-SDK behavior.

FAQ

Why do Settings and Share still show icons?

The system exempts certain common menu items. AppKit, UIKit, and SwiftUI all continue to provide default visible images for items such as Settings, Share, and Print.¹⁴⁵ Seeing those icons while your own are hidden is expected behavior, not a loading failure.

Does staying on an older SDK avoid this?

Partly, and the distinction matters. Apps linked on macOS 26.0 and later already hide symbol images.¹ Staying below the macOS 27 SDK preserves non-symbol image visibility and keeps the automatic protection for icon-only items.²³ It does not restore symbol images.

What happens to a menu item that has only an image and no title?

On SDKs before macOS 27, NSMenu shows the image automatically because the title and attributed title are both empty.³ On the macOS 27 SDK that protection does not apply and the image is hidden, which leaves a menu item with no visible content. Set preferredImageVisibility = .visible.

Is this the same on tvOS and visionOS?

UIMenuElement.preferredImageVisibility is available on both at 27.0.⁷ The release-note entries describe the hiding behavior for iPadOS and macOS. The API existing on a platform is not confirmation that the behavior is active there.

Which icons should I keep?

The release notes point to the Human Interface Guidelines, which I was unable to read directly. The heuristic Apple states in the SwiftUI entry is to show an icon when the menu item “represents an object or a concept rather than an action.”⁵

Sources