SwiftUI-Onboarding Documentation

The library provides three distinct layout styles via WelcomeScreen factory methods:

• .apple(...): An Apple-style hero layout featuring a list of features and continue controls. Requires appIcon, appDisplayName, and features.
• .modern(...): A card-based feature layout with inline links for Terms of Service and Privacy Policy. Requires appIcon, appDisplayName, features, termsOfServiceURL, and privacyPolicyURL.
• .hero(...): A hero-focused layout designed for product previews. It includes a language picker, custom hero content, a Call to Action (CTA), and a sign-in action. Requires title, languageOptions, and heroContent.

// Modern Layout Example
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.")
    ],
    termsOfServiceURL: URL(string: "https://example.com/terms")!,
    privacyPolicyURL: URL(string: "https://example.com/privacy")!
)

// Hero Layout Example
let hero = WelcomeScreen.hero(
    accentColor: .mint,
    title: "Track every meal with AI",
    languageOptions: [
        OnboardingLanguageOption(identifier: "en", displayName: "English", flag: "🇺🇸", shortName: "EN")
    ],
    signInAction: { /* Sign in flow */ },
    languageSelectionAction: { language in /* Handle language change */ }
) {
    Image("WelcomeHero").resizable().scaledToFit()
}

SwiftUI-Onboarding provides several ways to manage whether a user has seen the onboarding:

Custom AppStorage Key

By default, the library uses a built-in key. To use your own, pass a binding to an @AppStorage property to the .showOnboardingIfNeeded(storage:) modifier.

Manual State Management

You can access the library's default storage key using the .onboardingKey extension to manually reset or check the onboarding state.

Custom Continue Action

You can wrap the markComplete closure in a custom action to perform side effects (like analytics) before finishing.

// Custom Storage
@AppStorage("myCustomOnboardingKey") private var customOnboardingState = false

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

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

To implement a basic onboarding flow, follow these two steps:

1. Create a WelcomeScreen configuration

Define a static configuration (e.g., using the .apple style) that includes your app's icon, name, and a list of FeatureInfo objects.

2. Attach the onboarding to your root view

Use the .showOnboardingIfNeeded modifier on your main view. This modifier provides a markComplete closure which you must pass to the WelcomeScreen via the .with(continueAction:) method to ensure the onboarding state is saved when the user finishes.

Requirements:

• iOS 18.0+ or macOS 15.0+
• Swift 6.0+

import Onboarding
import SwiftUI

// 1. Define configuration
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."
            )
        ],
        privacyPolicyURL: URL(string: "https://example.com/privacy")!,
        titleSectionAlignment: .center
    )
}

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

Configuration details for the different WelcomeScreen styles.

### AppleWelcomeScreen.Configuration
- `accentColor`: Primary color (default: `.blue`)
- `appDisplayName`: App's display name
- `appIcon`: The app icon image
- `features`: Array of `FeatureInfo` objects
- `privacyPolicyURL`: URL for privacy text
- `titleSectionAlignment`: `.leading`, `.center`, or `.trailing`

### FeatureInfo
- `image`: Icon (e.g., SF Symbol)
- `title`: Brief title
- `content`: Detailed description

### HeroWelcomeScreen.Configuration
- `title`: Hero title
- `languageOptions`: Array of `OnboardingLanguageOption`
- `heroContent`: View for the hero section
- `signInAction`: Closure for sign-in flow
- `languageSelectionAction`: Closure for language selection
- `ctaTitle`: Call to action title
- `accountPrompt`: Account prompt text
- `signInTitle`: Sign in button title
- `textBundle`: Text bundle for localization
- `selectedLanguageStorageKey`: Key for language storage
- `defaultLanguageIdentifier`: Default language ID