dpearson2699/tipkit

TipKit

Add feature discovery tips, contextual hints, and onboarding coach marks to iOS 17+ apps using Apple's TipKit framework. TipKit manages display frequency, eligibility rules, and persistence so tips appear at the right time and disappear once the user has learned the feature.

Contents

• Setup
• Defining Tips
• Displaying Tips
• Tip Rules
• Tip Actions
• Tip Groups
• Programmatic Control
• Common Mistakes
• Review Checklist
• References

Setup

Call Tips.configure() once in App.init, before any views render. This initializes the tips datastore and begins rule evaluation. Calling it later risks a race where tip views attempt to display before the datastore is ready.

import SwiftUI
import TipKit

@main
struct MyApp: App {
    init() {
        try? Tips.configure([
            .datastoreLocation(.applicationDefault)
        ])
    }

    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

DatastoreLocation Options

| Option | Use Case | |---|---| | .applicationDefault | Default location, app sandbox (most apps) | | .groupContainer(identifier:) | Share tips state across app and extensions | | .url(_:) | Custom file URL for full control over storage location |

CloudKit Sync

Sync tip state across a user's devices so they do not see the same tip on every device. Add the CloudKit container option alongside the datastore location.

try? Tips.configure([
    .datastoreLocation(.applicationDefault),
    .cloudKitContainer(.named("iCloud.com.example.app"))
])

Defining Tips

Conform a struct to the Tip protocol. Provide a title at minimum. Add message for supporting detail and image for a leading icon. Keep titles short and action-oriented because the tip appears as a compact callout.

import TipKit

struct FavoriteTip: Tip {
    var title: Text { Text("Pin Your Favorites") }
    var message: Text? { Text("Tap the heart icon to save items for quick access.") }
    var image: Image? { Image(systemName: "heart") }
}

Properties: title (required), message (optional detail), image (optional leading icon), actions (optional buttons), rules (optional eligibility conditions), options (display frequency, max count).

Lifecycle: Pending (rules unsatisfied) -> Eligible (all rules pass) -> Invalidated (dismissed, actioned, or programmatically removed). Once invalidated, a tip does not reappear unless the datastore is reset.

Displaying Tips

Inline Tips with TipView

Embed a TipView directly in your layout. It renders as a rounded card that appears and disappears with animation. Use for tips within scrollable content.

let favoriteTip = FavoriteTip()
var body: some View {
    VStack {
        TipView(favoriteTip)
        ItemListView()
    }
}

Popover Tips with .popoverTip()

Attach a tip as a popover anchored to any view. The framework draws an arrow from the popover to the anchor. Use for tips pointing to a specific control.

Button { toggleFavorite() } label: { Image(systemName: "heart") }
    .popoverTip(favoriteTip)

// Control arrow direction (omit to let system choose)
.popoverTip(favoriteTip, arrowEdge: .bottom)

Custom TipViewStyle

Create a custom style to control tip appearance across the app. Conform to TipViewStyle and implement makeBody(configuration:).

struct CustomTipStyle: TipViewStyle {
    func makeBody(configuration: Configuration) -> some View {
        HStack {
            configuration.image?
                .font(.title2)
                .foregroundStyle(.tint)

            VStack(alignment: .leading) {
                configuration.title
                    .font(.headline)
                configuration.message?
                    .font(.subheadline)
                    .foregroundStyle(.secondary)
            }
        }
        .padding()
    }
}

// Apply globally or per view
TipView(favoriteTip)
    .tipViewStyle(CustomTipStyle())

Tip Rules

Rules control when a tip becomes eligible. All rules in the rules array must pass before the tip displays. TipKit supports two rule types: parameter-based and event-based.

Parameter-Based Rules

Use @Parameter to track app state. The tip becomes eligible when the parameter value satisfies the rule condition.

struct FavoriteTip: Tip {
    @Parameter
    static var hasSeenList: Bool = false

    var title: Text { Text("Pin Your Favorites") }

