Window Management

Window Management

Overview

Use this skill to tailor each SwiftUI window to its job. Start by identifying which scene owns the window (Window, WindowGroup, or a dedicated utility scene), then customize the toolbar/title area, background material, resize and restoration behavior, and initial or zoomed placement.

Prefer scene and window modifiers over ad hoc AppKit bridges when SwiftUI offers the behavior directly. Keep each window purpose-built: a main browser window, an About window, and a media player window usually want different chrome, resizability, restoration, and placement rules.

These APIs are macOS 15+ SwiftUI window/scene customizations. For older deployment targets, expect to use more AppKit bridging or availability guards.

Workflow

1. Inspect the relevant scene declaration and classify the window role: main app navigation, inspector/detail utility, About/support window, media playback window, welcome window, or a borderless custom surface.
2. Adjust toolbar and title presentation to match the content.
3. If the toolbar background or entire toolbar is hidden, make sure the window still has a usable drag region.
4. Refine window behavior for that role: minimize availability, restoration, resize expectations, and whether the window should appear at launch.
5. Set default placement for newly opened windows and ideal placement for zoom behavior when content and display size matter.
6. Build and launch the app with build-run-debug to verify the result in a real foreground .app bundle.
7. If SwiftUI scene/window modifiers are not enough, switch to appkit-interop for a narrow NSWindow bridge rather than spreading AppKit through the view tree.

Toolbar And Title

• Use .toolbar(removing: .title) when the window title should stay associated with the window for accessibility and menus, but not be visibly drawn in the title bar.
• Use .toolbarBackgroundVisibility(.hidden, for: .windowToolbar) when large media or hero content should visually extend to the top edge of the window.
• If the window still needs close/minimize/full-screen controls, remove only the title and toolbar background. If the toolbar should disappear entirely, use .toolbarVisibility(.hidden, for: .windowToolbar) instead.
• Remove custom toolbar backgrounds and manually painted titlebar fills before layering new SwiftUI toolbar APIs on top.
• Keep the window's logical title meaningful even if hidden; the system can still use it for accessibility and menu items. These are visual changes only.

Drag Regions

• If a toolbar background is hidden or the toolbar is removed entirely, use WindowDragGesture() to extend the draggable area into your content.
• Attach the gesture to a transparent overlay or non-interactive header region that does not steal gestures from real controls.
• For a media player with custom playback controls, insert the drag overlay between the video content and the controls so AVKit or transport controls keep receiving input.
• Pair the drag gesture with .allowsWindowActivationEvents(true) so clicking and immediately dragging a background window still activates and moves it.

Background And Materials

• Use .containerBackground(.thickMaterial, for: .window) when a utility window or About window should replace the default window background with a subtle frosted material.
• Prefer system materials for stylized windows instead of hardcoded translucent colors.
• Use this especially for fixed-content utility windows where a softer backdrop is part of the design.

Window Behavior

• Use .windowMinimizeBehavior(.disabled) for always-reachable utility windows such as a custom About window where minimizing adds little value.
• Disable the green zoom control through fixed sizing or window constraints when the window's content has one intended size.
• Use .restorationBehavior(.disabled) for windows that should not reopen on next launch, such as About panels, transient support/info windows, or first-run welcome surfaces.
• Keep state restoration enabled for primary document or navigation windows when reopening prior size and position is desirable.
• By default, SwiftUI respects the user's system-wide macOS state restoration setting. Use restorationBehavior(...) only when a specific window should intentionally opt into or out of that system behavior.
• Use .defaultLaunchBehavior(.presented) for windows that should appear first on launch, such as a welcome window, and choose that behavior intentionally rather than relying on side effects from scene creation order.