SwiftUI-Onboarding

Description

SwiftUI-Onboarding is a SwiftUI library that provides an Apple-like app onboarding experience.

Features

• ✅ Swift 6.0 Compatible - Built for the latest Swift standards
• 🌍 Multi-language Support - 10 languages included out of the box
• ♿ Accessibility First - Full Dynamic Type support and accessibility features
• 🎨 Highly Customizable - Flexible configuration options
• 📱 Cross-platform - iOS and macOS support
• 🔄 Modern SwiftUI - Uses latest SwiftUI APIs and patterns
• 💾 Automatic State Management - Built-in AppStorage integration
• 🌗 Light and Dark Mode - Fully supports both light and dark appearance

Table of Contents

• Requirements
• Installation
• Supported Languages
• Usage
  • Basic Setup
  • Advanced Usage
• Configuration Options
• Contributing
• License

Requirements

• iOS: 18.0 or later
• macOS: 15.0 or later
• Swift: 6.0 or later

Installation

You can install Onboarding using the Swift Package Manager.

1. In Xcode, select "File" > "Add Package Dependencies"
2. Copy & paste the following into the "Search or Enter Package URL" search bar: https://github.com/Sedlacek-Solutions/SwiftUI-Onboarding.git
3. Xcode will fetch the repository & the "Onboarding" library will be added to your project

Supported Languages

Onboarding includes localization for the following languages:

• English (en)
• German (de)
• Spanish (es)
• French (fr)
• Italian (it)
• Japanese (ja)
• Korean (ko)
• Portuguese (pt)
• Russian (ru)
• Chinese Simplified (zh-Hans)
• Bulgarian (bg)

Usage

Basic Setup

1. Create your onboarding configuration:

import Onboarding
import SwiftUI

extension WelcomeScreen {
    static let production = WelcomeScreen.apple(
        accentColor: .blue,
        appDisplayName: "My Amazing App",
        appIcon: Image("AppIcon"),
        features: [
            FeatureInfo(
                image: Image(systemName: "star.fill"),
                title: "Amazing Features",
                content: "Discover powerful tools that make your life easier."
            ),
            FeatureInfo(
                image: Image(systemName: "shield.fill"),
                title: "Privacy First",
                content: "Your data stays private and secure on your device."
            ),
            FeatureInfo(
                image: Image(systemName: "bolt.fill"),
                title: "Lightning Fast",
                content: "Optimized performance for the best user experience."
            )
        ],
        privacyPolicyURL: URL(string: "https://example.com/privacy"),
        titleSectionAlignment: .center
    )
}

WelcomeScreen conforms to View; render it directly inside the onboarding modifier and inject the continue action via .with(continueAction:).

2. Add onboarding to your app's root view:

import Onboarding
import SwiftUI

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .showOnboardingIfNeeded { markComplete in
                    WelcomeScreen.production
                        .with(continueAction: markComplete)
                }
        }
    }
}

Advanced Usage

Custom Continue Action

You can provide a custom action to perform when the user taps "Continue":

ContentView()
    .showOnboardingIfNeeded { markComplete in
        WelcomeScreen.production.with(continueAction: {
            // Perform analytics, API calls, etc.
            Analytics.track("onboarding_completed")
            markComplete()
        })
    }

Custom Storage

Use a custom AppStorage key for tracking onboarding state:

@AppStorage("myCustomOnboardingKey") private var customOnboardingState = false

ContentView()
    .showOnboardingIfNeeded(storage: $customOnboardingState) { markComplete in
        WelcomeScreen.production
            .with(continueAction: markComplete)
    }

Manual State Management

Access the convenient AppStorage extension for manual control:

import Onboarding

struct SettingsView: View {
    @AppStorage(.onboardingKey) private var isOnboardingCompleted = false
    
    var body: some View {
        VStack {
            Button("Reset Onboarding") {
                isOnboardingCompleted = false
            }
        }
    }
}

Presenting Onboarding as a Modal Sheet

Present onboarding as a sheet above your main content, instead of replacing the root view:

import Onboarding
import SwiftUI

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .presentOnboardingIfNeeded { markComplete in
                    WelcomeScreen.production
                        .with(continueAction: markComplete)
                }
        }
    }
}

Modern Welcome Screen

Use the modern layout with feature cards and inline terms/privacy links:

let modern = WelcomeScreen.modern(
    accentColor: .mint,
    appDisplayName: "My Amazing App",
    appIcon: Image("AppIcon"),
    features: [
        FeatureInfo(image: Image(systemName: "bolt.fill"), title: "Fast", content: "Optimized for speed."),
        FeatureInfo(image: Image(systemName: "shield.fill"), title: "Secure", content: "Your data stays private.")
    ],
    termsOfServiceURL: URL(string: "https://example.com/terms")!,
    privacyPolicyURL: URL(string: "https://example.com/privacy")!
)

ContentView()
    .showOnboardingIfNeeded { markComplete in
        modern.with(continueAction: markComplete)
    }

Multi-Screen Onboarding Flows

Need more than a single welcome screen? Build whatever flow you need inside the onboarding builder and call markComplete() when you're done.

.showOnboardingIfNeeded { markComplete in
    NavigationStack {
        CustomTutorialView(onFinish: markComplete)
    }
}

Notifications Permissions Screen

Use the built-in notifications priming screen to request authorization and continue on success:

import Onboarding
import SwiftUI

PermissionsScreen.notifications(
    accentColor: .blue,
    subtitle: "Stay up to date with important alerts.",
    appIcon: Image("AppIcon"),
    authorizationOptions: [.alert, .badge, .sound],
    allowAction: {
        // Continue your flow after authorization succeeds.
    },
    failureAction: { granted, error in
        // Handle declines or errors.
    }
)

Configuration Options

WelcomeScreen

• .apple(AppleWelcomeScreen.Configuration): Apple-style hero layout with feature list and continue controls.
  • Convenience factory: WelcomeScreen.apple(...) produces the Apple-style welcome screen configuration you see in the examples.
  • Required: appIcon, appDisplayName, features
  • Optional: accentColor, privacyPolicyURL, titleSectionAlignment
• .modern(ModernWelcomeScreen.Configuration): Card-based feature layout with inline terms/privacy links.
  • Required: appIcon, appDisplayName, features, termsOfServiceURL, privacyPolicyURL
  • Optional: accentColor, titleSectionAlignment

PermissionsScreen

• .notifications(NotificationsPriming.Configuration): Notifications priming screen with a system permission request.
  • Required: subtitle
  • Optional: accentColor, title, appIcon, authorizationOptions, allowAction, skipAction, failureAction

AppleWelcomeScreen.Configuration

• accentColor: Primary color used throughout the onboarding (default: .blue)
• appDisplayName: Your app's display name shown in the welcome section
• appIcon: The app icon image
• features: Array of FeatureInfo objects to showcase
• privacyPolicyURL: URL to open when the privacy text is tapped
• titleSectionAlignment: Horizontal alignment for the title (.leading, .center, .trailing)

FeatureInfo

• image: Icon representing the feature (typically SF Symbols)
• title: Brief, descriptive title
• content: Detailed description of the feature

Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

SwiftUI-Onboarding is available under the MIT license. See the LICENSE file for more info.