    var rules: [Rule] {
        #Rule(Self.$hasSeenList) { $0 == true }
    }
}

// Set the parameter when the user reaches the list
FavoriteTip.hasSeenList = true

Event-Based Rules

Use Tips.Event to track user actions. Donate to the event each time the action occurs. The rule fires when the donation count or timing condition is met. This is ideal for tips that should appear after the user has performed an action several times without discovering a related feature.

struct ShortcutTip: Tip {
    static let appOpenedEvent = Tips.Event(id: "appOpened")

    var title: Text { Text("Try the Quick Action") }

    var rules: [Rule] {
        #Rule(Self.appOpenedEvent) { $0.donations.count >= 3 }
    }
}

// Donate each time the app opens
ShortcutTip.appOpenedEvent.donate()

Combining Multiple Rules

Place multiple rules in the array. All must pass (logical AND).

struct AdvancedTip: Tip {
    @Parameter
    static var isLoggedIn: Bool = false

    static let featureUsedEvent = Tips.Event(id: "featureUsed")

    var title: Text { Text("Unlock Advanced Mode") }

    var rules: [Rule] {
        #Rule(Self.$isLoggedIn) { $0 == true }
        #Rule(Self.featureUsedEvent) { $0.donations.count >= 5 }
    }
}

Display Frequency Options

Control how often tips appear using the options property.

struct DailyTip: Tip {
    var title: Text { Text("Daily Reminder") }

    var options: [TipOption] {
        MaxDisplayCount(3)                   // Show at most 3 times total
        IgnoresDisplayFrequency(true)        // Bypass global frequency limit
    }
}

Global display frequency is set at configuration time:

try? Tips.configure([
    .displayFrequency(.daily)  // .immediate, .hourly, .daily, .weekly, .monthly
])

With .daily, the system shows at most one tip per day across the entire app, unless a specific tip sets IgnoresDisplayFrequency(true).

Tip Actions

Add action buttons to a tip for direct interaction. Each action has an id and a label. Handle the action in the tip view's action handler.

struct FeatureTip: Tip {
    var title: Text { Text("Try the New Editor") }
    var message: Text? { Text("We added a powerful new editing mode.") }

    var actions: [Action] {
        Action(id: "open-editor", title: "Open Editor")
        Action(id: "learn-more", title: "Learn More")
    }
}

Handle actions in the view:

TipView(featureTip) { action in
    switch action.id {
    case "open-editor":
        navigateToEditor()
        featureTip.invalidate(reason: .actionPerformed)
    case "learn-more":
        showHelpSheet = true
    default:
        break
    }
}

Tip Groups

Use TipGroup to coordinate multiple tips within a single view. TipGroup ensures only one tip from the group displays at a time, preventing tip overload. Tips display in priority order.

struct OnboardingView: View {
    let tipGroup = TipGroup(.ordered) {
        WelcomeTip()
        NavigationTip()
        ProfileTip()
    }

