Fix TabBarMinimize and prefersLargeTitle behaviour

[nbelzer]

I recently delved into an issue with the new TabBarMinimize functionality in iOS 26. For certain visits the minimize behavior would not trigger on scroll resulting in an unpredictable user experience.

Based on my findings the scrolling of the webView is not always detected by the TabBarController, therefore not triggering the minimized state of the tab bar. This also seems to extend to other functionality that triggers on scroll like the prefersLargeTitle configuration.

Based on my initial findings the issue appears to be that the webView in HotwireNative is not always the first child in the view hierarchy when the view appears. In HotwireNative we have several other views, like the screenshotContainerView and activityIndicatorView that are added and removed depending on the loading state of the page.

The proposed fix is to always place the webView as the first view in the hierarchy using insertSubview.

A better solution might be to rework the way we add views to the VisitableView such that the webview is always the first child. While I attempted such a solution I found that using insertSubview is more explicit and less likely to break by future changes to this file.

I have included more specific details in the commit description.

Would love to see this fixed in a future release. Also happy to discuss and look into any alternatives.

Example

At the moment I cannot share any examples from the app I am working on. However, I was able to use the demo app to re-create the issue using the following SceneDelegate:

// SceneDelegate.swift
import HotwireNative
import UIKit

let rootURL = URL(string: "https://hotwire-native-demo.dev")!

class CustomNavigationController: HotwireNavigationController {
    override func viewDidLoad() {
        super.viewDidLoad()
        navigationBar.prefersLargeTitles = true
    }
}

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    private let navigator = Navigator(configuration: .init(
        name: "main",
        startLocation: rootURL
    ))

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        Hotwire.config.defaultNavigationController = { CustomNavigationController() }
        window?.rootViewController = navigator.rootViewController
        navigator.start()
    }
}

Before

before.mp4

After

after.mp4

[joemasilotti]

Nice work! Do you know if this changes anything in iOS 18 or below?

[nbelzer]

Nice work! Do you know if this changes anything in iOS 18 or below?

On iOS 18 it solves the same issue with the prefersLargeTitles configuration. It also seems to resolve an issue with the tab bar being translucent on initial load. I have not tested anything below iOS 18.

I have updated the SceneDelegate example to also include a tab bar:

import HotwireNative
import UIKit

let rootURL = URL(string: "https://hotwire-native-demo.dev")!

class CustomNavigationController: HotwireNavigationController {
    override func viewDidLoad() {
        super.viewDidLoad()
        navigationBar.prefersLargeTitles = true
    }
}

extension HotwireTab {
    static let all = [
        HotwireTab(title: "Home", image: UIImage(systemName: "house")!, url: rootURL)
    ]
}

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    private let tabBarController = HotwireTabBarController()

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        Hotwire.config.defaultNavigationController = { CustomNavigationController() }
        window?.rootViewController = tabBarController
        tabBarController.load(HotwireTab.all)
    }
}

Before

ios18-before.mp4

After

ios18-after.mp4

[Jacoblab1]

This resolved the prefersLargeTitle behaviour in our app as well (tested on both iOS 18 and 26), thank you @nbelzer!

[joemasilotti]

This is great, nice work @nbelzer! I'm inclined to also prefer large titles in the demo app (see diff bellow).

But when I launch the app for the first time, the first tab doesn't correctly show a large title. Are you seeing the same?

RocketSim_Recording_iPhone_17_Pro_6.3_2025-11-06_08.17.01.mp4

diff --git a/Demo/AppDelegate.swift b/Demo/AppDelegate.swift
index a6912b9..42ad6e8 100644
--- a/Demo/AppDelegate.swift
+++ b/Demo/AppDelegate.swift
@@ -38,6 +38,11 @@ class AppDelegate: UIResponder, UIApplicationDelegate {
             OverflowMenuComponent.self,
         ])

+        // Use a custom navigation controller that prefers large titles.
+        Hotwire.config.defaultNavigationController = {
+            LargeTitleNavigationController()
+        }
+
         // Set configuration options
         Hotwire.config.backButtonDisplayMode = .minimal
         Hotwire.config.showDoneButtonOnModals = true

