Beacon

SwiftUI spotlight overlay framework

Step-by-step tour	Auto-advancing tutorial
manual-demo.mp4	auto-demo.mp4

Features

• Single-line spotlight presentation
• Declarative sequence builder with step navigation
• Multiple spotlight shapes
• Configurable overlay style and animations
• Works across sheets, popovers, and navigation stacks
• Async/await support
• Optional os.Logger integration
• VoiceOver support

Installation

Swift Package Manager

Add Beacon to your project via Xcode:

1. File > Add Package Dependencies
2. Enter: https://github.com/mmellau/swift-beacon
3. Select version and add to your target

Or add to Package.swift:

dependencies: [
    .package(url: "https://github.com/mmellau/swift-beacon", from: "0.1.0")
]

Quick Start

1. Mark targets

import Beacon

Image(systemName: "star")
    .beaconTarget("star")

2. Present spotlight

// Fire-and-forget
Beacon.present("star")

// Multiple targets
Beacon.present("inbox", "compose", "settings")

// When you need the result
let result = await Beacon.presentAsync("star")
switch result {
case .tappedOutside: print("User dismissed")
case .tappedRegion(let id): print("User tapped: \(id)")
case .dismissed: print("Dismissed externally")
}

3. Dismiss

Beacon.dismiss()

Sequences

Chain steps into guided tours:

// Fire-and-forget
Beacon.Sequence.run {
    BeaconStep(targets: ["profile"])
    BeaconStep(targets: ["search"])
    BeaconStep(targets: ["settings"])
}

// When you need to await completion
await Beacon.Sequence.runAsync {
    BeaconStep(targets: ["profile"])
    BeaconStep(targets: ["settings"])
}
print("Onboarding complete!")

Configuration

Style

// Built-in presets
Beacon.style = .dimmed  // Default (55% opacity)
Beacon.style = .light   // 30% opacity
Beacon.style = .dark    // 75% opacity

// Custom
Beacon.style = BeaconStyle(color: .blue, opacity: 0.6)

Shapes

Image(systemName: "star")
    .beaconTarget("star")  // Default: circle

Button("Submit")
    .beaconTarget("submit", shape: .capsule)

RoundedRectangle(cornerRadius: 12)
    .beaconTarget("card", shape: .rectangle(cornerRadius: 12))

Usage Example

func handleFirstLaunch() async {
    let isFirstLaunch = await checkFirstLaunch()
    if isFirstLaunch {
        await Beacon.Sequence.runAsync {
            BeaconStep(targets: ["welcome"])
            BeaconStep(targets: ["main_feature"])
        }
        await markOnboardingComplete()
    }
}

Requirements

• iOS 18.4+
• Swift 6.2+
• Xcode 26.0+

Demo App

See BeaconDemo for an example app.

License

MIT License. See LICENSE for details.