    var body: some View {
        VStack {
            if let currentTip = tipGroup.currentTip {
                TipView(currentTip)
            }

            Button("Next") {
                tipGroup.currentTip?.invalidate(reason: .actionPerformed)
            }
        }
    }
}

Priority Options

| Initializer | Behavior | |---|---| | .ordered | Tips display in the order they are listed |

When the current tip is invalidated, the next eligible tip in the group becomes currentTip.

Programmatic Control

Invalidating Tips

Call invalidate(reason:) when the user performs the discovered action or when the tip is no longer relevant.

let tip = FavoriteTip()
tip.invalidate(reason: .actionPerformed)

| Reason | When to Use | |---|---| | .actionPerformed | User performed the action the tip describes | | .displayCountExceeded | Tip hit its maximum display count | | .tipClosed | User explicitly dismissed the tip |

Testing Utilities

TipKit provides static methods to control tip visibility during development and testing. Gate these behind #if DEBUG or ProcessInfo checks so they never run in production builds.

#if DEBUG
// Show all tips regardless of rules (useful during development)
Tips.showAllTipsForTesting()

// Show only specific tips
Tips.showTipsForTesting([FavoriteTip.self, ShortcutTip.self])

// Hide all tips (useful for UI tests that do not involve tips)
Tips.hideAllTipsForTesting()

// Reset the datastore (clears all tip state, invalidations, and events)
try? Tips.resetDatastore()
#endif

Using ProcessInfo for Test Schemes

if ProcessInfo.processInfo.arguments.contains("--show-all-tips") {
    Tips.showAllTipsForTesting()
}

Pass --show-all-tips as a launch argument in the Xcode scheme for development builds.

Common Mistakes

DON'T: Call Tips.configure() anywhere except App.init

Calling Tips.configure() in a view's onAppear or task modifier creates a race condition where tip views try to render before the datastore is ready, causing missing or flickering tips.

// WRONG
struct ContentView: View {
    var body: some View {
        Text("Hello")
            .task { try? Tips.configure() }  // Too late, views already rendered
    }
}

// CORRECT
@main struct MyApp: App {
    init() { try? Tips.configure() }
    var body: some Scene { WindowGroup { ContentView() } }
}

DON'T: Show too many tips at once

Displaying multiple tips simultaneously overwhelms users and dilutes the impact of each tip. Users learn to ignore them.

// WRONG: Three tips visible at the same time
VStack {
    TipView(tipA)
    TipView(tipB)
    TipView(tipC)
}

// CORRECT: Use TipGroup to sequence them
let group = TipGroup(.ordered) { TipA(); TipB(); TipC() }
if let currentTip = group.currentTip {
    TipView(currentTip)
}

DON'T: Forget to invalidate tips after the user performs the action

If a tip says "Tap the star to favorite" and the user taps the star but the tip remains, it erodes trust in the UI.

// WRONG: Tip stays visible after user acts
Button("Favorite") { toggleFavorite() }
    .popoverTip(favoriteTip)

// CORRECT: Invalidate on action
Button("Favorite") {
    toggleFavorite()
    favoriteTip.invalidate(reason: .actionPerformed)
}
.popoverTip(favoriteTip)

DON'T: Leave testing tips enabled in production

Tips.showAllTipsForTesting() bypasses all rules and frequency limits. Shipping this in production means every user sees every tip immediately.

// WRONG: Always active
Tips.showAllTipsForTesting()

// CORRECT: Gated behind DEBUG
#if DEBUG
Tips.showAllTipsForTesting()
#endif

DON'T: Make tip titles too long

Long titles get truncated or wrap awkwardly in the compact tip callout. Put the key action in the title and supporting context in the message.

// WRONG
var title: Text { Text("You can tap the heart button to save this item to your favorites list") }

// CORRECT
var title: Text { Text("Save to Favorites") }
var message: Text? { Text("Tap the heart icon to keep items for quick access.") }

DON'T: Use tips for critical information

Users can dismiss tips at any time and they do not reappear. Never put essential instructions or safety information in a tip.

// WRONG: Critical info in a dismissible tip
struct DataLossTip: Tip {
    var title: Text { Text("Unsaved changes will be lost") }
}

// CORRECT: Use an alert or inline warning for critical information
// Reserve tips for feature discovery and progressive disclosure

Review Checklist

• [ ] Tips.configure() called in App.init, before any views render
• [ ] Each tip has a clear, concise title (action-oriented, under ~40 characters)
• [ ] Tips invalidated when the user performs the discovered action
• [ ] Rules set so tips appear at the right time (not immediately on first launch for all tips)
• [ ] TipGroup used when multiple tips exist in one view
• [ ] Testing utilities (showAllTipsForTesting, resetDatastore) gated behind #if DEBUG
• [ ] CloudKit sync configured if the app supports multiple devices
• [ ] Display frequency set appropriately (.daily or .weekly for most apps)
• [ ] Tips used for feature discovery only, not for critical information
• [ ] Custom TipViewStyle applied consistently if the default style does not match the app design
• [ ] Tip actions handled and tip invalidated in the action handler
• [ ] Event donations placed at the correct user action points
• [ ] Ensure custom Tip types are Sendable; configure Tips on @MainActor

References

• See references/tipkit-patterns.md for complete implementation patterns including custom styles, event-based rules, tip groups, testing strategies, onboarding flows, and SwiftUI preview configuration.