Las imágenes de los elementos de menú desaparecen en macOS 27 y iPadOS 27

Un elemento de menú con imagen y sin título no se ve en absoluto en macOS 27 si enlazas contra el SDK de macOS 27. Apple protege ese caso en los SDK anteriores: muestra la imagen automáticamente cuando el título y el título con atributos del elemento están ambos vacíos.¹ Recompila contra 27 y esa protección deja de aplicarse.

macOS 27 y iPadOS 27 ocultan por defecto la mayoría de las imágenes de los elementos de menú, y lo que se esfuma depende del SDK contra el que enlazaste. Apple describe el resultado como “similar al comportamiento anterior a macOS 26.0”, o sea: macOS 26 añadió imágenes de menú de forma generalizada y 27 se lleva de vuelta la mayoría.¹

Hay tres frameworks afectados y cada uno tiene una forma distinta de excluirse. Si llegaste aquí buscando preferredImageVisibility y escribes SwiftUI, esa propiedad no existe para ti.

TL;DR

macOS 27 oculta por defecto las imágenes de símbolo de los elementos de menú en las apps enlazadas contra macOS 26.0 o posterior; las apps enlazadas contra el SDK de macOS 27 pierden además las imágenes que no son símbolos.¹² Los elementos de menú compuestos solo por un ícono están protegidos automáticamente en los SDK anteriores a 27 y pierden esa protección al recompilar contra 27.³ iPadOS 27 oculta por defecto las imágenes asignadas a los elementos de menú.⁴ AppKit y UIKit exponen preferredImageVisibility con .automatic, .visible y .hidden; SwiftUI, en cambio, usa labelStyle(.titleAndIcon).⁵ Ajustes (Settings), Compartir (Share) e Imprimir (Print) conservan su imagen en todo el sistema, así que verás algunos íconos y podrías concluir que los tuyos están rotos.

Qué cambia realmente, según el SDK

El comportamiento de AppKit llegó repartido en tres entradas distintas de las notas de la versión, dos de ellas registradas como correcciones, y por eso los resúmenes que circulan sobre este cambio se contradicen entre sí.

La entrada base indica que NSMenu oculta por defecto todas las imágenes de símbolo de los elementos de menú, mientras que las que no son símbolos siguen visibles, y que el cambio se aplica a las aplicaciones enlazadas contra macOS 26.0 o posterior.¹

Una segunda entrada extiende el ocultamiento: “Para las aplicaciones enlazadas contra el SDK de macOS 27, tanto las imágenes de símbolo como las que no lo son se ocultan ahora automáticamente. Para las aplicaciones enlazadas contra SDK anteriores, las imágenes que no son símbolos siguen visibles de forma automática, lo que preserva la compatibilidad con el comportamiento existente de la aplicación”.²

La tercera entrada es la que conviene leer dos veces:³

“Para las aplicaciones enlazadas contra SDK anteriores a macOS 27, NSMenu ahora muestra automáticamente las imágenes de los elementos de menú si el título y el título con atributos del elemento están ambos vacíos. Esto preserva el comportamiento existente de la aplicación cuando la imagen es la única representación del contenido del elemento. Al enlazar contra el SDK de macOS 27, esas imágenes se ocultarán automáticamente; un menú con este diseño debería usar la API preferredImageVisibility para asegurar que las imágenes de los elementos sigan visibles.”

Apple construyó una red de seguridad para los elementos de menú que solo tienen ícono y luego documentó que esa red no llega al nuevo SDK. Un elemento cuyo contenido completo es una imagen se dibuja vacío después de recompilar. Nada cambia en tu código fuente. El detonante es el SDK contra el que compilaste.

Los elementos de menú con solo ícono son menos exóticos de lo que suenan. Las muestras de color de un menú de formato, donde la muestra es la opción. Los selectores de dispositivo o de cuenta que identifican cada entrada con un avatar o un glifo de estado. Las filas de reacciones y emoji construidas como una tira horizontal de elementos que son pura imagen. Las listas de documentos recientes que muestran el ícono del tipo de archivo con el nombre dibujado aparte. En todos los casos, la imagen no es un adorno pegado a una etiqueta: es la etiqueta.

