Skip to content
macOS user interface guide to display an overlay with descriptions of NSViews in your app
Swift Objective-C
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
AppGuideOverlay.xcodeproj update scheme for Xcode 11.2 Jan 18, 2020
AppGuideOverlay fix light mode button colors Jan 18, 2020
Example fix Nib internal inconsistency Jan 18, 2020
img add README Feb 5, 2018
.gitignore add meta files Jan 27, 2018


Swift 5.0 Version License Platform Carthage compatible

macOS user interface guide to display an overlay with descriptions of NSViews in your app.



Have a look at the example app that is part of this repository. The basic setup looks like this:

// Given access to interesting view components ...
let window: NSWindow = ...
let textField: NSTextField = ...
let button: NSButton = ...

// ... and an AppGuide with steps attached to them ...
let appGuide = AppGuide(steps: [
    AppGuide.Step(title: "A Text Field",
          detail: "Use this to type something.",
          position: .below,
          cutoutView: textField),
    AppGuide.Step(title: "A Button",
          detail: "Press this to make something happen.",
          position: .right,
          cutoutView: button)

// ... keep the AppGuideOverlay around and start it:
let appGuideOverlay = AppGuideOverlay(
    appGuide: appGuide,
    appGuideSuperview: window.contentView!)

Types of Interest

  • AppGuide is the model. It contains an array of AppGuide.Steps that represents the steps in your guide.
  • AppGuideOverlay is a convenient service object to set up the app guide and control it. (You don't have to use it and can use AppGuidePresenter and a HandlesOverlayEvents conforming delegate. But AppGuideOverlay really is the most useful façade to get started.)
  • AppGuideOverlayDelegate is used to react to progress and completion events.


  • Uses Auto Layout to position the AppGuide.Step contents next to the view the steps explain. This ensures the window size fits the labels at all times. It also ensures the step's description is displayed correctly when the window is resized.
  • Tasteful pulsation of the cutout frame's size in the overlay. This also indicates that the app doesn't just hang.
  • Good citizen: No custom NSRunLoop or anything. It's just a view on top of other views that captures the first responder status and doesn't give it back to underlying controls. This means you can remote-control your user interface to change display content and animate as usual while the overlay is visible.

Code License

Copyright (c) 2018-2019 Christian Tietze. Distributed under the MIT License.

You can’t perform that action at this time.