diff --git a/Demo/LargeTitleNavigationController.swift b/Demo/LargeTitleNavigationController.swift
new file mode 100644
index 0000000..224149a
--- /dev/null
+++ b/Demo/LargeTitleNavigationController.swift
@@ -0,0 +1,9 @@
+import HotwireNative
+import UIKit
+
+class LargeTitleNavigationController: HotwireNavigationController {
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        navigationBar.prefersLargeTitles = true
+    }
+}

[nbelzer]

But when I launch the app for the first time, the first tab doesn't correctly show a large title. Are you seeing the same?

I am seeing the same with the fix in this branch applied. Without the fix the title does appear in the large version right from launch (but we see the glitches documented above).

Playing around with largeTitleDisplayMode = .always does not appear to change anything.

When creating a simple app with native views only, the large title is displayed on launch. Ideally that would also be the behavior to expect from our HotwireWebView. I will need to look into why that is not happening with the fix applied.

EDIT: Some debugging shows a relationship between the large title view and the scroll view used for our webView:

Perhaps some logic is pushing the large title up before the view is displayed?

[nbelzer]

Found an additional reference indicating that the scrollable view should be placed at index 0 in the subview hierarchy.

Regarding the issue with large title on load, I took some time to look into the issue and found the following:

• the navigation view seems to add a negative contentOffset to the scrollable view when using large titles.
• when VisitableViewController#viewDidAppear is called, the content offset (visitableView.webView?.scrollView.contentOffset) for a large title is correct. I assume this value is different depending on the iOS version and device. On an iPhone 17 running iOS 26.1 this value is (0.0, -168.0).
• by the time we hit visitableDidRender the content offset has changed to (0.0, -116.0).
• when manually updating the content offset back to a y of -168.0 the large title is displayed correctly.
• This only happens on initial application load, further navigations do not see this difference.
• When adding a UIScrollViewDelegate to the webView.scrollView I see several calls to scrollViewDidScroll. The final one being triggered by a method changeContentOffsetBoundedInValidRange in WebKit. It seems part of the core iOS libraries so I am unable to inspect the code further:
  
• I was able to re-create the effect without the TurboNative library using the following SceneDelegate:

import WebKit
import UIKit

let rootURL = URL(string: "https://hotwire-native-demo.dev")!

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        let navigationController = UINavigationController()
        navigationController.navigationBar.prefersLargeTitles = true
        
        window?.rootViewController = navigationController

        let webView = WKWebView(frame: .zero)
        webView.translatesAutoresizingMaskIntoConstraints = false
        let request = URLRequest(url: rootURL)
        webView.load(request)
        
        let viewController = UIViewController()
        viewController.view.addSubview(webView)
        NSLayoutConstraint.activate([
            webView.leadingAnchor.constraint(equalTo: viewController.view.leadingAnchor),
            webView.trailingAnchor.constraint(equalTo: viewController.view.trailingAnchor),
            webView.topAnchor.constraint(equalTo: viewController.view.topAnchor),
            webView.bottomAnchor.constraint(equalTo: viewController.view.bottomAnchor)
        ])
        viewController.title = "Home"
        navigationController.pushViewController(viewController, animated: true)
    }
}

issue-on-plain-scene-delegate.mp4

• Experimenting with the constrains does show that the issue might be related to the constraints.
  • When I use a heightAnchor instead of the bottomAnchor with a constant smaller than the screen, the issue doesn't present itself. However, this is is not an acceptable solution as we wouldn't be able to use the entire screen height for our WebView.
  • I believe the way we add the WebView and set its constraints is common practice.

Based on the fact that the issue with large titles appears outside the HotwireNative library, and the incorrect contentOffset is being set by internal WebKit logic, I believe the issue is a bug in iOS.

I reported my findings to Apple through the Feedback Assistant. I will keep this thread updated when I hear something back.

On the short-term we might want to look into a fix built into the HotwireNative library. @joemasilotti Do we want to include such a fix as part of this PR?

[joemasilotti]

Great work on this @nbelzer! And thanks for reporting to Apple.

I'm all in favor of this change. I think we had a similar PR back before the Hotwire Native rebrand but it got lost in the transition.

Also of note, I think the bug is actually fixed in iOS 26.1! Here's two simulators, iOS 26.1 on the left and iOS 26.0 on the right, running the same code you shared above. Notice how the large title works as expected right on launch in iOS 26.1.

@svara, is it possible to test this against HEY/Basecamp? Everything seems to work fine in the apps I'm currently working on but I'd love another check before merging this.

