Keyboard Avoidance — Essence, Implementation Methods and Interface Offset

What is Keyboard Avoidance

Keyboard Avoidance is a set of techniques that ensure the visibility of the active input field when the system keyboard appears on iOS. The basic problem: the keyboard occupies up to 50% of the screen and covers the lower half of the interface, including text fields, submit buttons, and other elements.

There are three main approaches to implementation: manual management through Keyboard Notifications (classic approach, works since iOS 3.0), using UIScrollView with automatic scrolling (recommended by Apple), and Keyboard Layout Guide (modern approach with iOS 15+). The choice depends on the minimum supported iOS version and interface complexity.

According to Apple, the lack of Keyboard Avoidance is one of the most common reasons for app rejection during review if text fields are completely covered by the keyboard. App Store Guidelines explicitly require that all interactive elements remain accessible during active input.

Why iOS Does Not Do This Automatically

iOS cannot automatically determine which element should remain visible because it does not know the semantics of the interface. In a simple form with one text field, moving the entire screen up is sufficient. In a complex interface with custom panels, floating buttons, and multiple sections, different behavior logic is required.

Additionally, some apps intentionally do not shift content — for example, keyboard calculators or editors where the keyboard is part of the workspace. iOS leaves the decision to the developer, providing flexible APIs for any scenario.

Keyboard Frame Notifications

UIKeyboardWillShowNotification is the main notification that iOS sends before the keyboard appears. It contains a CGRect with the final keyboard position in the UIResponder.keyboardFrameEndUserInfoKey dictionary, as well as the animation duration in UIResponder.keyboardAnimationDurationUserInfoKey.

The notification handler should calculate the overlap between the active text field and the keyboard, then change the bottom inset (contentInset or frame) of the container. If the field is below the top edge of the keyboard, the content shifts upward by the amount of overlap. When the keyboard hides, the inset returns to its original value.

@objc func keyboardWillShow(_ notification: Notification) {
    guard let keyboardFrame = notification
        .userInfo?[UIResponder.keyboardFrameEndUserInfoKey]
        as? CGRect else { return }
    
    let keyboardHeight = keyboardFrame.height
    scrollView.contentInset.bottom = keyboardHeight
    scrollView.verticalScrollIndicatorInsets.bottom = keyboardHeight
}

When using notifications, it is important to handle animation synchronously with the system keyboard. iOS provides the animation curve (UIResponder.keyboardAnimationCurveUserInfoKey) and duration. Use UIView.animate with these parameters so that the content shifts smoothly, simultaneously with the keyboard appearance.

Keyboard Layout Guide in iOS 15+

UIScrollView.keyboardLayoutGuide is a modern API for Keyboard Avoidance, introduced in iOS 15. It automatically tracks the keyboard position and updates Auto Layout constraints that connect the bottom of the interface to the top edge of the keyboard.

To use it, simply activate the layout guide on a UIScrollView or UIStackView and attach the bottom content constraint to it. No manual work with notifications, height calculation, or animation is required — the system does everything automatically, synchronizing animation with the keyboard appearance and dismissal.

// Enable Keyboard Layout Guide (iOS 15+)
scrollView.keyboardLayoutGuide.followsUndockedKeyboard = true

// Pin bottom constraint to keyboard top
contentView.bottomAnchor.constraint(
    equalTo: scrollView.keyboardLayoutGuide.topAnchor
).isActive = true

followsUndockedKeyboard is a property that determines whether the guide should respond to a keyboard that can be detached from the bottom edge (on iPad). Set it to true only if the interface works correctly with a floating keyboard. For iPhone, this property is ignored — the keyboard is always attached to the bottom edge.

UIScrollView and Keyboard

UIScrollView is a container that Apple recommends using as the foundation for Keyboard Avoidance. When the keyboard appears, the scroll view increases its contentInset.bottom, allowing the content to scroll up and making the active field visible.

The key method is scrollRectToVisible, which programmatically scrolls the scroll view so that the specified rectangle (the active text field) becomes visible. Combining contentInset changes with a scrollRectToVisible call ensures that the field is not only uncovered but also positioned in the upper part of the visible area.

func adjustScrollForKeyboard(
    keyboardHeight: CGFloat,
    activeField: UIView
) {
    scrollView.contentInset.bottom = keyboardHeight
    scrollView.verticalScrollIndicatorInsets.bottom = keyboardHeight
    
    var visibleRect = view.frame
    visibleRect.size.height -= keyboardHeight
    
    if activeField.frame.origin.y > visibleRect.maxY {
        scrollView.scrollRectToVisible(
            activeField.frame, animated: true
        )
    }
}

For UIViewController with UITableView, Apple recommends using UITableViewController, which automatically adjusts contentInset when the keyboard appears. If you use UIViewController with an added table, you will need to implement Keyboard Avoidance manually — UITableViewController does not provide this behavior for custom controllers.

Auto Layout and Keyboard Avoidance

Auto Layout allows implementing Keyboard Avoidance without programming animations — simply change the activity (isActive) of a specific constraint or update its constant in response to a keyboard notification.

A typical scheme: create an IBOutlet NSLayoutConstraint for the bottom inset of the scroll view or content, and in the keyboardWillShow handler set constraint.constant = keyboardHeight, and in keyboardWillHide reset it to 0. Update the layout via layoutIfNeeded inside an animate block for a smooth transition.

When using UIStackView, changing bottom inset constraints also works: the stack view redistributes child elements automatically. However, if the stack view is inside a UIScrollView, it is preferable to manage the contentInset of the scroll view itself, rather than constraints inside it.

Third-Party Solutions for Keyboard Avoidance

IQKeyboardManager is the most popular library (over 16,000 stars on GitHub) that implements automatic Keyboard Avoidance without a single line of code in the controller. It uses method swizzling to track text fields and automatically raises content when the keyboard appears.

The library provides flexible settings: you can specify the distance between the field and the keyboard, enable/disable it for specific controllers, and configure behavior for UITextView and custom input views. However, method swizzling may conflict with other libraries, and Apple does not recommend this approach for production code due to unpredictable side effects.

Alternatives include TPKeyboardAvoiding (a lightweight library, ~2000 stars) and KeyboardManager from the community. For modern projects, Apple recommends using the built-in iOS 15+ tools, and for projects with a lower minimum version — UIScrollView with contentInset, which is the most reliable built-in solution.