CocoaNavigationController

A UINavigationController-like container view controller for macOS.

Features

• Push & Pop - Familiar iOS-style navigation API
• Animated Transitions - Smooth horizontal slide animations
• View Controller Stack - Full stack management (push, pop, popToRoot, setViewControllers)
• Delegate Support - willShow/didShow callbacks
• Modern Swift - Swift 5.9+ with @MainActor safety

Installation

Swift Package Manager

Add to your Package.swift:

dependencies:[.package(url:"https://github.com/hechen/CocoaNavigationController.git", from:"2.0.0")]

Or in Xcode: File → Add Package Dependencies → Enter the repository URL.

Usage

Basic Setup

import CocoaNavigationController
// Create navigation controller with a root view controller
letrootVC=MyViewController()letnavController=CocoaNavigationController(rootViewController: rootVC)
// Set as window's content view controller
window.contentViewController = navController

Push

letdetailVC=DetailViewController()
navigationController?.push(detailVC, animated:true)

Pop

// Pop one level
navigationController?.pop(animated:true)
// Pop to specific view controller
navigationController?.popToViewController(targetVC, animated:true)
// Pop to root
navigationController?.popToRootViewController(animated:true)

Set Stack

// Replace entire stack
letnewStack=[rootVC, vc1, vc2, vc3]
navigationController?.setViewControllers(newStack, animated:true)

Access Navigation Controller

// From any view controller in the stack
classMyViewController:NSViewController{func goBack(){
navigationController?.pop(animated:true)}}

Delegate

classMyClass:CocoaNavigationControllerDelegate{func navigationController(_ navController:CocoaNavigationController, willShow viewController:NSViewController, animated:Bool){print("Will show: \(viewController)")}func navigationController(_ navController:CocoaNavigationController, didShow viewController:NSViewController, animated:Bool){print("Did show: \(viewController)")}}
navController.delegate = myDelegate

How It Works

The navigation controller uses snapshot-based animations for smooth transitions:

 Push →
┌─────────────┐ ┌─────────────┐
│ │ │ │
│ From │ │ To │
│ │ │ │
└─────────────┘ └─────────────┘
← Pop

1. Before animation: Create snapshots of both views
2. During animation: Slide snapshots horizontally
3. After animation: Replace snapshot with real view

This ensures smooth 60fps animations regardless of view complexity.

Requirements

• macOS 12.0+
• Swift 5.9+
• Xcode 15+

License

MIT License - see LICENSE for details.

Credits

Originally created by Chen He in 2019. Updated in 2026 with modern Swift patterns and Swift Package Manager support.