/swiftui-webkit

name: swiftui-webkit
description: "Embeds and controls web content in SwiftUI with WebKit for SwiftUI, including WebView, WebPage, navigation policies, JavaScript execution, observable page state, link interception, local HTML or data loading, and custom URL schemes. Use when building iOS 26+ article/detail views, help centers, in-app documentation, or other embedded web experiences backed by HTML, CSS, and JavaScript."

SwiftUI WebKit

Embed and manage web content in SwiftUI using the native WebKit-for-SwiftUI APIs introduced for iOS 26, iPadOS 26, macOS 26, and visionOS 26. Use this skill when the app needs an integrated web surface, app-owned HTML content, JavaScript-backed page interaction, or custom navigation policy control.

Contents

• [Choose the Right Web Container](#choose-the-right-web-container)
• [Displaying Web Content](#displaying-web-content)
• [Loading and Observing with WebPage](#loading-and-observing-with-webpage)
• [Navigation Policies](#navigation-policies)
• [JavaScript Integration](#javascript-integration)
• [Local Content and Custom URL Schemes](#local-content-and-custom-url-schemes)
• [WebView Customization](#webview-customization)
• [Common Mistakes](#common-mistakes)
• [Review Checklist](#review-checklist)
• [References](#references)

Choose the Right Web Container

Use the narrowest tool that matches the job.

| Need | Default choice | |---|---| | Embedded app-owned web content in SwiftUI | `WebView` + `WebPage` | | iOS/iPadOS modal browsing with Safari behavior | `SFSafariViewController` | | macOS or visionOS browse-out behavior | `openURL` / default browser | | OAuth or third-party sign-in | `ASWebAuthenticationSession` | | Back-deploy below iOS 26 or use missing legacy-only WebKit features | `WKWebView` fallback |

Prefer `WebView` and `WebPage` for modern SwiftUI apps targeting iOS 26+ when the new API surface covers the feature. Apple’s WWDC25 guidance frames existing UIKit/AppKit WebKit wrappers in SwiftUI apps as good candidates to try migrating, not as a blanket mandate to delete every fallback.

Do not use embedded web views for OAuth. That stays an `ASWebAuthenticationSession` flow.

Displaying Web Content

Use the simple `WebView(url:)` form when the app only needs to render a URL and SwiftUI state drives navigation.

import SwiftUI
import WebKit

struct ArticleView: View {
    let url: URL

    var body: some View {
        WebView(url: url)
    }
}

Create a `WebPage` when the app needs to load requests directly, observe state, call JavaScript, or customize navigation behavior.

A `WebPage` can be associated with only one `WebView` at a time. Create separate `WebPage` instances for multiple visible web views.

@Observable
@MainActor
final class ArticleModel {
    let page = WebPage()

    func load(_ url: URL) async throws {
        for try await _ in page.load(URLRequest(url: url)) {
        }
    }
}

struct ArticleDetailView: View {
    @State private var model = ArticleModel()
    let url: URL

    var body: some View {
        WebView(model.page)
            .task {
                try? await model.load(url)
            }
    }
}

See [references/loading-and-observation.md](references/loading-and-observation.md) for full examples.

Loading and Observing with WebPage

`WebPage` is an `@MainActor` observable type. Use it when you need page state in SwiftUI.

Common loading entry points:

• `load(URLRequest)`
• `load(URL)`
• `load(html:baseURL:)`
• `load(_:mimeType:characterEncoding:baseURL:)`

Common observable properties:

• `title`
• `url`
• `isLoading`
• `estimatedProgress`
• `currentNavigationEvent`
• `backForwardList`

struct ReaderView: View {
    @State private var page = WebPage()

    var body: some View {
        WebView(page)
            .navigationTitle(page.title ?? "Loading")
            .overlay {
                if page.isLoading {
                    ProgressView(value: page.estimatedProgress)
                }
            }
            .task {
                do {
                    for try await _ in page.load(URLRequest(url: URL(string: "https://example.com")!)) {
                    }
                } catch {
                    // Handle load failure.
                }
            }
    }
}

When you need to react to every navigation, observe the navigation sequence rather than only checking a single property.

Task {
    do {
        for try await event in page.navigations {
            // Handle started, redirect, committed, or finished events.
        }
    } catch {
        // Handle WebPage.NavigationError or cancellation.
    }
}

See [references/loading-and-observation.md](references/loading-and-observation.md) for stronger patterns and the load-sequence examples.

Navigation Policies

Use `WebPage.NavigationDeciding` to allow, cancel, or customize navigations based on the request or response.

Typical uses:

• keep app-owned domains inside the embedded web view
• cancel external domains and hand them off with `openURL`
• intercept special callback URLs
• tune `NavigationPreferences`

@MainActor
final class ArticleNavigationDecider: WebPage.NavigationDeciding {
    var urlToOpenExternally: URL?

    func decidePolicy(
        for action: WebPage.NavigationAction,
        preferences: inout WebPage.NavigationPreferences
    ) async -> WKNavigationActionPolicy {
        guard let url = action.request.url else { return .allow }

        if url.host == "example.com" {
            return .allow
        }

        urlToOpenExternally = url
        return .cancel
    }
}

Keep app-level deep-link routing in the navigation skill. This skill owns navigation that happens inside embedded web content.

See [references/navigation-and-javascript.md](references/navigation-and-javascript.md) for complete patterns.

JavaScript Integration

Use `callJavaScript(_:arguments:in:contentWorld:)` to evaluate JavaScript functions against the page.