Building a macOS Menu Bar App in Swift

Why Menu Bar Apps Are Different

A menu bar app is not a regular macOS app with a smaller window. It operates under a fundamentally different set of constraints: it has no Dock icon, no main window by default, no standard app lifecycle, and its primary UI is a popover or panel attached to a 22-pixel-tall status item in the system menu bar.

These constraints affect every architectural decision — from how you manage state to how you handle focus to how you persist data. Developers who treat a menu bar app as a miniaturized standard app end up fighting AppKit conventions instead of working with them.

Decision 1: AppKit, SwiftUI, or Both

The Hybrid Approach

The menu bar itself is AppKit territory. NSStatusItem, NSStatusBarButton, NSPopover, and NSMenu are AppKit classes with no SwiftUI equivalents. You cannot create a menu bar presence purely in SwiftUI.

The popover content, however, can be pure SwiftUI. NSPopover.contentViewController accepts an NSHostingController that wraps any SwiftUI view. This gives you the best of both worlds: AppKit for the system integration layer, SwiftUI for the UI content.

AppKit Layer:
  NSStatusItem → NSStatusBarButton → click → NSPopover

SwiftUI Layer:
  NSHostingController → PopoverView (SwiftUI)
    → HistoryTab
    → BookmarksTab
    → SettingsTab

Why not pure AppKit? SwiftUI's declarative UI, state management (@Published, @ObservedObject, @EnvironmentObject), and animation system are significantly more productive for building the content views. The list views, tab switching, search filtering, and item interactions are all easier in SwiftUI.

Why not pure SwiftUI? SwiftUI's MenuBarExtra (introduced in macOS 13) provides a basic menu bar presence but lacks the control needed for professional menu bar apps. You cannot customize the popover size dynamically, control focus behavior precisely, or implement click-versus-right-click differentiation.

Decision 2: Popover vs. Panel vs. Window

Popover (NSPopover)

A popover is attached to the status bar button and appears directly below it. It closes when the user clicks outside, presses Escape, or switches to another app. This is the standard behavior users expect from menu bar apps.

Advantages: Feels native, auto-positions relative to the menu bar, handles light/dark mode, closes automatically on focus loss.

Limitations: Fixed arrow pointing to the status item (cosmetic), limited size (Apple recommends keeping popovers under 600pt wide), no standard resize handle.

Panel (NSPanel)

A floating panel is a borderless window that stays above other windows. It can be positioned independently of the status item and offers more flexibility in size and behavior.

Advantages: Unrestricted size, no arrow, can be repositioned by the user.

Limitations: Must manually handle focus/dismiss behavior, doesn't feel as "attached" to the menu bar, more code to implement correctly.

Window (NSWindow)

A standard window with a title bar. This is appropriate for secondary views (preferences, full image editor) but not for the primary menu bar interface.

Recommendation: Use NSPopover for the primary interface and NSWindow for secondary views (preferences, editors). The popover provides the expected menu bar app behavior with minimal custom code.

Decision 3: LSUIElement and the Dock

Setting LSUIElement = true in Info.plist makes your app a "UI element" application — it has no Dock icon, no main menu bar, and doesn't appear in the ⌘Tab app switcher. This is the correct setting for a menu bar-only app.

Consequence: Without a main menu bar, standard menu items (Edit → Copy, Edit → Paste, File → Preferences) don't exist. Any keyboard shortcuts that would normally be handled by the menu bar (⌘C, ⌘V within your app's views) must be handled manually in your SwiftUI views or via NSEvent monitoring.

Consequence: Without a Dock icon, there's no way for the user to "find" your app visually if the popover is closed and the menu bar icon is hidden behind the system overflow area (common on MacBook screens with many menu bar items).

Decision 4: Singleton Services vs. Dependency Injection

Menu bar apps tend toward singleton services because the app has a single instance of everything: one clipboard monitor, one database, one hotkey manager, one screenshot service. The question is whether to use explicit singletons or pass dependencies through the view hierarchy.

Practical approach: Use singletons for system-level services (clipboard monitoring, hotkey registration, screenshot capture) and @ObservableObject / @EnvironmentObject for view-level state (selected tab, search query, expanded item). This mirrors the natural boundary: system services are global, UI state is scoped.

Decision 5: Data Layer

SQLite via GRDB.swift

For clipboard managers and similar data-heavy menu bar apps, SQLite (via GRDB.swift) is the recommended data layer. It provides:

• Full SQL query support (important for search and filtering)
• ACID transactions (important for data integrity during rapid clipboard captures)
• FTS5 full-text search (important for searching clipboard history)
• Single-file database (simple backup and deletion)
• Excellent performance for the data volumes involved (thousands to tens of thousands of items)

