How it works
CommandGroupPlacement is a set of named constants that identify a standard location in your app's menu hierarchy, such as the New-item area of the File menu or the Help menu. You use it to tell SwiftUI exactly which built-in group of commands you want to extend, replace, or sit before or after, so your custom menu items land in the place a user already expects them. Reach for it whenever you build menu bar commands with CommandGroup and need to target a specific system-defined section rather than appending to an arbitrary spot.
Refer to a section by its placement constant
Each placement value names a well-known region of the menus. The example holds one in a property,
let placement: CommandGroupPlacement = .newItem, which points at the New-document group near the top of the File menu. SwiftUI defines a fixed catalog of these constants, so you choose from the system's vocabulary rather than naming menus by string.Pass the placement to a CommandGroup
A
CommandGroupPlacementvalue isn't used on its own; it's the argument that anchors aCommandGroup. The labelCommandGroup(replacing: .newItem) { ... }shown in the example feeds.newItemto the group so the custom content takes over that exact section of the menu hierarchy.Choose how your commands relate to the section
The same placement works with the
replacing:,before:, andafter:forms of CommandGroup, which respectively swap out the built-in items, insert ahead of them, or follow them. The constant such as.newItemstays the subject; the parameter you pass it to decides whether you override or surround the system commands at that location.Pick from the standard placements
Beyond
.newItem, the type vends constants for other regions, including app info, undo and redo, pasteboard, text formatting, the sidebar and toolbar, window arrangement, and the Help group. Selecting the matching constant keeps related commands grouped where users hunt for them, which is why the example surfaces the active value withLabel("Placement: .newItem", systemImage: "menubar.rectangle").
let placement: CommandGroupPlacement = .newItem to .help (and update the label text to match) to retarget the same custom commands at the Help menu instead of the File menu's New section.Example & preview
Press Run live & edit to compile it in your browser — then edit the Swift on the left and the preview re-renders live.
struct CommandGroupPlacementDemo: View {
let placement: CommandGroupPlacement = .newItem
var body: some View {
VStack(alignment: .leading, spacing: 8) {
Text("Menu Commands")
.font(.headline)
Text("CommandGroup(replacing: .newItem) { ... }")
.font(.system(.caption, design: .monospaced))
.foregroundStyle(.secondary)
Label("Placement: .newItem", systemImage: "menubar.rectangle")
.font(.callout)
}
.padding()
}
}