Swiftui Webkit

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
• Displaying Web Content
• Loading and Observing with WebPage
• Navigation Policies
• JavaScript Integration
• Local Content and Custom URL Schemes
• WebView Customization
• Common Mistakes
• Review Checklist
• References

Choose the Right Web Container

Use the narrowest tool that matches the job.

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 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 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 for complete patterns.

JavaScript Integration

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

Pass a JavaScript function body, not a wrapped function declaration or call expression. Prefer arguments for Swift-provided values instead of interpolating untrusted strings into the script.

let script = """
const headings = [...document.querySelectorAll('h1, h2')];
return headings.map(node => ({
    id: node.id,
    text: node.textContent?.trim()
}));
"""

let result = try await page.callJavaScript(script)
let headings = result as? [[String: Any]] ?? []

You can pass values through the arguments dictionary and cast the returned Any into the Swift type you actually need.

let result = try await page.callJavaScript(
    "return document.getElementById(sectionID)?.getBoundingClientRect().top ?? null;",
    arguments: ["sectionID": selectedSectionID]
)

Handle empty and JavaScript null results deliberately: no explicit return produces nil, while an explicit JavaScript null returns NSNull.

Important boundary: the native SwiftUI WebKit API clearly supports Swift-to-JavaScript calls, but it does not expose an obvious direct replacement for WKScriptMessageHandler. If you need coarse JS-to-native signaling, a custom navigation or callback-URL pattern can work, but document it as a workaround pattern, not a guaranteed one-to-one replacement.

See references/navigation-and-javascript.md.

Local Content and Custom URL Schemes

Use WebPage.Configuration and URLSchemeHandler when the app needs bundled HTML, offline documents, or app-provided resources under a custom scheme.

var configuration = WebPage.Configuration()
configuration.urlSchemeHandlers[URLScheme("docs")!] = DocsSchemeHandler(bundle: .main)

let page = WebPage(configuration: configuration)
for try await _ in page.load(URL(string: "docs://article/welcome")!) {
}

Use this for:

• bundled documentation or article content
• offline HTML/CSS/JS assets
• app-owned resource loading under a custom scheme

Do not overuse custom schemes for normal remote content. Prefer standard HTTPS for server-hosted pages.

See references/local-content-and-custom-schemes.md.

WebView Customization

Use WebView modifiers to match the intended browsing experience.

Useful modifiers and related APIs:

• webViewBackForwardNavigationGestures(_:)
• findNavigator(isPresented:)
• webViewScrollPosition(_:)
• webViewOnScrollGeometryChange(...)

Apply them only when the user experience needs them.

• Enable back/forward gestures when people are likely to visit multiple pages.
• Add Find in Page when the content is document-like.
• Sync scroll position only when the app has a sidebar, table of contents, or other explicit navigation affordance.

Apple’s HIG also applies here: support back/forward navigation when appropriate, but do not turn an app web view into a general-purpose browser.

Common Mistakes

• Using WKWebView wrappers by default in an iOS 26+ SwiftUI app instead of starting with WebView and WebPage
• Using embedded web views for OAuth instead of ASWebAuthenticationSession
• Reaching for WebPage only after building a plain WebView(url:) path that now needs state, JS, or navigation control
• Treating callJavaScript as a direct replacement for WKScriptMessageHandler
• Passing a callable JavaScript wrapper to callJavaScript instead of only the function body
• Iterating page.navigations without try/catch even though navigation failure terminates the sequence by throwing
• Binding the same WebPage to multiple visible WebView values
• Keeping all links inside the app when external domains should open outside the embedded surface
• Treating SFSafariViewController as the cross-platform browse-out answer on macOS or visionOS instead of using default-browser/openURL behavior
• Building a browser-style app shell around WebView instead of a focused embedded experience
• Using custom URL schemes for content that should just load over HTTPS
• Forgetting that WebPage is main-actor-isolated

Review Checklist

