Beacon

SwiftUI spotlight overlay framework

Step-by-step tour	Auto-advancing tutorial
RocketSim_Recording_iPhone_17_Pro_6.3_2026-04-01_14.44.47.mp4	RocketSim_Recording_iPhone_17_Pro_6.3_2026-04-01_14.45.10.mp4

Features

• Single-line spotlight presentation
• Declarative sequence builder with step navigation
• Tooltip/accessory views on cutouts with flexible positioning
• 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!")

Tooltips

Attach custom views to spotlight cutouts:

Simple tooltip

Beacon.Sequence.run {
    BeaconStep(targets: [
        BeaconTarget("star", alignment: .top) {
            Text("Tap to favorite")
        }
    ])
    BeaconStep(targets: ["settings"])  // no tooltip
}

Per-target tooltips

Use BeaconTarget for per-cutout configuration:

Beacon.present(
    BeaconTarget("inbox", alignment: .top) {
        Label("3 new messages", systemImage: "envelope")
    },
    BeaconTarget("compose", alignment: .bottom) {
        Text("Write a new message")
    },
    "settings"  // no tooltip
)

Positioning

Tooltips use SwiftUI's native Alignment (.top, .bottom, .leading, .trailing, and all 9 built-in positions). Fine-tune with offset:

BeaconStep(targets: [
    BeaconTarget("star", alignment: .top, offset: CGSize(width: 0, height: -8)) {
        Text("Tap to favorite")
    }
])

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.