Core Data

Core Data adds an ORM layer that's useful for complex object graphs but overkill for the flat table structures of a clipboard manager. The additional abstraction increases complexity without proportional benefit.

UserDefaults

Appropriate for preferences (start at login, close after copy, retention period) but not for clipboard history. UserDefaults is not designed for thousands of records with indexed search.

Decision 6: Clipboard Monitoring Strategy

Polling (Timer-Based)

macOS does not provide a notification when the clipboard changes. The standard approach is polling: check NSPasteboard.general.changeCount on a timer. When the count changes, the clipboard has new content.

Timer.scheduledTimer(withTimeInterval: 0.5, repeats: true) { _ in
    let currentCount = NSPasteboard.general.changeCount
    if currentCount != self.lastChangeCount {
        self.lastChangeCount = currentCount
        self.captureClipboard()
    }
}

Polling interval: 0.5 seconds is the sweet spot. Shorter intervals (0.1s) waste CPU cycles checking an unchanged clipboard. Longer intervals (1.0s+) risk missing rapid copy sequences and feel sluggish.

CPU impact: Checking changeCount is a single integer comparison — effectively zero CPU cost. The timer overhead at 0.5s intervals is negligible.

Content Hashing for Deduplication

Users frequently copy the same content multiple times (selecting the same text, copying an image they already copied). A content hash (SHA-256 of the clipboard data) detects duplicates and avoids storing the same item repeatedly.

Decision 7: Image Handling

Images on the macOS clipboard are large. A Retina screenshot produces 10 to 30 MB of TIFF data. Storing this raw data would consume gigabytes within days for a heavy screenshot user.

Compression Pipeline

NSPasteboard (TIFF, 10-30 MB)
    → NSImage
    → Compressed PNG/JPEG (200 KB - 2 MB)
    → Save to Images/ folder
    → Generate 48×48 thumbnail
    → Save thumbnail to Thumbnails/ folder

The compression step should be configurable. A "Max Image Size" preference (e.g., 1024px, 2048px, original) lets users balance quality against storage.

Clipboard Write Compression

When copying an image back to the clipboard (for pasting into another app), the same compression should apply. Writing raw NSImage to NSPasteboard produces 10 to 30 MB of TIFF data on the receiving end. Writing compressed JPEG data instead reduces this to 100 KB to 1 MB — critical for pasting into web-based AI tools that have upload size limits.

Decision 8: Global Hotkey Implementation

The Carbon Event API (RegisterEventHotKey) is the standard mechanism for global hotkeys on macOS. The HotKey Swift library wraps this API cleanly.

After writing content to the clipboard, simulate ⌘V using CGEvent:

// Create key-down event for ⌘V
let keyDown = CGEvent(keyboardEventSource: nil, virtualKey: 0x09, keyDown: true)
keyDown?.flags = .maskCommand

// Create key-up event
let keyUp = CGEvent(keyboardEventSource: nil, virtualKey: 0x09, keyDown: false)
keyUp?.flags = .maskCommand

// Post to active application
keyDown?.post(tap: .cghidEventTap)
keyUp?.post(tap: .cghidEventTap)

This requires Accessibility permission. A small delay (10 to 50ms) between the clipboard write and the simulated keystroke ensures the clipboard content is available when the target application processes the paste.

Decision 9: Start at Login

macOS 13+ provides SMAppService.mainApp for registering login items. This replaces the older SMLoginItemSetEnabled API.

import ServiceManagement

func setStartAtLogin(_ enabled: Bool) {
    do {
        if enabled {
            try SMAppService.mainApp.register()
        } else {
            try SMAppService.mainApp.unregister()
        }
    } catch {
        // Handle error
    }
}

This registration appears in System Settings → General → Login Items as a user-controllable toggle.

Decision 10: Permissions Strategy

Menu bar apps that capture screenshots and register global hotkeys need two system permissions: Screen Recording and Accessibility. Both require user action in System Settings.

Graceful Degradation

The best approach is graceful degradation: the app works without permissions but with reduced functionality. If Accessibility permission is not granted, hotkeys don't fire but the rest of the app works. If Screen Recording permission is not granted, screenshot capture is unavailable but clipboard monitoring and bookmarks still function.

This avoids the anti-pattern of blocking the entire app behind a permission gate. Users can start using clipboard features immediately and grant screenshot/hotkey permissions when they're ready.

Permission Persistence

Code-signed applications retain their permissions across updates as long as the signing identity and bundle ID remain stable. Developer ID signing with a consistent team ID ensures that OS updates and app updates don't reset permissions.