Esos menús quedan reducidos a una columna de filas vacías que siguen respondiendo a los clics. El menú conserva su altura, sus separadores y sus zonas de clic, así que a ojos de una prueba automatizada no parece un fallo de renderizado. Una prueba de UI que verifica que el menú tiene seis elementos sigue pasando. Una comparación de capturas de pantalla lo detecta; una aserción sobre el número de elementos, no.

El silencio es el aire de familia. macOS 27 también deniega el acceso a contenedores de otro equipo sin preguntar: ahí la API devuelve una URL de aspecto válido y el fallo espera hasta la lectura. Los dos cambios sustituyen una señal visible por silencio, y los dos afloran disfrazados de otra cosa.

Tres frameworks, tres soluciones

AppKit y UIKit comparten la forma. Ambas propiedades reciben un enum ImageVisibility con .automatic, .visible y .hidden, ambos RawRepresentable sobre NSInteger y ambos 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 toma otro camino. Su nota de la versión dice que hay que “usar el modificador de vista labelStyle(_:) con el estilo .titleAndIcon para indicar que el ícono del Label de un elemento de menú siempre debe mostrarse”.⁵

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

Ten en cuenta, además, que el comportamiento por defecto de SwiftUI coincide con la línea base de AppKit y no con el del SDK de 27: imágenes de símbolo ocultas, imágenes que no son símbolos todavía visibles.⁵ La tabla de enlazado por SDK de más arriba describe AppKit. No asumas que se traslada.

El alcance es más estrecho de lo que parece

Conviene leer con cuidado la redacción sobre plataformas, porque las entradas no dicen lo mismo.

La entrada de UIKit cubre “la barra de menús y los menús contextuales” en iPadOS 27.0 y macOS 27.0.⁴ La de SwiftUI es más específica: la barra de menús en iPadOS 27.0 y macOS 27.0, “además de los menús contextuales en macOS 27.0”.⁵ Los menús contextuales de SwiftUI en iPadOS no se mencionan.

UIMenuElement.preferredImageVisibility está disponible en iOS, iPadOS, Mac Catalyst, tvOS y visionOS 27.0.⁷ Que la API exista en una plataforma no significa que ahí esté activo el ocultamiento. Las notas de la versión de Apple describen el comportamiento para iPadOS y macOS. Trata tvOS y visionOS como casos no documentados, no como confirmados.

La superficie de Interface Builder

Un detalle no tiene equivalente en código. Para los elementos de menú creados desde un archivo xib, NSMenu respeta una casilla “macOS 26.0 only” en el inspector del elemento: sin marcar mantiene la imagen visible, marcada la oculta.¹

Una propiedad de Interface Builder cambia ahora la visibilidad de las imágenes en tiempo de ejecución. Si tus menús vienen de xibs, la auditoría no es una búsqueda en el código: alguien tiene que abrir el inspector.

Por qué sobreviven algunos íconos

Tanto AppKit como UIKit siguen proporcionando imágenes visibles por defecto para elementos de menú comunes en todo el sistema, como Ajustes, Compartir e Imprimir.¹⁴ SwiftUI hace lo mismo.⁵

El efecto práctico es confusión al diagnosticar. Actualizas, abres un menú y ves íconos junto a Ajustes y Compartir, pero no junto a tus propios elementos. La conclusión razonable es que tus imágenes no cargaron, o que se rompió el asset catalog, o que los nombres de los símbolos están mal. Nada de eso está pasando: el sistema aplica una política que exime a un puñado de elementos muy conocidos.

Cómo decidir qué íconos conservar

