Skip to content
macOSDeep Dive Published Updated 8 min readViews unavailable

NSPopover on macOS: Anchoring, Behavior, and Close Ownership

Manage AppKit popovers predictably with visible anchors, explicit transient behavior, retained content controllers, and idempotent dismissal handling.

An NSPopover is content presented in relation to an existing view or toolbar item. That relationship is part of the lifecycle: the anchor can disappear, move, or become detached while the popover is open. Its behavior determines which outside interactions close it, and its content controller can outlive the button or menu action that created it. Reliable popover code treats anchor validity, content ownership, close reason, and presentation state as explicit inputs.

Popovers are not generic floating windows. Use one for supplementary content that is clearly attached to an affordance. If the content is a long-lived workspace or a task that users must compare while interacting elsewhere, an ordinary window or sheet may communicate the interaction model more honestly. The AppKit class provides transient, semi-transient, and application-defined behaviors; the right choice depends on whether outside interaction should dismiss the content.

Configure content before presenting

Set a content view controller before calling show. The positioning view must exist, be non-nil, and be visible in the window hierarchy. Apple documents that passing a nil view raises an invalid argument exception, a missing content controller or view raises an internal inconsistency exception, and an anchor that is not visible results in no presentation. These are contract conditions, not rare cosmetic edge cases.

import AppKit

final class HelpPopoverController {
    private let popover = NSPopover()

    init(contentController: NSViewController) {
        popover.behavior = .transient
        popover.contentViewController = contentController
    }

    func show(from anchor: NSView) {
        guard let window = anchor.window,
              window.isVisible,
              !anchor.isHidden,
              !anchor.visibleRect.isEmpty,
              !popover.isShown else { return }
        popover.show(
            relativeTo: anchor.bounds,
            of: anchor,
            preferredEdge: .maxY
        )
    }

    func close() {
        if popover.isShown {
            popover.performClose(nil)
        }
    }
}

The sample owns the popover for as long as the feature needs it and checks that the anchor belongs to a window. isShown is useful state but does not replace delegate and close-notification handling when the application must learn that a user dismissed it. If the feature creates a new controller every time, release or reuse it according to the content’s model ownership rather than keeping accidental stale state.

Choose behavior as an interaction contract

With transient behavior, the system closes a popover when the user interacts with a UI element outside it. Semi-transient behavior closes it when the user interacts with UI elements in the window containing its positioning view; choose it only when that is the intended dismissal boundary. Application-defined behavior leaves close responsibility to the app and is not usually closed by the system on the developer’s behalf. The documented default is application-defined, so set behavior explicitly when you expect a different policy.

These behaviors describe policy, not a complete input-event matrix. Apple does not specify every interaction that closes a transient or semi-transient popover; for example, some menus or panels that become key only when needed do not close a transient popover. Application-defined behavior makes the app responsible for the close policy, but AppKit may still close the popover in limited circumstances such as when its positioning window closes. Test the exact menu, panel, window, and activation transitions your interface uses instead of assuming every outside click is equivalent.

Transient behavior is appropriate for a short picker or contextual inspector that should disappear when focus moves outside it. Semi-transient can be appropriate when interactions elsewhere in the app should leave the popover open but interactions in its positioning view’s window should dismiss it. Application-defined behavior can support a workflow that deliberately remains open, but it requires complete close ownership: dismissal on relevant navigation, Escape handling, anchor deletion, and content replacement.

Do not use a transient popover for a destructive confirmation if an outside click silently discards meaningful input. Do not choose application-defined simply to prevent the popover from closing; that can leave stale UI attached to a deleted model. Ask what should happen when the user clicks elsewhere, switches windows, closes the parent, or changes the selected object, and encode each answer.

Anchor and controller lifetimes

The positioning view determines placement and moves with its anchor. If a collection cell is reused while its popover remains open, the popover may now appear to describe another item. Associate the presented content with a stable model identifier and dismiss or update it when selection changes. For a toolbar item, use its dedicated presentation API and account for toolbar overflow, where AppKit can choose another appropriate anchor.

