1# macOS Scenes Reference
2 
3> SwiftUI scene types for macOS apps — `Settings`, `MenuBarExtra`, `WindowGroup`, `Window`, `UtilityWindow`, and `DocumentGroup`. Covers macOS-only scenes and cross-platform scenes with macOS-specific behavior.
4 
5## Table of Contents
6 
7- [Quick Lookup Table](#quick-lookup-table)
8- [Settings (macOS-only)](#settings-macos-only)
9- [MenuBarExtra (macOS-only)](#menubarextra-macos-only)
10- [WindowGroup (macOS behavior)](#windowgroup-macos-behavior)
11- [Window](#window)
12- [UtilityWindow (macOS-only)](#utilitywindow-macos-only)
13- [DocumentGroup](#documentgroup)
14- [Platform Conditionals](#platform-conditionals)
15- [Best Practices](#best-practices)
16 
17---
18 
19## Quick Lookup Table
20 
21| API | Availability | macOS-Only? | macOS-Specific Behavior |
22|-----|-------------|:-----------:|------------------------|
23| `WindowGroup` | macOS 11.0+ | No | Multiple window instances, tabbed interface, automatic Window menu commands |
24| `Window` | macOS 13.0+ | No | App quits when sole window closes; adds itself to Windows menu |
25| `UtilityWindow` | macOS 15.0+ | Yes | Floating tool palette; receives `FocusedValues` from active main window |
26| `Settings` | macOS 11.0+ | Yes | Presents preferences window (Cmd+,) |
27| `MenuBarExtra` | macOS 13.0+ | Yes | Persistent icon/menu in the system menu bar |
28| `DocumentGroup` | macOS 11.0+ | No | Document-based menu bar commands (File > New/Open/Save); multiple document windows |
29 
30---
31 
32## Settings (macOS-only)
33 
34Presents the app's preferences window, accessible via **Cmd+,** or the app menu. SwiftUI automatically enables the Settings menu item and manages the window lifecycle.
35 
36```swift
37Settings {
38    TabView {
39        Tab("General", systemImage: "gear") { GeneralSettingsView() }
40        Tab("Advanced", systemImage: "star") { AdvancedSettingsView() }
41    }
42    .scenePadding()
43    .frame(maxWidth: 350, minHeight: 100)
44}
45```
46 
47Use `TabView` with `Tab` items for multi-pane preferences. Each tab's content is typically a `Form` with `@AppStorage`-backed controls.
48 
49### SettingsLink (macOS 14.0+)
50 
51A button that opens the Settings scene. Use for in-app navigation to preferences.
52 
53```swift
54struct SidebarFooter: View {
55    var body: some View {
56        SettingsLink {
57            Label("Preferences", systemImage: "gear")
58        }
59    }
60}
61```
62 
63### openSettings environment action (macOS 14.0+)
64 
65Programmatically open (or bring to front) the Settings window.
66 
67```swift
68struct OpenSettingsButton: View {
69    @Environment(\.openSettings) private var openSettings
70 
71    var body: some View {
72        Button("Open Settings") {
73            openSettings()
74        }
75    }
76}
77```
78 
79---
80 
81## MenuBarExtra (macOS-only)
82 
83Renders a persistent control in the system menu bar. Two styles available:
84- **`.menu`** (default) — standard dropdown menu
85- **`.window`** — popover panel with custom SwiftUI views
86 
87### Menu-style (dropdown)
88 
89```swift
90MenuBarExtra("My Utility", systemImage: "hammer") {
91    Button("Action One") { /* ... */ }
92    Button("Action Two") { /* ... */ }
93    Divider()
94    Button("Quit") { NSApplication.shared.terminate(nil) }
95}
96```
97 
98### Window-style (popover panel)
99 
100```swift
101MenuBarExtra("Status", systemImage: "chart.bar") {
102    DashboardView()
103        .frame(width: 240)
104}
105.menuBarExtraStyle(.window)
106```
107 
108**Variations:**
109- **Toggleable** — pass `isInserted:` with an `@AppStorage` binding to let users show/hide the extra: `MenuBarExtra("Status", systemImage: "chart.bar", isInserted: $showMenuBarExtra)`
110- **Menu-bar-only app** — use `MenuBarExtra` as the sole scene + set `LSUIElement = true` in Info.plist to hide the Dock icon. The app auto-terminates if the user removes the extra from the menu bar.
111 
112---
113 
114## WindowGroup (macOS behavior)
115 
116On macOS, `WindowGroup` supports:
117- **Multiple window instances** — users can open many windows from File > New Window
118- **Tabbed interface** — users can merge windows into tabs
119- **Automatic Window menu** — commands for window management appear automatically
120 
121```swift
122@main
123struct Mail: App {
124    var body: some Scene {
125        // Basic multi-window support
126        WindowGroup {
127            MailViewer()
128        }
129 
130        // Data-presenting window opened programmatically
131        WindowGroup("Message", for: Message.ID.self) { $messageID in
132            MessageDetail(messageID: messageID)
133        }
134    }
135}
136 
137// Open a specific window programmatically
138struct NewMessageButton: View {
139    var message: Message
140    @Environment(\.openWindow) private var openWindow
141 
142    var body: some View {
143        Button("Open Message") {
144            openWindow(value: message.id)
145        }
146    }
147}
148```
149 
150> **Key difference from `Window`:** `WindowGroup` keeps the app running even after all windows are closed. `Window` (as sole scene) quits the app when closed.
151 
152---
153 
154## Window
155 
156A single, unique window scene. The system ensures only one instance exists.
157 
158```swift
159@main
160struct Mail: App {
161    var body: some Scene {
162        WindowGroup {
163            MailViewer()
164        }
165 
166        // Supplementary singleton window
167        Window("Connection Doctor", id: "connection-doctor") {
168            ConnectionDoctor()
169        }
170    }
171}
172 
173// Open programmatically — brings to front if already open
174struct OpenDoctorButton: View {
175    @Environment(\.openWindow) private var openWindow
176 
177    var body: some View {
178        Button("Connection Doctor") {
179            openWindow(id: "connection-doctor")
180        }
181    }
182}
183```
184 
185### Window as sole scene
186 
187If `Window` is the only scene, the app quits when the window closes:
188 
189```swift
190@main
191struct VideoCall: App {
192    var body: some Scene {
193        Window("VideoCall", id: "main") {
194            CameraView()
195        }
196    }
197}
198```
199 
200> **Recommendation:** In most cases, prefer `WindowGroup` for the primary scene. Use `Window` for supplementary singleton windows.
201 
202---
203 
204## UtilityWindow (macOS-only)
205 
206A specialized floating window for tool palettes and inspector panels. Available since macOS 15.0.
207 
208**Key behaviors:**
209- Receives `FocusedValues` from the focused main scene (like menu bar commands)
210- Floats above main windows (default level: `.floating`)
211- Hides when the app is no longer active
212- Only becomes focused when explicitly needed (e.g., clicking the title bar)
213- Dismissible with the Escape key
214- Not minimizable by default
215- Automatically adds a show/hide item to the View menu
216 
217```swift
218@main
219struct PhotoBrowser: App {
220    var body: some Scene {
221        WindowGroup {
222            PhotoGallery()
223        }
224 
225        UtilityWindow("Photo Info", id: "photo-info") {
226            PhotoInfoViewer()
227        }
228    }
229}
230 
231struct PhotoInfoViewer: View {
232    // Automatically updates based on whichever main window is focused
233    @FocusedValue(PhotoSelection.self) private var selectedPhotos
234 
235    var body: some View {
236        if let photos = selectedPhotos {
237            Text("\(photos.count) photos selected")
238        } else {
239            Text("No selection")
240                .foregroundStyle(.secondary)
241        }
242    }
243}
244```
245 
246> **Tip:** Remove the automatic View menu item with `.commandsRemoved()` and place a `WindowVisibilityToggle` elsewhere in your commands.
247 
248---
249 
250## DocumentGroup
251 
252Document-based apps with automatic file management. On macOS, provides:
253- **Document-based menu bar commands** (File > New, Open, Save, Revert)
254- **Multiple document windows** simultaneously
255- On iOS, shows a document browser instead
256 
257```swift
258DocumentGroup(newDocument: TextFile()) { config in
259    ContentView(document: config.$document)
260}
261```
262 
263The document type must conform to `FileDocument` (value type) or `ReferenceFileDocument` (reference type). Key requirements:
264 
265```swift
266struct TextFile: FileDocument {
267    static var readableContentTypes: [UTType] { [.plainText] }
268    var text: String = ""
269    init() {}
270    init(configuration: ReadConfiguration) throws {
271        text = String(data: configuration.file.regularFileContents ?? Data(), encoding: .utf8) ?? ""
272    }
273    func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper {
274        FileWrapper(regularFileWithContents: Data(text.utf8))
275    }
276}
277```
278 
279For multiple document types, add additional `DocumentGroup` scenes — use `DocumentGroup(viewing:)` for read-only formats.
280 
281---
282 
283## Platform Conditionals
284 
285Always wrap macOS-only scenes in `#if os(macOS)`:
286 
287```swift
288@main
289struct MyApp: App {
290    var body: some Scene {
291        WindowGroup {
292            ContentView()
293        }
294 
295        #if os(macOS)
296        Settings {
297            SettingsView()
298        }
299 
300        MenuBarExtra("Status", systemImage: "bolt") {
301            StatusMenu()
302        }
303        #endif
304    }
305}
306```
307 
308---
309 
310## Best Practices
311 
312- **Use `Settings`** for preferences — prefer this over a custom preferences window
313- **Use `MenuBarExtra`** for menu bar items — prefer this over managing AppKit's `NSStatusItem` directly
314- **Use `WindowGroup`** as the primary scene — reserve `Window` for supplementary singletons
315- **Use `UtilityWindow`** for inspectors/palettes — it handles floating, focus, and visibility automatically
316- **Use `DocumentGroup`** for document-based apps — it provides the full File menu and document lifecycle
317- **Gate macOS-only scenes** with `#if os(macOS)` for multiplatform projects
318- **Use `openWindow(id:)`** to open windows programmatically — it brings existing windows to front
319