Las cinco entradas de las notas de la versión piden a los desarrolladores revisar las Human Interface Guidelines actualizadas para decidir qué elementos de menú deberían seguir mostrando imagen.¹⁴⁵ No pude verificar qué dice esa guía: la página de menús de las HIG se renderiza del lado del cliente y casi no devuelve texto a un rastreador, y no existe un endpoint JSON para el contenido de las HIG como sí lo hay para la referencia de la API. Revísala tú mismo en lugar de fiarte de la palabra de un resumen, incluido este.

La única heurística concreta que aparece en las propias notas viene de la entrada de SwiftUI, que sugiere mostrar el ícono cuando un elemento de menú “representa un objeto o un concepto en lugar de una acción”.⁵

Esa regla sirve. Un menú que lista documentos abiertos, dispositivos disponibles o filtros guardados está nombrando objetos, y ahí el ícono aporta identidad. Un menú de verbos, que es la mayoría de los menús, no gana gran cosa con un ícono junto a cada entrada. Todo indica que Apple concluyó que macOS 26 aplicó imágenes en exceso y que 27 es la corrección.

Qué hacer antes de publicar con el SDK de 27

Localiza primero tus elementos de menú con solo ícono. Son los que se rompen peor, porque la imagen es todo el contenido. Cualquier NSMenuItem con imagen y título vacío, y cualquier elemento de UIMenu construido igual, necesita .visible de forma explícita.

Decide elemento por elemento, no de forma global. Poner .visible en todas partes revierte un cambio deliberado de la plataforma y te devuelve al punto donde estaba macOS 26. La regla de objeto frente a acción filtra mejor que una anulación general.

Revisa los xibs por separado. La casilla “macOS 26.0 only” no se puede buscar con grep como una asignación de propiedad, y cambia el comportamiento.

Prueba con las dos generaciones de SDK si das soporte a ambas. Una compilación contra 26 y otra contra 27 se dibujan distinto a partir del mismo código. Eso hace que tus capturas y tus pruebas de UI dependan del SDK, algo que antes no ocurría.

Que el enlazado con el SDK decida el comportamiento se está volviendo un patrón recurrente en esta versión. La obsolescencia de canOpenURL en iOS 27 gira sobre el mismo eje, y la lección práctica se repite: lo que ven los usuarios lo determina tu elección en tiempo de compilación, no tu código.

Cuenta con que las notas de la versión cambien. Dos de las tres entradas de AppKit están registradas como correcciones, lo que significa que el comportamiento ya cambió una vez durante el ciclo beta. Volví a verificar las cinco entradas contra las notas de la Beta 4 el 1 de agosto de 2026 y dicen lo que se cita aquí. Confirma contra las notas vigentes antes de actuar sobre cualquiera de estos puntos.

Cómo auditar una base de código existente

El cambio es lo bastante mecánico como para auditarlo de forma sistemática, y conviene hacerlo antes de recompilar y no después de que alguien de pruebas reporte un menú en blanco.

Empieza por el caso más grave. Un NSMenuItem que lleva imagen con el título vacío es el único fallo que produce un menú visiblemente roto en lugar de uno más sobrio. En el código, busca asignaciones de imagen sin el título correspondiente:

# 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'

Ninguno de los dos patrones es exhaustivo, porque el título puede asignarse tres líneas más abajo o leerse de una tabla de localización. Toma los resultados como una lista de candidatos que hay que inspeccionar, no como un hallazgo.

Después, los xibs. Ningún grep ayuda con la casilla “macOS 26.0 only”, que vive en el inspector del elemento de menú y no en un atributo que tu compilación pueda ver. Si tus menús vienen de Interface Builder, auditar significa abrir cada menú y revisar cada elemento.

Después, los constructores de menús de UIKit. UIMenu, UIAction, UICommand y UIKeyCommand recibieron inicializadores actualizados que aceptan preferredImageVisibility, así que la corrección puede ir en la construcción y no como una asignación posterior.⁴