• [ ] WebView and WebPage are the default path for iOS 26+ SwiftUI web content
• [ ] ASWebAuthenticationSession is used for auth flows instead of embedded web views
• [ ] WebPage is used whenever the app needs state observation, JS calls, or policy control
• [ ] Navigation policies only intercept the URLs the app actually owns or needs to reroute
• [ ] External domains open externally when appropriate
• [ ] JavaScript return values are cast defensively to concrete Swift types
• [ ] callJavaScript uses a function body and passes Swift values through arguments
• [ ] page.navigations loops use for try await and handle thrown navigation errors
• [ ] Each visible WebView(page) owns a distinct WebPage
• [ ] Custom URL schemes are used only for real app-owned resources
• [ ] Back/forward gestures or controls are enabled when multi-page browsing is expected
• [ ] SFSafariViewController is limited to iOS/iPadOS Safari-style modal browsing; macOS and visionOS browse-out flows use platform default browser behavior
• [ ] The web experience adds focused native value instead of behaving like a thin browser shell
• [ ] Fallback to WKWebView is justified by deployment target or missing API needs

References

• Loading and observation: references/loading-and-observation.md
• Navigation and JavaScript: references/navigation-and-javascript.md
• Local content and custom schemes: references/local-content-and-custom-schemes.md
• Migration and fallbacks: references/migration-and-fallbacks.md

Loading and Observation

Contents

• Simple WebView(url:)
• Controlled WebPage loading
• Observing progress and title
• Observing navigation events
• Ephemeral pages and custom user agents

Simple WebView(url:)

Use WebView(url:) when the app only needs to display a URL and does not need explicit page control.

import SwiftUI
import WebKit

struct MarketingPageView: View {
    let url: URL

    var body: some View {
        WebView(url: url)
            .webViewBackForwardNavigationGestures(.enabled)
    }
}

This is the lowest-friction path for embedded content.

Controlled WebPage loading

Create a WebPage when the app needs to drive loading itself.

Keep page ownership one-to-one with presentation: a WebPage can be bound to only one visible WebView at a time.

@Observable
@MainActor
final class ArticleModel {
    let page = WebPage()
    var lastError: String?

    func load(_ url: URL) async {
        do {
            for try await _ in page.load(URLRequest(url: url)) {
            }
        } catch {
            lastError = error.localizedDescription
        }
    }
}

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

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

You can also load:

• for try await _ in page.load(url) { }
• for try await _ in page.load(html: htmlString, baseURL: baseURL) { }
• for try await _ in page.load(data, mimeType: "text/html", characterEncoding: "utf-8", baseURL: baseURL) { }

Use the async sequence returned by a load call when you need to track that specific programmatic navigation. Use page.navigations for a broader stream covering both user and programmatic navigations.

Observing progress and title

WebPage is observable, so SwiftUI can bind directly to its state.

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

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

Useful properties:

• title
• url
• isLoading
• estimatedProgress
• themeColor
• hasOnlySecureContent
• backForwardList

Observing navigation events

Use currentNavigationEvent for a lightweight current-state view. Use navigations to observe the full sequence of navigation events.

@MainActor
func observeNavigations(for page: WebPage) {
    Task {
        do {
            for try await event in page.navigations {
                switch event {
                case .startedProvisionalNavigation:
                    print("Navigation started")
                case .receivedServerRedirect:
                    print("Navigation redirected")
                case .committed:
                    print("Navigation committed")
                case .finished:
                    print("Navigation finished")
                @unknown default:
                    break
                }
            }
        } catch {
            print("Navigation failed: \(error)")
        }
    }
}

This is the right place to trigger follow-up work like parsing headings after a finished navigation. Treat thrown errors as normal navigation failures such as invalid URLs, provisional navigation failures, page closure, or web content process termination.

Ephemeral pages and custom user agents

Use WebPage.Configuration when you need a nonpersistent page, custom user agent, or tighter loading rules.

@MainActor
func makeMetadataPage() -> WebPage {
    var configuration = WebPage.Configuration()
    configuration.loadsSubresources = false
    configuration.defaultNavigationPreferences.allowsContentJavaScript = false
    configuration.websiteDataStore = .nonPersistent()

    let page = WebPage(configuration: configuration)
    page.customUserAgent = "MetadataBot/1.0"
    return page
}

Use nonpersistent pages when you want an isolated web session or metadata fetch path without shared cookies or long-lived website data.

Local Content and Custom URL Schemes

Contents

• When to use custom schemes
• Registering a scheme handler
• Returning responses and data
• Loading bundled content
• Cancellation behavior

When to use custom schemes

Use URLSchemeHandler when the app owns the content source and needs WebKit to resolve resources under a custom scheme.

Good fits:

• bundled HTML, CSS, and JavaScript assets
• offline documentation
• app-owned rich content assembled on device

Do not use custom schemes for ordinary server-hosted pages that should just load over HTTPS.

