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()

App.init

import SwiftUI
import TipKit

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

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

DatastoreLocation Options

.applicationDefault

.groupContainer(identifier:)

.url(_:)

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

title

message

image

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

message

image

actions

rules

options

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

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

makeBody(configuration:)

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

            VStack(alignment: .leading, spacing: 4) {
                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

Parameter-Based Rules

Use

@Parameter

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

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

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

IgnoresDisplayFrequency(true)

Tip Actions

Add action buttons to a tip for direct interaction. Each action has an

id

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

TipGroup

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

.ordered

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

currentTip

Programmatic Control

Invalidating Tips

Call

invalidate(reason:)

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

.actionPerformed

.displayCountExceeded

.tipClosed

Testing Utilities

TipKit provides static methods to control tip visibility during development and testing. Gate these behind

#if DEBUG

ProcessInfo

#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

Common Mistakes

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

Calling

Tips.configure()

onAppear

task

// 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()

// 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.