Common Mistakes

Common Mistakes

A short list of traps that look correct but silently do nothing (or surprise you).

---

1. Preference modifiers outside the content closure

.dialogStyle, .peekInteractiveDismissDisabled, and .peekPlacementInset work via preference keys that are read from the content of the dialog. Applied on the view that has .peekDialog, they never reach that content.

Wrong

Button("Show") { show = true }
    .peekDialog(isPresented: $show) {
        Text("Hello").padding()
    }
    .dialogStyle(.glassRegular)                    // ❌ ignored
    .peekInteractiveDismissDisabled()              // ❌ ignored
    .peekPlacementInset(24)                        // ❌ ignored

Right

Button("Show") { show = true }
    .peekDialog(isPresented: $show) {
        Text("Hello")
            .padding()
            .dialogStyle(.glassRegular)            // ✅
            .peekInteractiveDismissDisabled()      // ✅
            .peekPlacementInset(24)                // ✅
    }

Same rule if you extract the content into a @ViewBuilder — put the modifiers on that content, not on the outer view.

---

2. Expecting a custom background without .plain

The default style wraps content in a material rounded rectangle. Adding your own .background { … } inside the closure can leave you with two backgrounds (yours + the default).

// Looks "wrong" — default material still applied
.peekDialog(isPresented: $show) {
    Text("Copied")
        .padding()
        .background(Capsule().fill(.black))
}

Use .plain when you want to own the chrome:

.peekDialog(isPresented: $show) {
    Text("Copied")
        .padding()
        .background(Capsule().fill(.black))
        .dialogStyle(.plain)
}

---

3. Using peekDialog(items:) off iOS

Stacking is iOS-only (window-based presenter). On macOS / watchOS / visionOS that overload isn't available — use isPresented: or with: for a single dialog. See Stacking.

---

4. Assuming every stacked dialog auto-dismisses on its own timer

In a stack, only the front dialog runs dismissDelay. Dialogs behind wait until they become front. That keeps the queue from clearing itself all at once.

---

5. Putting interactive content behind a full-banner Button and expecting clean drag

If the entire banner is a Button, a drag can still feel fiddly. Prefer a smaller tap target (or disable swipe with .peekInteractiveDismissDisabled() when the banner is an action you don't want swipe-dismissing).

---

6. Forgetting the default delay is .persistent

For isPresented: / with:, omitting dismissDelay means the dialog stays until swipe or binding clear. Use .short / .medium / .long when you want a toast that goes away on its own.

.peekDialog(isPresented: $show, dismissDelay: .medium) { … }

The stacked items: API defaults to .short instead.

---

Still stuck? Open an issue.