Registering a scheme handler

import Foundation
import WebKit

@MainActor
func makeDocsPage() -> WebPage {
    var configuration = WebPage.Configuration()
    configuration.urlSchemeHandlers[URLScheme("docs")!] = DocsSchemeHandler(bundle: .main)
    return WebPage(configuration: configuration)
}

If WebKit already owns a scheme, URLScheme("https") style registration does not work. Use a genuinely custom scheme.

Returning responses and data

A handler replies with an async sequence of intermixed response and data values.

struct DocsSchemeHandler: URLSchemeHandler {
    let bundle: Bundle

    func reply(for request: URLRequest) -> some AsyncSequence<URLSchemeTaskResult> {
        AsyncStream { continuation in
            guard let url = request.url,
                  let fileURL = bundle.url(forResource: url.host, withExtension: "html", subdirectory: "Docs")
            else {
                continuation.finish()
                return
            }

            do {
                let data = try Data(contentsOf: fileURL)
                let response = URLResponse(
                    url: url,
                    mimeType: "text/html",
                    expectedContentLength: data.count,
                    textEncodingName: "utf-8"
                )
                continuation.yield(.response(response))
                continuation.yield(.data(data))
                continuation.finish()
            } catch {
                continuation.finish()
            }
        }
    }
}

Keep MIME type and encoding aligned with the actual content you serve.

Loading bundled content

Once registered, load the custom URL like any other page.

let page = makeDocsPage()
for try await _ in page.load(URL(string: "docs://welcome")!) {
}

This works well when the HTML references other assets with the same custom scheme.

Cancellation behavior

If WebKit no longer needs the resource, it cancels the task producing the async sequence. Treat cancellation as normal behavior when:

• the user navigates away
• the page reloads before the previous request completes
• the resource is no longer needed by the page

Do not build logic that assumes every scheme-handled request runs to completion.

Migration and Fallbacks

Contents

• Migration goal
• Decision guide
• Migrating from WKWebView wrappers
• Incremental migration pattern
• When SFSafariViewController is still the right choice
• When ASWebAuthenticationSession is required
• When WKWebView remains justified
• Testing the migration
• Review checklist

Migration goal

For SwiftUI apps targeting iOS 26+, the default for routine embedded web content should be native SwiftUI WebKit APIs (WebView, WebPage) instead of a custom UIViewRepresentable wrapper around WKWebView.

The goal is not "delete every WKWebView immediately." The goal is to move routine embedded web content to the new native surface and keep legacy fallback paths only where they are still justified.

Decision guide

Migrating from WKWebView wrappers

For SwiftUI apps targeting iOS 26+, start from WebView and WebPage for routine embedded content instead of a UIViewRepresentable wrapper around WKWebView.

Typical mapping:

Migrate first when the app is already SwiftUI-native and only kept WKWebView because there was no native view before.

Incremental migration pattern

A clean migration is usually screen-by-screen, not all-at-once.

Start by separating page ownership from view ownership

If the current wrapper mixes:

• page state
• navigation policy
• JS calls
• UI embedding

split those concerns first. Once page logic is no longer trapped inside the wrapper, moving to WebPage gets much easier.

Move the simplest screens first

Best first migrations:

• static help center content
• app-owned account or legal pages
• embedded flows that only need URL loading, title, and progress

Leave these for later:

• auth flows
• highly customized legacy UIKit screens
• surfaces relying on a capability you have not yet mapped to the new API set

Keep fallback boundaries explicit

Use availability and architecture boundaries instead of mixing two approaches in one view body.

