Tipkit

TipKit

Use TipKit for small, contextual feature-discovery moments: inline tips, popover tips, rule-gated education, and lightweight coach marks. Keep generic SwiftUI architecture, navigation, layout, and long first-run onboarding flows in their sibling skills unless TipKit presentation is the core issue.

Contents

• Availability
• Configure TipKit
• Design Good Tips
• Define Tips
• Present Tips
• Rules and Events
• Options and Invalidation
• Actions and Styles
• Tip Groups
• Testing
• Common Mistakes
• Review Checklist
• References

Availability

TipKit's core Tip, TipView, popoverTip, rules, events, options, and testing overrides are available on iOS 17+, iPadOS 17+, macOS 14+, tvOS 17+, watchOS 10+, and visionOS 1+.

Gate newer APIs explicitly:

Configure TipKit

Call Tips.configure(_:) once during app initialization, before any tip can display. Do not configure TipKit from a view's onAppear or .task.

import SwiftUI
import TipKit

@main
struct MyApp: App {
    init() {
        do {
            try Tips.configure([
                .datastoreLocation(.applicationDefault),
                .displayFrequency(.daily)
            ])
        } catch {
            assertionFailure("TipKit configuration failed: \(error)")
        }
    }

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

Use .datastoreLocation(.groupContainer(identifier:)) only when an app and extension or app-group members intentionally share tip state. Keep option settings consistent across app-group members because TipKit persists option state with the tip record.

CloudKit Sync

Use CloudKit sync only on iOS 18+ and later. Enable iCloud + CloudKit and Background Modes > Remote notifications, then pass a container:

try Tips.configure([
    .cloudKitContainer(.named("iCloud.com.example.app.tips"))
])

Prefer a dedicated container with a .tips suffix. .automatic uses the first entitled .tips container when present, then falls back to the primary container.

Design Good Tips

Tips are small, transient help. Use them for features people can understand and try in a few simple steps. If the flow needs a long explanation, multiple screens, or critical safety/error information, use a tutorial, alert, inline warning, or onboarding flow instead.

Follow HIG-aligned defaults:

• Keep titles short, direct, and action-oriented.
• Use one or two sentences; avoid promotional or unrelated copy.
• Place tips near the feature they explain.
• Prefer inline tips when hiding nearby UI would interrupt the task.
• Prefer popover tips when preserving the current layout matters and the tip can point to a specific control.
• Use rules and display frequency so only the right audience sees each tip.
• Avoid repeating an icon in the tip when the popover already points to that icon.

Define Tips

Tip conforms to Identifiable and Sendable. Provide title at minimum; add message, image, actions, rules, options, and id only when they improve the feature-discovery moment.

import TipKit

struct FavoriteTip: Tip {
    var title: Text { Text("Save to Favorites") }
    var message: Text? { Text("Tap the heart to keep items for quick access.") }
    var image: Image? { Image(systemName: "heart.fill") }
}

By default, TipKit uses the tip type name as id. Override id for reusable tips whose persisted state should vary by content:

struct NewItemTip: Tip {
    let itemID: Item.ID

    var id: String { "NewItemTip-\(itemID)" }
    var title: Text { Text("New Item Available") }
}

Use stable, concrete identifiers. Do not derive IDs from transient copy or unstable ordering.

Present Tips

Use TipView for inline tips:

let favoriteTip = FavoriteTip()

VStack {
    TipView(favoriteTip, arrowEdge: .bottom)
    ItemListView()
}

Use .popoverTip when the tip should point to a control:

Button {
    toggleFavorite()
    favoriteTip.invalidate(reason: .actionPerformed)
} label: {
    Image(systemName: "heart")
}
.popoverTip(favoriteTip, arrowEdge: .top)

Rules and Events

Rules are ANDed together. A tip becomes eligible only when every rule passes.

Use @Parameter for persisted app state:

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

    var title: Text { Text("Save to Favorites") }

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

Use Tips.Event for repeated user actions. TipKit queries the most recent 1000 donations by default, so keep event rules bounded and intentional.

struct ShortcutTip: Tip {
    static let manualSaveEvent = Tips.Event(id: "manualSave")

    var title: Text { Text("Save Faster") }

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

ShortcutTip.manualSaveEvent.sendDonation()

For richer event rules, define Tips.Event<DonationInfo> where DonationInfo: Codable, Sendable. Keep donation payloads small.

Group related event definitions in a shared namespace when several tips use the same events; event IDs are the persistence boundary, so collisions can create confusing eligibility.

Options and Invalidation

Use options sparingly; frequency and invalidation rules are part of the tip's persisted behavior.

struct DailyTip: Tip {
    var title: Text { Text("Try Filters") }

    var options: [any TipOption] {
        MaxDisplayCount(3)
        IgnoresDisplayFrequency(false)
    }
}

MaxDisplayDuration is iOS 18+. It counts cumulative display time and has a minimum continuous display duration before automatic invalidation can occur. Do not use it as a replacement for explicit invalidate(reason:) when the app knows the taught action or ordered step is complete.

Call invalidate(reason:) when the user performs the discovered action or the tip is no longer relevant. Invalidation is permanent until the datastore is reset or, on iOS 26+, the specific tip calls await resetEligibility().

favoriteTip.invalidate(reason: .actionPerformed)

Use .tipClosed for explicit dismissal and .displayCountExceeded or .displayDurationExceeded only when describing automatic invalidation outcomes.

Actions and Styles

Add Action buttons when the user needs a direct route to settings, more information, or a setup flow.

struct FeatureTip: Tip {
    var title: Text { Text("Try the New Editor") }

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

TipView(FeatureTip()) { action in
    switch action.id {
    case "open-editor":
        openEditor()
    case "learn-more":
        showHelp()
    default:
        break
    }
}

For custom appearance, prefer TipViewStyle.Configuration values over reading directly from a concrete tip instance. That preserves labels, handlers, and modifiers applied to the TipView.

struct CompactTipStyle: TipViewStyle {
    func makeBody(configuration: Configuration) -> some View {
        HStack(alignment: .top) {
            configuration.image?
            VStack(alignment: .leading) {