macOS AppKit Interoperability
Bridges SwiftUI and AppKit in both directions: NSViewRepresentable and NSViewControllerRepresentable embed AppKit in SwiftUI, and NSHostingController and NSHostingView host SwiftUI in AppKit. Also covers the responder chain, NSToolbar, NSOpenPanel, and drag and drop across the boundary.
When to Use
Use this skill when you're:
- Embedding an AppKit view or view controller inside SwiftUI
- Hosting SwiftUI views inside an AppKit app
- Working around SwiftUI gaps —
NSToolbarcustomization,NSOpenPaneloptions,NSTextViewrich text - Debugging menu commands, copy/paste, or keyboard shortcuts that don't cross the SwiftUI/AppKit boundary
- Bridging drag-and-drop between SwiftUI's
Transferablemodel and AppKit'sNSDraggingDestination - Diagnosing responder chain or focus behavior that breaks when mixing frameworks
- Optimizing SwiftUI cells inside
NSCollectionVieworNSTableViewfor scroll performance - Updating
NSViews automatically from@Observablemodels (observation tracking, no SwiftUI required) - Reusing an existing
NSGestureRecognizerin a SwiftUI view (NSGestureRecognizerRepresentable, macOS 26) - Building main-menu items in SwiftUI (
NSHostingMenu) or adding SwiftUI scenes likeMenuBarExtraandSettingsto an AppKit app delegate (NSHostingSceneRepresentation, macOS 26)
Example Prompts
Questions you can ask your assistant that will draw from this skill:
- "How do I host an
NSTextViewinside SwiftUI and keep bindings synced?" - "My SwiftUI cells inside
NSCollectionViewcause scroll jank. What's wrong?" - "When should I drop from
.fileImportertoNSOpenPanel?" - "My
.onCommandmodifier is silently ignored. What did I miss?" - "Why are my writes from the AppKit delegate not reaching the SwiftUI binding?"
- "Can my NSView redraw automatically when my @Observable model changes?"
- "How do I add a SwiftUI MenuBarExtra to my existing AppKit app?"
What This Skill Provides
Direction Decision
- SwiftUI host + AppKit guest →
NSViewRepresentable(raw view) orNSViewControllerRepresentable(controller with lifecycle) - AppKit host + SwiftUI guest →
NSHostingController(controller contexts) orNSHostingView(raw view contexts) - When to bridge at all — start with SwiftUI; cross only when SwiftUI lacks the capability
NSViewRepresentable Lifecycle
makeCoordinator()→makeNSView(context:)→updateNSView(_:context:)→dismantleNSView(_:coordinator:)- The coordinator pattern for delegate callbacks writing back to bindings
- Refreshing
context.coordinator.parent = selfinupdateNSView; a stale reference silently swallows writes back to SwiftUI state - Guarding redundant property sets, which otherwise reset the text caret and selection while the user types
- Reading
context.environment(for example,isEnabled) and applying it to the AppKit view - Wrapping
NSTextViewin the scroll view fromNSTextView.scrollableTextView() - The never-set-frame rule — SwiftUI owns layout; use
.frame()on the SwiftUI side
NSHostingController vs NSHostingView
NSHostingControllerfor view-controller contexts (NSSplitViewItem, sheets, popovers, modal windows, tabs)NSHostingViewfor raw view contexts (collection cells, sidebars, table cells)sizingOptionson the controller for Auto Layout constraint generation- The reuse rule: create the hosting view once, then update
rootViewon reuse, never a new hosting view per cell
Responder Chain and Focus
- The "they don't live in separate worlds" mental model — SwiftUI views participate in the AppKit responder chain
- SwiftUI command modifiers —
.copyable,.cuttable,.pasteDestination,.onMoveCommand,.onExitCommand,.onCommand(#selector(...)) - The
.focusable()requirement for command receivers - Full Keyboard Navigation testing (System Settings toggle on and off)
Incremental SwiftUI Adoption
- Automatic observation tracking: AppKit redraws an
NSViewwhen@Observableproperties read in its draw or layout methods change; on by default with the 2026 SDKs, and back-deployable to macOS 15 with theNSObservationTrackingEnabledInfo.plist key NSGestureRecognizerRepresentable(macOS 26) for existing gesture recognizers, andNSHostingMenu(macOS 14.4) for SwiftUI-built menusNSHostingSceneRepresentationandaddSceneRepresentationforMenuBarExtraandSettingsscenes in an app-delegate app (macOS 26)
Bridging Other AppKit APIs
NSToolbarfor capabilities.toolbardoesn't cover (item validation, user customization, centered groups)NSOpenPanelfor capabilities.fileImporterdoesn't cover (directories, accessory views, ubiquitous content)- Drag and drop:
Transferablewith.draggableand.dropDestinationwhen SwiftUI can handle it,NSDraggingDestinationon the AppKit view inside a representable, and.onDrop(of:delegate:)for legacy pasteboard types - Shared state via
@Observable(orObservableObject) accessible to both sides
Key Pattern
The most common performance bug is creating a new NSHostingView on every cell reuse instead of updating rootView:
class ShortcutItemView: NSCollectionViewItem {
private var hostingView: NSHostingView<ShortcutView>?
func displayShortcut(_ shortcut: Shortcut) {
let view = ShortcutView(shortcut: shortcut)
if let hostingView {
hostingView.rootView = view // reuse — SwiftUI diffs internally
} else {
let newHosting = NSHostingView(rootView: view)
self.view.addSubview(newHosting)
setupConstraints(for: newHosting)
hostingView = newHosting
}
}
}Documentation Scope
This page documents the appkit-interop skill (in the axiom-macos suite), which your assistant uses when you bridge SwiftUI and AppKit.
Related
- appkit-modernization – Modernizing the AppKit side itself (input, restoration, macOS 27 look)
- swiftui-differences – Drop to AppKit only when these macOS SwiftUI primitives don't cover the need
- windows –
NSHostingControlleris the right way to host SwiftUI inside an AppKit-managed window or sheet - sandbox-and-file-access – Reasons to drop from
.fileImportertoNSOpenPanel - menus-and-commands – Where SwiftUI's command modifiers meet AppKit's responder chain
- uikit-bridging – Same representable pattern, UIKit edition
Resources
WWDC: 2022-10075, 2026-272
Docs: /swiftui/nsviewrepresentable, /swiftui/nsviewcontrollerrepresentable, /swiftui/nshostingcontroller, /swiftui/nshostingview, /swiftui/nshostingmenu, /swiftui/nsgesturerecognizerrepresentable, /swiftui/nshostingscenerepresentation, /appkit/nstoolbar, /appkit/nsopenpanel