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

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(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 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
how to use tipkit
CursorClaude CodeClineCodexWindsurfGooseGitHub CopilotVS CodeGemini CLIKiloOpencodeKimi CLIRoo ClineAiderContinueZedBolt.newLovablev0Replit AgentSweepSmol DeveloperDevinCavemanAmpAntigravity
How to use tipkit on Cursor
AI-first code editor with Composer
1
Prerequisites
Before installing skills in Cursor, ensure your development environment meets these requirements:
›Cursor installed and configured on your development machine
›Node.js version 16.0+ with npm package manager (verify with node --version)
›Active project directory or workspace where you want to add tipkit
2
Execute installation command
Execute the skills CLI command in your project's root directory to begin installation:
$npx skills add https://github.com/dpearson2699/swift-ios-skills --skill tipkitcopy
The skills CLI fetches tipkit from GitHub repository dpearson2699/swift-ios-skills and configures it for Cursor.
3
Select Cursor when prompted
The CLI will show a list of available agents. Use arrow keys to navigate and space to select Cursor:
◆ Which agents do you want to install to?
│
│ ── Universal (.agents/skills) ── always included ────
│   • Amp
│   • Antigravity
│   • Cline
│   • Codex
│ ●Cursor(selected)
│   • Cursor
│   • Windsurf
4
Verify installation
Confirm successful installation by checking the skill directory location:
.cursor/skills/tipkit
Reload or restart Cursor to activate tipkit. Access the skill through slash commands (e.g., /tipkit) or your agent's skill management interface.
⚠
Security & Verification Notice
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your development environment. Always verify the publisher's identity, review recent commits, and test in isolated environments before production deployment.
Additional Resources
›View source code on GitHub›Skills CLI documentation›Learn more about Cursor›What are agent skills?