struct HelpCenterScreen: View {
    let page = WebPage()

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

If a fallback is still needed, isolate it in a separate type rather than sprinkling if #available checks through the screen's core logic.

When SFSafariViewController is still the right choice

Use SFSafariViewController on iOS and iPadOS when the app just needs to show an external site with Safari behavior and does not need page-level control.

Good fits:

• help center article from a public website
• a legal page or blog post
• a temporary browse-out flow that should keep Safari chrome and reader behavior

Do not use SFSafariViewController when the app needs to:

• observe page state
• run JavaScript
• intercept navigation
• coordinate in-app page history

On macOS and visionOS, prefer platform default-browser behavior through openURL instead of treating SFSafariViewController as the browse-out surface.

When ASWebAuthenticationSession is required

Use ASWebAuthenticationSession for OAuth and third-party sign-in.

This remains true even if the rest of the app uses WebView for embedded content.

Do not replace auth sessions with embedded web views. The authentication skill owns that flow because the product requirement is secure sign-in, not generic web content.

When WKWebView remains justified

A fallback WKWebView path can still make sense when:

• the app must back-deploy below iOS 26
• the codebase is still UIKit-first and not ready to move the surface into

native SwiftUI WebKit APIs

• a required legacy-only WebKit capability is not yet available through the new

SwiftUI-facing API surface

• a heavily customized existing surface would create churn without product value

When you keep WKWebView, treat it as a deliberate fallback, not the default architecture for a modern iOS 26+ SwiftUI feature.

Testing the migration

For each migrated screen, verify:

• title and URL state still update correctly
• JavaScript calls still reach the page when needed
• navigation policy behavior still matches product expectations
• loading and error states still render at the right time
• no auth flow accidentally moved from ASWebAuthenticationSession to an

embedded view

• fallback WKWebView screens stay isolated instead of spreading wrapper logic

back into new screens

Review checklist

• [ ] New SwiftUI-native screens default to WebView and WebPage
• [ ] SFSafariViewController used only for browse-out Safari-style flows
• [ ] ASWebAuthenticationSession retained for OAuth and sign-in
• [ ] WKWebView kept only where back-deployment or capability gaps justify it
• [ ] Fallback paths isolated to dedicated wrapper types
• [ ] No new iOS 26+ feature starts from a UIViewRepresentable wrapper by default

Navigation and JavaScript

Contents

• Navigation policy decisions
• Opening external links outside the embedded web view
• Calling JavaScript
• Passing arguments into JavaScript
• Coarse JS-to-native signaling

Navigation policy decisions

Use WebPage.NavigationDeciding when the app needs to allow only owned URLs inside the embedded page.

import Observation
import WebKit

@Observable
@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 == "docs.example.com" {
            return .allow
        }

        urlToOpenExternally = url
        return .cancel
    }
}

This keeps app-owned pages embedded while still letting the app hand off external destinations.

Opening external links outside the embedded web view

Bridge the decider back into SwiftUI with openURL.

struct ArticleView: View {
    @Environment(\.openURL) private var openURL
    @State private var decider: ArticleNavigationDecider
    @State private var page: WebPage

    init() {
        let decider = ArticleNavigationDecider()
        _decider = State(initialValue: decider)
        _page = State(initialValue: WebPage(configuration: .init(), navigationDecider: decider))
    }

    var body: some View {
        WebView(page)
            .onChange(of: decider.urlToOpenExternally) { _, url in
                guard let url else { return }
                openURL(url)
                decider.urlToOpenExternally = nil
            }
    }
}

Use this for external links, legal pages, or routes that should leave the embedded surface.

Calling JavaScript

callJavaScript executes an async JavaScript function and returns an optional Any. Pass only the function body. Do not wrap the script in function foo() { ... } or append a call expression.

let script = """
const headings = [...document.querySelectorAll('h1, h2')];
return headings.map(node => ({
    id: node.id,
    title: node.textContent?.trim()
}));
"""

let result = try await page.callJavaScript(script)
let headings = result as? [[String: Any]] ?? []

Cast immediately into the specific structure the app expects. If the function body has no explicit return, the result is nil; if JavaScript explicitly returns null, handle NSNull.

Passing arguments into JavaScript

Arguments become local variables inside the JavaScript function. Use them for Swift-provided values instead of interpolating values into the script string. Supported values include numbers, strings, dates, and arrays, dictionaries, and optionals of those value types.

let topOffset = try await page.callJavaScript(
    "return document.getElementById(sectionID)?.getBoundingClientRect().top ?? null;",
    arguments: ["sectionID": selectedSectionID]
) as? Double

This is cleaner than interpolating untrusted values into the script string.

Coarse JS-to-native signaling

The native SwiftUI WebKit API clearly supports Swift-to-JavaScript calls, but it does not expose an obvious direct equivalent to WKScriptMessageHandler.

For coarse event handoff, a custom navigation pattern can work:

• JavaScript navigates to a custom callback URL like app-event://completed?id=123
• NavigationDeciding intercepts the URL
• the decider extracts data and returns .cancel

Use this for simple completion or routing signals. Do not present it as a full structured messaging replacement for legacy WKUserContentController script handlers, and keep richer native/web messaging on a WKWebView fallback until the SwiftUI-facing API covers the need.