Introduction

automaticallyAdjustsScrollViewInsets was removed from the modern iOS layout model because safe areas replaced the old global inset behavior. If your project still relies on the old property, you may see content hidden under bars or extra top spacing on newer devices. The migration path is to use per scroll view inset adjustment rules and safe area aware constraints.

What Changed In iOS 11

Before iOS 11, one view controller level property controlled automatic inset behavior for embedded scroll views. Starting in iOS 11, each scroll view has its own contentInsetAdjustmentBehavior.

This gives finer control but requires explicit setup per screen.

Available behaviors:

• .automatic for default system handling,
• .always to always include safe area,
• .never to fully opt out,
• .scrollableAxes to adjust only for scrollable directions.

Most migration bugs come from leaving old assumptions in place while adding new safe area constraints.

Basic Migration Example

For a table view inside a normal controller, set behavior explicitly.

1import UIKit
2
3final class FeedViewController: UIViewController {
4    @IBOutlet private weak var tableView: UITableView!
5
6    override func viewDidLoad() {
7        super.viewDidLoad()
8
9        if #available(iOS 11.0, *) {
10            tableView.contentInsetAdjustmentBehavior = .automatic
11        }
12    }
13}

This is usually enough when constraints are already safe area based.

When You Need Manual Insets

Custom overlays, floating headers, or mixed bar visibility often require manual inset control.

1override func viewDidLoad() {
2    super.viewDidLoad()
3    if #available(iOS 11.0, *) {
4        scrollView.contentInsetAdjustmentBehavior = .never
5    }
6}
7
8override func viewSafeAreaInsetsDidChange() {
9    super.viewSafeAreaInsetsDidChange()
10
11    let top = view.safeAreaInsets.top
12    let bottom = view.safeAreaInsets.bottom
13
14    scrollView.contentInset = UIEdgeInsets(top: top, left: 0, bottom: bottom, right: 0)
15    scrollView.scrollIndicatorInsets = scrollView.contentInset
16}

If you choose .never, you now own all inset updates and should keep indicator insets in sync.

Navigation Controller Interactions

Insets can change when navigation bar visibility changes, large titles expand or collapse, or interactive transitions run. Test at least these flows:

• push and pop with large title enabled,
• modal presentation then dismiss,
• rotation and split view changes,
• keyboard appearance for forms inside scroll views.

Many teams test only static launch state and miss transition related spacing bugs.

Safe Area And Constraints Must Agree

Inset settings and Auto Layout constraints must be aligned. A common anti pattern is constraining scroll view content to superview top while also using automatic inset adjustment. That can produce double spacing.

Preferred baseline:

• pin scroll view frame to view edges,
• pin content layout guide correctly,
• rely on inset adjustment for bar avoidance.

If layout is fully custom, disable automatic adjustment and compute insets manually.

Legacy Compatibility Strategy

If you still support older iOS versions, keep version checks local and temporary. Do not spread compatibility branches across every controller.

Create a helper method or base controller that applies consistent inset policy. This reduces migration drift and makes future cleanup easier when minimum version increases.

Common Pitfalls

• Leaving deprecated property references in old controllers after migration.
• Applying both automatic adjustment and hardcoded top inset values.
• Updating content insets but forgetting scroll indicator insets.
• Testing only one device and missing notch and dynamic island safe area differences.
• Ignoring layout changes during navigation bar collapse and expansion.

Summary

• iOS 11 replaced global inset control with per scroll view behavior.
• Migrate by setting contentInsetAdjustmentBehavior intentionally on each screen.
• Use safe area aware constraints and keep inset logic consistent.
• If opting out with .never, manage both content and indicator insets yourself.
• Validate transitions, device sizes, and keyboard scenarios to catch real layout regressions.