Después, el uso de Label de SwiftUI dentro de menús. Son los más fáciles de pasar por alto, porque en el código un Label dentro de un menú se ve idéntico a un Label en cualquier otro sitio. El modificador va en la etiqueta, y solo donde quieras conservar el ícono.

Compila dos veces y compara. La comprobación más confiable no pasa por leer código. Compila contra el SDK de 26 y contra el de 27, abre los mismos menús y captura ambos. Que el mismo código produzca dos menús distintos es justamente el sentido de este cambio, y una comparación lado a lado encuentra lo que ningún grep va a encontrar.

Ese último paso también protege tus capturas. Las imágenes de marketing, la documentación y los recursos de la App Store donde aparecen menús se tomaron con el SDK que estuviera vigente en ese momento. Si muestran íconos que tu compilación de producción ya no dibuja, ahora están equivocadas, y nada en tu proceso de compilación lo va a señalar.

Conclusiones clave

Para desarrolladores de AppKit: - Enlazar contra el SDK de macOS 27 también oculta las imágenes que no son símbolos, no solo los símbolos. Auditar únicamente tus SF Symbols deja fuera la mitad del problema. - Los elementos de menú con solo ícono pierden su protección automática con el SDK de 27 y se dibujan vacíos. Ponles preferredImageVisibility = .visible uno por uno. - Los menús definidos en xibs llevan una casilla “macOS 26.0 only” que cambia la visibilidad fuera de cualquier ruta de código.

Para desarrolladores de UIKit: - preferredImageVisibility está en UIMenuElement y en los inicializadores actualizados de UIMenu, UIAction, UICommand y UIKeyCommand. - La propiedad existe en tvOS y visionOS, pero Apple documenta el comportamiento para iPadOS y macOS. Verifica antes de asumir.

Para desarrolladores de SwiftUI: - preferredImageVisibility no es tu API. Usa labelStyle(.titleAndIcon) en el Label. - El comportamiento por defecto de SwiftUI oculta las imágenes de símbolo y conserva las que no lo son, lo que coincide con la línea base de AppKit y no con el comportamiento del SDK de 27.

Preguntas frecuentes

¿Por qué Ajustes y Compartir siguen mostrando íconos?

El sistema exime a ciertos elementos de menú comunes. AppKit, UIKit y SwiftUI siguen proporcionando imágenes visibles por defecto para elementos como Ajustes, Compartir e Imprimir.¹⁴⁵ Ver esos íconos mientras los tuyos están ocultos es el comportamiento esperado, no un fallo de carga.

¿Quedarse en un SDK anterior evita esto?

En parte, y la diferencia importa. Las apps enlazadas contra macOS 26.0 o posterior ya ocultan las imágenes de símbolo.¹ Quedarte por debajo del SDK de macOS 27 conserva la visibilidad de las imágenes que no son símbolos y mantiene la protección automática de los elementos con solo ícono.²³ Lo que no hace es devolverte las imágenes de símbolo.

¿Qué pasa con un elemento de menú que solo tiene imagen y no título?

En los SDK anteriores a macOS 27, NSMenu muestra la imagen automáticamente porque el título y el título con atributos están ambos vacíos.³ Con el SDK de macOS 27 esa protección no se aplica y la imagen queda oculta, lo que deja un elemento de menú sin contenido visible. Ponle preferredImageVisibility = .visible.

¿Es igual en tvOS y visionOS?

UIMenuElement.preferredImageVisibility está disponible en ambos a partir de 27.0.⁷ Las entradas de las notas de la versión describen el ocultamiento para iPadOS y macOS. Que la API exista en una plataforma no confirma que el comportamiento esté activo ahí.

¿Qué íconos debería conservar?

Las notas de la versión remiten a las Human Interface Guidelines, que no pude leer directamente. La heurística que Apple enuncia en la entrada de SwiftUI es mostrar un ícono cuando el elemento de menú “representa un objeto o un concepto en lugar de una acción”.⁵

Fuentes