1# macOS Window & Toolbar Styling Reference
2 
3> Window configuration, toolbar styles, sizing, positioning, and navigation patterns specific to macOS SwiftUI apps.
4 
5## Table of Contents
6 
7- [Quick Lookup Table](#quick-lookup-table)
8- [Toolbar Styles](#toolbar-styles)
9- [Window Style](#window-style)
10- [Window Sizing](#window-sizing)
11- [MenuBarExtra Style (macOS-only)](#menubarextra-style-macos-only)
12- [Navigation Layout (macOS behavior)](#navigation-layout-macos-behavior)
13- [Commands & Keyboard](#commands--keyboard)
14- [Best Practices](#best-practices)
15 
16---
17 
18## Quick Lookup Table
19 
20| API | Availability | macOS-Only? | Usage |
21|-----|-------------|:-----------:|-------|
22| `windowToolbarStyle(_:)` | macOS 11.0+ | Yes | Sets toolbar style: `.unified`, `.unifiedCompact`, `.expanded` |
23| `windowStyle(_:)` | macOS 11.0+ | No | Supports `.hiddenTitleBar` for chromeless windows |
24| `windowResizability(_:)` | macOS 13.0+ | No | Controls resize handle and green zoom button behavior |
25| `defaultSize(width:height:)` | macOS 13.0+ | No | Initial frame size when user creates a new window |
26| `defaultPosition(_:)` | macOS 13.0+ | No | Initial window position on screen |
27| `windowIdealPlacement(_:)` | macOS 15.0+ | No | Closure with display geometry for precise window positioning |
28| `menuBarExtraStyle(_:)` | macOS 13.0+ | Yes | Sets MenuBarExtra to `.menu` or `.window` style |
29| `NavigationSplitView` | macOS 13.0+ | No | Columns always visible side-by-side on macOS; translucent sidebar |
30| `Inspector` | macOS 14.0+ | No | Trailing-edge sidebar panel; resizable by dragging |
31 
32---
33 
34## Toolbar Styles
35 
36### windowToolbarStyle (macOS-only)
37 
38Controls how the toolbar and title bar are displayed. Applied to a scene.
39 
40```swift
41@main
42struct MyApp: App {
43    var body: some Scene {
44        WindowGroup {
45            ContentView()
46        }
47        // Title bar and toolbar in a single row
48        .windowToolbarStyle(.unified)
49    }
50}
51```
52 
53**Available styles:**
54 
55| Style | Description |
56|-------|-------------|
57| `.automatic` | System default |
58| `.unified` | Title bar and toolbar in a single combined row |
59| `.unifiedCompact` | Same as unified but with reduced vertical height |
60| `.expanded` | Title bar displayed above the toolbar (more toolbar space) |
61 
62```swift
63// Unified compact — minimal chrome
64.windowToolbarStyle(.unifiedCompact)
65 
66// Expanded — title bar above toolbar
67.windowToolbarStyle(.expanded)
68 
69// Unified with title hidden
70.windowToolbarStyle(.unified(showsTitle: false))
71```
72 
73### Toolbar content
74 
75```swift
76struct ContentView: View {
77    @State private var searchText = ""
78 
79    var body: some View {
80        NavigationSplitView {
81            SidebarView()
82        } detail: {
83            DetailView()
84        }
85        .toolbar {
86            ToolbarItem(placement: .automatic) {
87                Button(action: addItem) {
88                    Label("Add", systemImage: "plus")
89                }
90            }
91        }
92        .searchable(text: $searchText, placement: .sidebar)
93    }
94}
95```
96 
97---
98 
99## Window Style
100 
101### windowStyle
102 
103Set the visual style of a window. Use `.hiddenTitleBar` for chromeless, immersive windows.
104 
105```swift
106// Standard title bar (default)
107WindowGroup {
108    ContentView()
109}
110.windowStyle(.titleBar)
111 
112// Hidden title bar — chromeless window
113WindowGroup {
114    ContentView()
115}
116.windowStyle(.hiddenTitleBar)
117```
118 
119> **Use case:** `.hiddenTitleBar` is useful for media players, custom-chrome apps, or immersive experiences where the standard title bar is unwanted.
120 
121---
122 
123## Window Sizing
124 
125### windowResizability, defaultSize, defaultPosition
126 
127These modifiers work together to configure window sizing and placement:
128 
129```swift
130WindowGroup {
131    ContentView()
132        .frame(minWidth: 600, minHeight: 400)
133}
134.defaultSize(width: 900, height: 600)
135.defaultPosition(.center)
136.windowResizability(.contentMinSize)
137```
138 
139**`windowResizability` options:**
140 
141| Value | Behavior |
142|-------|----------|
143| `.automatic` | System decides resize behavior |
144| `.contentSize` | Fixed to content size; no user resize; zoom button disabled |
145| `.contentMinSize` | Resizable with minimum based on content's `minWidth`/`minHeight` |
146 
147**`defaultPosition` options:** `.center`, `.topLeading`, `.top`, `.topTrailing`, `.leading`, `.trailing`, `.bottomLeading`, `.bottom`, `.bottomTrailing`
148 
149**Guidelines:**
150- Set `minWidth`/`minHeight` via `.frame()` on content, enforce with `.contentMinSize`
151- Use `.defaultSize()` for initial dimensions (larger than minimums)
152- `defaultSize` also accepts `CGSize`
153 
154### windowIdealPlacement (macOS 15.0+)
155 
156For precise programmatic positioning, use a closure with display geometry:
157 
158```swift
159.windowIdealPlacement { context in
160    let screen = context.defaultDisplay.visibleArea
161    return WindowPlacement(x: screen.midX, y: screen.midY,
162                           width: screen.width / 2, height: screen.height)
163}
164```
165 
166---
167 
168## MenuBarExtra Style (macOS-only)
169 
170Choose between dropdown menu and popover panel for `MenuBarExtra`.
171 
172```swift
173// Dropdown menu (default)
174MenuBarExtra("Status", systemImage: "chart.bar") {
175    Button("Action") { /* ... */ }
176}
177.menuBarExtraStyle(.menu)
178 
179// Popover panel with custom SwiftUI content
180MenuBarExtra("Status", systemImage: "chart.bar") {
181    DashboardView()
182}
183.menuBarExtraStyle(.window)
184```
185 
186---
187 
188## Navigation Layout (macOS behavior)
189 
190### NavigationSplitView
191 
192On macOS, `NavigationSplitView` displays columns side-by-side (never overlaid). The sidebar gets a translucent material background. Columns support variable-width resizing by the user.
193 
194```swift
195NavigationSplitView {
196    List(items, selection: $selectedId) { item in
197        Text(item.name)
198    }
199    .navigationSplitViewColumnWidth(min: 180, ideal: 220, max: 300)
200} detail: {
201    DetailView(id: selectedId)
202}
203.navigationSplitViewStyle(.balanced)
204```
205 
206Use the three-column variant (`sidebar` / `content` / `detail`) for master-detail-detail layouts. Customize column widths with `.navigationSplitViewColumnWidth(min:ideal:max:)`.
207 
208### Inspector (macOS 14.0+)
209 
210A trailing-edge panel for supplementary information. On macOS, it appears as a sidebar-style panel that can be resized by dragging its edge.
211 
212```swift
213struct ContentView: View {
214    @State private var showInspector = false
215 
216    var body: some View {
217        MainContent()
218            .inspector(isPresented: $showInspector) {
219                InspectorView()
220                    .inspectorColumnWidth(min: 200, ideal: 250, max: 400)
221            }
222            .toolbar {
223                ToolbarItem {
224                    Button {
225                        showInspector.toggle()
226                    } label: {
227                        Label("Inspector", systemImage: "info.circle")
228                    }
229                }
230            }
231    }
232}
233```
234 
235---
236 
237## Commands & Keyboard
238 
239### Commands, CommandGroup, CommandMenu
240 
241Define menu bar commands. On macOS, these populate the menu bar directly. On iOS, they create key commands.
242 
243```swift
244.commands {
245    CommandMenu("Tools") {
246        Button("Run Analysis") { /* ... */ }
247            .keyboardShortcut("r", modifiers: [.command, .shift])
248    }
249    CommandGroup(after: .newItem) {
250        Button("New From Template...") { /* ... */ }
251    }
252}
253```
254 
255**`CommandGroup` placement options:** `.replacing(_:)` replaces a system group, `.before(_:)` / `.after(_:)` inserts adjacent to it. Common placements: `.newItem`, `.saveItem`, `.help`, `.toolbar`, `.sidebar`.
256 
257### KeyboardShortcut
258 
259On macOS, shortcuts are displayed alongside menu items and in button tooltips on hover.
260 
261```swift
262Button("Save") {
263    save()
264}
265.keyboardShortcut("s", modifiers: .command)
266 
267Button("Delete") {
268    delete()
269}
270.keyboardShortcut(.delete, modifiers: .command)
271```
272 
273### openWindow
274 
275Programmatically open a window. If the target window is already open, brings it to the front.
276 
277```swift
278struct ToolbarActions: View {
279    @Environment(\.openWindow) private var openWindow
280 
281    var body: some View {
282        Button("Connection Doctor") {
283            openWindow(id: "connection-doctor")
284        }
285 
286        Button("Show Message") {
287            openWindow(value: message.id)  // Type-matched to WindowGroup
288        }
289    }
290}
291```
292 
293---
294 
295## Best Practices
296 
297- **Use `.unified` or `.unifiedCompact`** for most apps — `.expanded` only when you need many toolbar items
298- **Set min frame sizes on content** and use `.windowResizability(.contentMinSize)` to enforce them
299- **Always provide `defaultSize`** so new windows start at a reasonable size
300- **Use `NavigationSplitView`** for sidebar navigation — not `HSplitView`
301- **Use `Inspector`** for supplementary panels — it integrates with the toolbar automatically
302- **Define `Commands`** for all repeatable actions — users expect keyboard shortcuts on macOS
303- **Use `#if os(macOS)`** to wrap macOS-only window configuration in multiplatform projects
304