Introduction

In grouped UITableView layouts, the first section often shows a header gap even when you do not want a visible title. Hiding that first header requires both a zero-height strategy and a compatible header view implementation. Behavior also differs slightly across iOS versions, especially with top padding changes in recent releases.

Implement Header Height Logic

Use UITableViewDelegate to return a minimal height for section zero and normal height for others.

1import UIKit
2
3final class SettingsViewController: UITableViewController {
4    override func viewDidLoad() {
5        super.viewDidLoad()
6        tableView = UITableView(frame: .zero, style: .grouped)
7    }
8
9    override func tableView(_ tableView: UITableView, heightForHeaderInSection section: Int) -> CGFloat {
10        if section == 0 {
11            return .leastNormalMagnitude
12        }
13        return 28
14    }
15}

Using .leastNormalMagnitude is typically safer than raw zero for grouped style rendering behavior.

Provide Matching Header View Behavior

If you customize header views, return an empty view for first section so UIKit does not synthesize default spacing.

1override func tableView(_ tableView: UITableView, viewForHeaderInSection section: Int) -> UIView? {
2    if section == 0 {
3        return UIView(frame: .zero)
4    }
5
6    let label = UILabel()
7    label.text = section == 1 ? "Account" : "Advanced"
8    label.font = UIFont.preferredFont(forTextStyle: .footnote)
9
10    let container = UIView()
11    label.translatesAutoresizingMaskIntoConstraints = false
12    container.addSubview(label)
13    NSLayoutConstraint.activate([
14        label.leadingAnchor.constraint(equalTo: container.leadingAnchor, constant: 16),
15        label.bottomAnchor.constraint(equalTo: container.bottomAnchor, constant: -6)
16    ])
17    return container
18}

Returning nil for first section can still produce default behavior in some combinations of delegate methods. An explicit empty view is more predictable.

iOS 15 Plus: Section Header Top Padding

From iOS fifteen, sectionHeaderTopPadding adds extra space by default in plain-style tables, and can affect expectations during migration.

if #available(iOS 15.0, *) {
    tableView.sectionHeaderTopPadding = 0
}

For grouped tables this setting is less central, but teams often use shared table configuration code, so include it when debugging visual spacing differences.

SwiftUI Hosting or Embedded Controllers

If your UITableViewController is embedded in another container, check surrounding layout constraints and content insets. The visible "header gap" can be top content inset from parent scroll behavior rather than section header itself.

1override func viewDidLayoutSubviews() {
2    super.viewDidLayoutSubviews()
3    tableView.contentInset.top = 0
4}

Use the view debugger to confirm where spacing is introduced before changing delegate logic.

Test Across Dynamic Type and Empty Data

Header spacing can change when section titles are localized or when data source returns zero rows for first section. Validate these states:

• first section has rows
• first section empty, second section populated
• large text accessibility sizes

This prevents regressions where hidden headers reappear in edge conditions.

Plain Style and Grouped Style Differences

Do not copy grouped-style header logic directly into plain-style tables. UIKit spacing defaults differ, and iOS fifteen top padding behavior is more visible in plain style. Keep style-specific configuration paths so layout fixes remain predictable after UI refactors.

Common Pitfalls

• Returning zero height but not overriding viewForHeaderInSection consistently.
• Assuming top spacing is always section header rather than content inset.
• Forgetting iOS version differences when migrating old table view code.
• Hardcoding magic numbers for all sections without design rationale.
• Testing only one dataset shape and missing empty-section layout regressions.

Summary

• Hide first grouped-section header with minimal height and explicit empty header view.
• Keep non-first sections using normal header heights and reusable views.
• Check content insets and container layout before blaming header logic.
• Account for iOS version behavior, including top-padding changes in shared setups.
• Validate with dynamic type and empty-state datasets to avoid visual regressions.