Introduction

iOS 15 introduced a visible layout change in UITableView: section headers gained extra top padding by default. Apps that looked correct on earlier iOS versions suddenly showed more white space above grouped or plain section headers, which made many existing table-based screens appear misaligned.

The New iOS 15 Property

Apple added sectionHeaderTopPadding to UITableView in iOS 15. That property controls the extra space the system inserts above section headers.

If you want the pre-iOS 15 appearance, set it to zero:

1import UIKit
2
3final class ItemsViewController: UITableViewController {
4    override func viewDidLoad() {
5        super.viewDidLoad()
6
7        if #available(iOS 15.0, *) {
8            tableView.sectionHeaderTopPadding = 0
9        }
10    }
11}

That single line is the fix most apps need.

Why the Layout Changed

The system default changed as part of broader UIKit spacing updates. Apple pushed many standard components toward more generous spacing, especially in list-like interfaces. That default can be reasonable for newly designed screens, but it also means older layouts suddenly inherit a look they were not designed for.

So this is not usually a bug in your header view. It is a changed default in the table view itself.

App-Wide Configuration

If the same problem appears in many table views, you can set the default through UIAppearance.

1import UIKit
2
3@main
4class AppDelegate: UIResponder, UIApplicationDelegate {
5    func application(
6        _ application: UIApplication,
7        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
8    ) -> Bool {
9        if #available(iOS 15.0, *) {
10            UITableView.appearance().sectionHeaderTopPadding = 0
11        }
12        return true
13    }
14}

This is convenient when your design system wants the old tighter spacing everywhere.

Custom Header Heights Still Matter

Setting sectionHeaderTopPadding does not replace your normal header sizing logic. If you already implement delegate methods such as tableView(_:heightForHeaderInSection:), those still control the header's height. The new property only removes the extra top padding added before the header.

override func tableView(_ tableView: UITableView, heightForHeaderInSection section: Int) -> CGFloat {
    return 32
}

So if the layout still looks wrong after setting the top padding to zero, review the header view itself and any delegate sizing methods next.

Watch Style Differences

The spacing change is most noticeable in grouped-style tables, but developers also encounter it in plain tables depending on header usage and overall layout. Because the effect depends on table style and header configuration, it is worth checking both simulator and device screenshots before making a global adjustment.

If your app actually benefits from the newer spacing, do not remove it automatically. Treat the property as a design choice, not just a compatibility flag.

Common Pitfalls

The biggest pitfall is trying to fight the issue by changing header view frames or returning tiny custom heights. That may mask the symptom but leave the real iOS 15 spacing behavior untouched.

Another common mistake is forgetting the availability check. sectionHeaderTopPadding is an iOS 15 API, so older deployment targets need conditional code around it.

Developers also sometimes confuse this top padding with content inset or safe-area issues. If the extra space only appears above section headers, the table view's new header padding behavior is the more likely cause.

Summary

• iOS 15 added default top padding above UITableView section headers.
• The main fix is tableView.sectionHeaderTopPadding = 0 on iOS 15 and later.
• Use UIAppearance if you want the adjustment across the whole app.
• Header height delegate methods still matter; the new property only controls extra spacing above the header.
• Check whether you actually want the old look before removing the new default globally.