The popover retains and displays its content view controller. That controller should not assume its original presenting view remains alive forever. Keep the underlying model reference valid, observe model deletion or account changes, and stop asynchronous work when the relevant content closes. If a background task finishes after close, either safely update durable model state or discard presentation-only work; do not resurrect a dismissed popover as a side effect.

Define the popover’s preferred content size and adapt when the window is near screen edges. AppKit positions it relative to the view and can move it when the view moves, but content that exceeds available screen space remains an application design problem. Test different display scales, multiple monitors, display-edge anchors, and window resizing. Avoid fixed geometry that assumes a single screen arrangement.

Observe presentation and close reasons

AppKit exposes will-show, did-show, will-close, and did-close notifications, plus delegate methods for additional behavior. Use one state owner to map these events into a small state machine such as hidden, showing, visible, and closing. Notification handlers may run during animation and should not recursively call show or close without checking state. Keep close handling idempotent because user interaction and application teardown can converge on the same cleanup path.

When product behavior depends on why a popover closed, use the close-reason information documented by AppKit rather than inferring from the last mouse event. On close, cancel content-only work, release transient selection state, and restore keyboard focus to a sensible owner if necessary. Do not assume a popover’s content controller is destroyed on every dismissal; it may be shown again later.

performClose(_:) asks the popover to close and can consult its delegate; close() forces closure without consulting the delegate. Use the former for normal user-visible dismissal and reserve forced close for cleanup where the application has already decided the UI must end. A delegate veto must not trap an app shutdown or model deletion in a state where the popover points at invalid data.

Accessibility and keyboard behavior

A popover should be reachable through the same control that opens it. Give the anchor a meaningful accessibility label and ensure the content has a clear initial focus target. Keyboard users need a predictable way to dismiss or complete the popover, and focus should not jump to an unrelated window when it closes. Test VoiceOver, keyboard navigation, full keyboard access, and reduced-motion expectations when animations are significant.

Avoid implementing a custom outside-click monitor unless the chosen behavior requires application-defined logic that AppKit does not provide. Global event monitors complicate permissions, event ordering, and focus. If application-defined behavior is necessary, observe only the app’s own relevant interactions and document how Escape, parent-window closure, and anchor invalidation are handled.

For editable content, decide whether closing commits, discards, or preserves a draft. A transient behavior can close on an outside click, so silently committing on every edit may surprise users while silently discarding can lose work. Keep a small draft model and apply it on an explicit action when the operation is consequential. If a validation error prevents dismissal, return focus to the invalid field and expose the error through accessibility APIs.

If popover content opens a menu or another popover, prevent competing presentation ownership. Close or transition the first presentation deliberately before showing the next one, and avoid retaining both controllers with stale model references. Test keyboard invocation as well as mouse clicks; a popover anchored to a control should still make sense when invoked through keyboard focus, even if the visual anchor rectangle is not at its center.

Failure and regression matrix

Test presentation with a visible anchor, an anchor removed just before presentation, repeated open requests, close during animation, parent-window close, model deletion, cell reuse, toolbar overflow, screen-edge placement, and clicks both inside and outside the owner window. Verify that only one popover exists for the feature, that stale content cannot be mistaken for a new selection, and that close cleanup can safely run twice.

Log feature identity, presentation attempt, close reason, and whether the anchor remained valid. Do not log sensitive content displayed inside the popover. Track failed presentation separately from deliberate dismissal. A no-op show caused by a hidden anchor should be diagnosable as an anchor lifecycle issue, not misreported as AppKit randomly failing.

The core production rule is to own the popover object, configure behavior deliberately, and anchor it to a live view whose model identity remains stable. AppKit provides placement and dismissal mechanics; your app supplies truthful content, focus behavior, cancellation, and cleanup.

Related:

Sources:

Comments