[ibrahima]

Just to clarify, this fixes the issue with scrolling not always triggering the relevant TabBarMinimize and prefersLargeTitle behaviors, and the bug that was fixed in iOS is just for having the correct state on initial page load? So this PR is still needed for correct behavior in those two instances? Thanks!

[octave]

@joemasilotti and @nbelzer I still have the collapsed/shrunk title on launch with iOS 26.2 simulator and 26.3 actual iPhone 17 Pro, using the code from #199 (comment)

[octave]

Deep dive: WebKit's cold-start large title collapsing + workaround

I've been debugging this issue extensively and wanted to share findings that go beyond what this PR addresses. PR #199's insertSubview(webView, at: 0) fix correctly handles the scroll-triggered large title collapsing, but there's a separate cold-start collapsing bug caused by WebKit itself.

Root cause

After a WKWebView finishes loading, WebKit's internal changeContentOffsetBoundedInValidRange clamps scrollView.contentOffset.y from the expanded large-title value (e.g. -168) to a smaller value (e.g. -116), collapsing the title. This happens even with no user interaction — it's WebKit recalculating content bounds after the page renders.

Timeline (from logging)

viewDidAppear     → contentOffset.y = -168  ← correct, large title expanded
visitableDidRender → contentOffset.y = -116  ← already clamped by WebKit

The clamp happens between viewDidAppear and visitableDidRender, triggered by WebKit's internal layout pass. By the time any Hotwire Native delegate method fires, the offset is already wrong.

Workaround: KVO on scrollView.contentOffset

The only reliable way to catch and reverse the clamp is observing contentOffset via KVO right after viewDidAppear:

class FixedWebViewController: HotwireWebViewController {
    private var activeWebView: WKWebView?
    private var offsetObservation: NSKeyValueObservation?
    private var expandedOffset: CGFloat?
    private var isFixingOffset = false
    private var knownExpandedOffset: CGFloat?
    private var isFirstAppearance = true
    private var wasAtTopWhenLeft = true

    override func visitableDidActivateWebView(_ webView: WKWebView) {
        super.visitableDidActivateWebView(webView)
        visitableView.sendSubviewToBack(webView)
        activeWebView = webView
    }

    // ── Cold start fix ──────────────────────────────────────────
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        guard navigationItem.largeTitleDisplayMode == .always,
              let scrollView = activeWebView?.scrollView else { return }

        if isFirstAppearance {
            isFirstAppearance = false
            let offset = scrollView.contentOffset.y
            if offset < -100 {
                knownExpandedOffset = offset   // cache for back-nav
                watchForLargeTitleCollapse()
            }
        }
    }

    private func watchForLargeTitleCollapse() {
        stopWatching()
        guard let scrollView = activeWebView?.scrollView else { return }
        expandedOffset = scrollView.contentOffset.y

        offsetObservation = scrollView.observe(\.contentOffset, options: [.new, .old]) {
            [weak self] scrollView, change in
            guard let self, !self.isFixingOffset,
                  let expanded = self.expandedOffset,
                  let oldValue = change.oldValue,
                  let newValue = change.newValue else { return }

            // Detect WebKit's clamp: offset jumps from expanded to collapsed
            // without user interaction
            if oldValue.y <= expanded && newValue.y > expanded && !scrollView.isDragging {
                self.restoreExpandedOffset(scrollView: scrollView, to: expanded)
            }
        }

        // Safety: clean up after 3s if KVO never triggers
        DispatchQueue.main.asyncAfter(deadline: .now() + 3.0) { [weak self] in
            self?.stopWatching()
        }
    }

    // ── Back navigation fix ─────────────────────────────────────
    // On back-nav, adjustedContentInset.top reflects the COLLAPSED state (116),
    // so we can't compute the expanded offset dynamically.
    // Instead, reuse the offset cached from cold start.

    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        guard navigationItem.largeTitleDisplayMode == .always,
              let scrollView = activeWebView?.scrollView,
              let known = knownExpandedOffset else { return }
        wasAtTopWhenLeft = scrollView.contentOffset.y <= known + 20
    }

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        guard !isFirstAppearance, wasAtTopWhenLeft,
              navigationItem.largeTitleDisplayMode == .always,
              let scrollView = activeWebView?.scrollView,
              let known = knownExpandedOffset else { return }
        restoreExpandedOffset(scrollView: scrollView, to: known)
    }

    // ── Helpers ─────────────────────────────────────────────────
    private func restoreExpandedOffset(scrollView: UIScrollView, to offset: CGFloat) {
        isFixingOffset = true
        scrollView.setContentOffset(CGPoint(x: 0, y: offset), animated: false)
        isFixingOffset = false
        stopWatching()
    }

    private func stopWatching() {
        offsetObservation?.invalidate()
        offsetObservation = nil
        expandedOffset = nil
    }

    deinit { stopWatching() }
}

