1# macOS Views & Components Reference
2 
3> macOS-specific SwiftUI views, file operations, drag & drop, and AppKit interop. Covers `HSplitView`, `VSplitView`, `Table`, `PasteButton`, file dialogs, cross-app drag & drop, and `NSViewRepresentable`.
4 
5## Table of Contents
6 
7- [Quick Lookup Table](#quick-lookup-table)
8- [HSplitView & VSplitView (macOS-only)](#hsplitview--vsplitview-macos-only)
9- [Table](#table)
10- [PasteButton & CopyButton](#pastebutton--copybutton)
11- [File Operations](#file-operations)
12- [Drag, Drop & Pasteboard](#drag-drop--pasteboard)
13- [AppKit Interop](#appkit-interop)
14- [Best Practices](#best-practices)
15 
16---
17 
18## Quick Lookup Table
19 
20### Views
21 
22| API | Availability | macOS-Only? | Usage |
23|-----|-------------|:-----------:|-------|
24| `HSplitView` | macOS 10.15+ | Yes | Horizontal resizable split layout with user-draggable dividers |
25| `VSplitView` | macOS 10.15+ | Yes | Vertical resizable split layout with user-draggable dividers |
26| `Table` | macOS 12.0+ | No | Full multi-column layout with sorting; on iOS compact, columns collapse |
27| `PasteButton` | macOS 10.15+ | No | System button that reads clipboard; does NOT auto-validate on macOS |
28| `CopyButton` | macOS 15.0+ | Yes | System button that copies `Transferable` content to clipboard |
29 
30### File Operations
31 
32| API | Availability | macOS-Only? | Usage |
33|-----|-------------|:-----------:|-------|
34| `fileImporter()` | macOS 11.0+ | No | Native NSOpenPanel with column/list/gallery view, sidebar, tags, QuickLook |
35| `fileExporter()` | macOS 11.0+ | No | Native NSSavePanel with format dropdown, tags field |
36| `fileMover()` | macOS 11.0+ | No | Native macOS move panel with Finder-like navigation |
37| `fileDialogMessage(_:)` | macOS 13.0+ | Yes | Custom message text in file dialogs |
38| `fileDialogConfirmationLabel(_:)` | macOS 13.0+ | Yes | Custom confirm button text in file dialogs |
39| `fileExporterFilenameLabel(_:)` | macOS 13.0+ | Yes | Custom filename field label in file exporter |
40 
41### Drag, Drop & Pasteboard
42 
43| API | Availability | macOS-Only? | Usage |
44|-----|-------------|:-----------:|-------|
45| `onDrag(_:)` / `draggable(_:)` | macOS 11.0+ | No | Drag image follows cursor; items draggable between apps |
46| `onDrop(of:delegate:)` / `dropDestination(for:action:)` | macOS 11.0+ | No | Accepts drops from any macOS app including Finder |
47 
48### AppKit Interop
49 
50| API | Availability | macOS-Only? | Usage |
51|-----|-------------|:-----------:|-------|
52| `NSViewRepresentable` | macOS 10.15+ | Yes | Wrap an AppKit `NSView` in SwiftUI |
53| `NSViewControllerRepresentable` | macOS 10.15+ | Yes | Wrap an AppKit `NSViewController` in SwiftUI |
54| `NSHostingController` | macOS 10.15+ | Yes | Host SwiftUI inside an AppKit view controller |
55| `NSHostingView` | macOS 10.15+ | Yes | Host SwiftUI inside an AppKit `NSView` hierarchy |
56 
57---
58 
59## HSplitView & VSplitView (macOS-only)
60 
61Resizable split layouts with user-draggable dividers. Use for IDE-style panes where all panels are equal peers. `VSplitView` works identically but splits vertically (use `minHeight` instead).
62 
63```swift
64HSplitView {
65    FileTreeView()
66        .frame(minWidth: 200)
67    CodeEditorView()
68        .frame(minWidth: 400)
69    PreviewPane()
70        .frame(minWidth: 200)
71}
72```
73 
74> **When to use which:**
75> - **`NavigationSplitView`** — sidebar-based navigation (sidebar drives content/detail)
76> - **`HSplitView`/`VSplitView`** — IDE-style layouts where all panes are equal peers
77 
78---
79 
80## Table
81 
82For `Table` basics (creation, selection, sorting, adaptive compact layout), see `list-patterns.md`. This section covers macOS-specific table styling.
83 
84### Table styles
85 
86```swift
87// Bordered with visible grid lines (macOS-only)
88Table(people) { /* columns */ }
89    .tableStyle(.bordered)
90 
91// Bordered with alternating row backgrounds
92Table(people) { /* columns */ }
93    .tableStyle(.bordered(alternatesRowBackgrounds: true))
94 
95// Inset (no borders)
96Table(people) { /* columns */ }
97    .tableStyle(.inset)
98 
99// Hide column headers
100Table(people) { /* columns */ }
101    .tableColumnHeaders(.hidden)
102```
103 
104---
105 
106## PasteButton & CopyButton
107 
108### PasteButton
109 
110System button that reads clipboard content via `Transferable`. On macOS, it does NOT auto-validate pasteboard changes (unlike iOS).
111 
112```swift
113struct ClipboardView: View {
114    @State private var pastedText = ""
115 
116    var body: some View {
117        HStack {
118            PasteButton(payloadType: String.self) { strings in
119                pastedText = strings[0]
120            }
121            Divider()
122            Text(pastedText)
123            Spacer()
124        }
125    }
126}
127```
128 
129### CopyButton (macOS 15.0+, macOS-only)
130 
131System button that copies `Transferable` content to the clipboard.
132 
133```swift
134struct CopyableContent: View {
135    let shareableText = "Hello, world!"
136 
137    var body: some View {
138        HStack {
139            Text(shareableText)
140            CopyButton(item: shareableText)
141        }
142    }
143}
144```
145 
146---
147 
148## File Operations
149 
150### fileImporter
151 
152On macOS, presents a native `NSOpenPanel` with column/list/gallery view, sidebar favorites, tags, and QuickLook.
153 
154```swift
155.fileImporter(
156    isPresented: $showImporter,
157    allowedContentTypes: [.pdf],
158    allowsMultipleSelection: false
159) { result in
160    if case .success(let urls) = result, let url = urls.first {
161        guard url.startAccessingSecurityScopedResource() else { return }
162        defer { url.stopAccessingSecurityScopedResource() }
163        // use url
164    }
165}
166```
167 
168> **Important:** Always call `startAccessingSecurityScopedResource()` on returned URLs, and `stopAccessingSecurityScopedResource()` when done. These are security-scoped bookmarks — access fails without this.
169 
170### fileExporter
171 
172On macOS, presents a native `NSSavePanel` with format dropdown and tags.
173 
174```swift
175.fileExporter(
176    isPresented: $showExporter,
177    document: document,
178    contentType: .plainText,
179    defaultFilename: "MyFile.txt"
180) { result in
181    // handle Result<URL, Error>
182}
183```
184 
185### File dialog customization (macOS-only)
186 
187Customize text in file dialogs with these macOS-specific modifiers:
188 
189```swift
190// Custom message and confirm button on file importer
191.fileImporter(
192    isPresented: $showImporter,
193    allowedContentTypes: [.image]
194) { result in
195    // handle result
196}
197.fileDialogMessage("Select an image to use as your profile photo")
198.fileDialogConfirmationLabel("Use This Photo")
199 
200// Custom filename label on file exporter
201.fileExporter(
202    isPresented: $showExporter,
203    document: myDocument,
204    contentType: .png
205) { result in
206    // handle result
207}
208.fileExporterFilenameLabel("Export As:")
209```
210 
211---
212 
213## Drag, Drop & Pasteboard
214 
215On macOS, drag and drop works **across applications** (e.g., drag from your app to Finder, Mail, or other apps).
216 
217### Modern approach (Transferable)
218 
219```swift
220// Drag source
221struct DraggableCard: View {
222    let item: MyItem
223 
224    var body: some View {
225        Text(item.title)
226            .draggable(item)  // Requires Transferable conformance
227    }
228}
229 
230// Drop target
231struct DropZone: View {
232    @State private var droppedItems: [MyItem] = []
233 
234    var body: some View {
235        VStack {
236            ForEach(droppedItems) { item in
237                Text(item.title)
238            }
239        }
240        .dropDestination(for: MyItem.self) { items, location in
241            droppedItems.append(contentsOf: items)
242            return true
243        }
244        .frame(width: 300, height: 200)
245        .border(.secondary)
246    }
247}
248```
249 
250### Legacy approach (NSItemProvider)
251 
252```swift
253// Drag source
254Image(systemName: "doc")
255    .onDrag {
256        NSItemProvider(object: fileURL as NSURL)
257    }
258 
259// Drop target
260Text("Drop files here")
261    .onDrop(of: [.fileURL], isTargeted: nil) { providers in
262        // handle providers
263        return true
264    }
265```
266 
267---
268 
269## AppKit Interop
270 
271### NSViewRepresentable (macOS-only)
272 
273Wraps an AppKit `NSView` for use in SwiftUI. Implement `makeNSView(context:)` and `updateNSView(_:context:)`.
274 
275```swift
276struct WebView: NSViewRepresentable {
277    let url: URL
278    func makeNSView(context: Context) -> WKWebView { WKWebView() }
279    func updateNSView(_ nsView: WKWebView, context: Context) {
280        nsView.load(URLRequest(url: url))
281    }
282}
283```
284 
285### NSViewRepresentable with Coordinator
286 
287Use a Coordinator to forward delegate/target-action callbacks to SwiftUI.
288 
289```swift
290struct SearchField: NSViewRepresentable {
291    @Binding var text: String
292 
293    func makeNSView(context: Context) -> NSSearchField {
294        let field = NSSearchField()
295        field.delegate = context.coordinator
296        return field
297    }
298    func updateNSView(_ nsView: NSSearchField, context: Context) {
299        nsView.stringValue = text
300    }
301    func makeCoordinator() -> Coordinator { Coordinator(text: $text) }
302 
303    class Coordinator: NSObject, NSSearchFieldDelegate {
304        var text: Binding<String>
305        init(text: Binding<String>) { self.text = text }
306        func controlTextDidChange(_ obj: Notification) {
307            if let field = obj.object as? NSSearchField {
308                text.wrappedValue = field.stringValue
309            }
310        }
311    }
312}
313```
314 
315> **Warning:** Never set `frame`/`bounds` directly on the managed `NSView` — SwiftUI owns the layout.
316 
317### NSViewControllerRepresentable (macOS-only)
318 
319Wraps an AppKit `NSViewController` for use in SwiftUI.
320 
321```swift
322struct MapViewWrapper: NSViewControllerRepresentable {
323    func makeNSViewController(context: Context) -> MapViewController {
324        MapViewController()
325    }
326 
327    func updateNSViewController(_ nsViewController: MapViewController, context: Context) {
328        // Update the controller when SwiftUI state changes
329    }
330}
331```
332 
333### NSHostingController & NSHostingView (macOS-only)
334 
335Host SwiftUI content inside AppKit (reverse direction — AppKit app embedding SwiftUI views).
336 
337```swift
338// Host SwiftUI as a view controller
339let hostingController = NSHostingController(rootView: MySwiftUIView())
340window.contentViewController = hostingController
341 
342// Host SwiftUI directly as an NSView
343let hostingView = NSHostingView(rootView: MySwiftUIView())
344someNSView.addSubview(hostingView)
345```
346 
347---
348 
349## Best Practices
350 
351- **Use `NavigationSplitView`** for sidebar-driven navigation — reserve `HSplitView`/`VSplitView` for IDE-style equal peer panes
352- **Make `Table` adaptive** — handle compact size classes by showing combined info in the first column
353- **Always call `startAccessingSecurityScopedResource()`** on URLs from `fileImporter` — they are security-scoped
354- **Use `Transferable`** for drag & drop (modern) — fall back to `NSItemProvider` only for legacy compatibility
355- **Use `NSViewRepresentable` with Coordinator** when you need delegate callbacks from AppKit views
356- **Never set `frame`/`bounds`** directly on views managed by `NSViewRepresentable` — SwiftUI owns the layout
357- **Prefer native SwiftUI** over AppKit interop when possible — only use `NSViewRepresentable` for features SwiftUI doesn't provide
358