Key findings

1. viewDidAppear is the right hook — it's the last moment where the offset is still correct (-168). By visitableDidRender, WebKit has already clamped it.

2. adjustedContentInset.top is unreliable on back-nav — it returns 116 (collapsed) instead of 168 (expanded), so you can't use -adjustedContentInset.top to compute the target offset. The workaround is to cache the correct expanded offset from the initial cold start.

3. viewWillAppear (not viewDidAppear) for back-nav — restoring the offset in viewWillAppear ensures the large title is expanded before the back transition animation starts, avoiding a visual flash.

4. Scroll position preservation — without the wasAtTopWhenLeft flag, navigating back always resets to top even when the user had scrolled down. Saving scroll state in viewWillDisappear prevents this.

5. !scrollView.isDragging guard — prevents the KVO observer from interfering with normal user scrolling.

Reproducing in isolation

I confirmed this bug in a minimal test project (no Hotwire Native — just a bare WKWebView in a UINavigationController with prefersLargeTitles = true). The clamp happens identically, proving it's a WebKit behavior, not a Hotwire Native bug.

Suggestion

This KVO approach could potentially be integrated into HotwireWebViewController itself (behind a flag or as default behavior when largeTitleDisplayMode == .always), so users don't need to subclass to get correct large title behavior.

Tested on iOS 26.2 (Simulator) and 26.3 (iPhone 17 Pro).

[nbelzer]

Thanks @octave for confirming that the cold-boot is still an issue on iOS 26.2 and 26.3, your findings perfectly match mine on iOS 26.0¹. Did you report your findings to Apple? maybe if they receive multiple reports they will look into it.

I like the idea of providing a fix for the cold-boot behavior out-of-the-box, but I'd argue it should be part of follow-up PR.

@joemasilotti @svara is there anything I can do to get this initial fix in to the next Hotwire Native release? The insertSubview change in this branch makes sure TabBarMinimize can be used in Hotwire Native apps. It also allows the prefersLargeTitle behavior to be used, although a cold-boot issue exists where it collapses on initial launch, this appears to be related to a bug in iOS as described above¹².

Footnotes

1. https://github.com/hotwired/hotwire-native-ios/pull/199#issuecomment-3532671791 ↩ ↩²

2. https://github.com/hotwired/hotwire-native-ios/pull/199#issuecomment-4020675614 ↩

[octave]

@nbelzer Thanks for the reply! I haven't reported to Apple yet — I'll file a Feedback Assistant report as well.

Agree that the insertSubview fix and the cold-boot KVO workaround should be separate PRs. The insertSubview change is clearly the right first step.

A couple of additional findings since my last comment, relevant for a future cold-boot fix:

Multi-tab edge case: In apps with multiple tabs using prefersLargeTitles, the second tab can exhibit a different timing issue. The first tab works with the KVO approach (clamp happens after viewDidAppear), but when switching to a second tab, the page may render faster than the tab transition — so visitableDidRender fires before viewDidAppear, and by then the offset is already clamped. The KVO watcher never catches it because it hasn't started yet.

The workaround I'm using: the first tab caches its correct expanded offset in a static/shared property. When a subsequent tab appears with an already-collapsed offset, it uses the shared value to force-expand (without starting a KVO watcher, since the clamp already happened).

UISearchController with preferredSearchBarPlacement = .stacked: If your app uses a native search bar via navigationItem.searchController, it must be set on the navigation item before the view loads (i.e., before vc.view is accessed). Setting it later (e.g., from a bridge component after page load) causes UIKit to never include it in the initial layout — it stays hidden until the user scrolls. Pre-installing it at VC creation time fixes this.

Happy to help with a follow-up PR for the cold-boot fix if that would be useful.