Skip to main content

​
Overview

As of version 8.0, IQKeyboardReturnManager is now an independent package, separated from the main IQKeyboardManager library. It automatically handles return key behavior, allowing users to navigate between text fields by pressing the return key.
IQKeyboardReturnManager was previously named IQReturnKeyHandler and was part of IQKeyboardManager. It has been renamed and extracted into its own package.

​
GitHub Repository

hackiftekhar/IQKeyboardReturnManager

​
Key Features

  • Automatic Return Key Handling - Navigate to next field or dismiss keyboard on return key press
  • Smart Navigation - Automatically moves to next text field when pressing return
  • Customizable Behavior - Configure return key type per field (Next, Done, etc.)
  • No Code Required - Works automatically once enabled
  • Delegate Pattern - Optional delegate methods for custom behavior

​
Installation

​
CocoaPods

# Install IQKeyboardReturnManager independently
pod 'IQKeyboardReturnManager'

# Or as a subspec of IQKeyboardManager for easier migration
pod 'IQKeyboardManagerSwift/IQKeyboardReturnManager'

​
Swift Package Manager

dependencies: [
    .package(url: "https://github.com/hackiftekhar/IQKeyboardReturnManager.git", from: "2.0.0")
]

​
Carthage

github "hackiftekhar/IQKeyboardReturnManager"

​
Basic Usage

​
Enable Return Key Management

import IQKeyboardReturnManager

class MyViewController: UIViewController {
    
    @IBOutlet var nameTextField: UITextField!
    @IBOutlet var emailTextField: UITextField!
    @IBOutlet var passwordTextField: UITextField!
    
    private lazy var returnKeyManager = IQKeyboardReturnManager(controller: self)
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Return key manager is automatically enabled when created
        // It will handle return key presses in this view controller
    }
}

​
How It Works

  1. When the user presses return on a text field:
    • If there’s a next text field, it becomes first responder
    • If it’s the last text field, the keyboard dismisses
  2. Return key types are automatically configured:
    • “Next” for fields with a next field
    • “Done” for the last field

​
Configuration

​
Custom Delegate

Implement the delegate to customize behavior: 
class MyViewController: UIViewController, IQKeyboardReturnManagerDelegate {
    
    private lazy var returnKeyManager: IQKeyboardReturnManager = {
        let manager = IQKeyboardReturnManager(controller: self)
        manager.delegate = self
        return manager
    }()
    
    // MARK: - IQKeyboardReturnManagerDelegate
    
    func shouldResignOnReturn(_ textInputView: UIView) -> Bool {
        // Custom logic to determine if keyboard should dismiss
        return true
    }
    
    func didBeginEditing(_ textInputView: UIView) {
        // Called when editing begins
    }
    
    func didEndEditing(_ textInputView: UIView) {
        // Called when editing ends
    }
}

​
Manual Control

// Navigate to next text field programmatically
returnKeyManager.goNext()

// Navigate to previous text field
returnKeyManager.goPrevious()

// Dismiss keyboard
returnKeyManager.resignFirstResponder()

​
Migration from v7

See the Migration Guide for detailed migration instructions from IQKeyboardManager v7 to v8.

​
Key Changes

  1. Renamed - IQReturnKeyHandler → IQKeyboardReturnManager
  2. Separate Package - Now available as an independent library
  3. Initialization - Requires view controller instance in initializer

​
Before (v7)

import IQKeyboardManagerSwift

class MyViewController: UIViewController {
    
    private var returnKeyHandler: IQReturnKeyHandler?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        returnKeyHandler = IQReturnKeyHandler(controller: self)
    }
}

​
After (v8)

import IQKeyboardReturnManager

class MyViewController: UIViewController {
    
    private lazy var returnKeyManager = IQKeyboardReturnManager(controller: self)
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // returnKeyManager is automatically active
    }
}

​
Use Cases

​
Form Navigation

Ideal for forms where users should navigate between fields using the return key: 
class RegistrationViewController: UIViewController {
    
    @IBOutlet var firstNameField: UITextField!
    @IBOutlet var lastNameField: UITextField!
    @IBOutlet var emailField: UITextField!
    @IBOutlet var phoneField: UITextField!
    @IBOutlet var passwordField: UITextField!
    
    private lazy var returnKeyManager = IQKeyboardReturnManager(controller: self)
    
    // Return key will automatically navigate:
    // firstName (Return) → lastName (Return) → email (Return) → phone (Return) → password (Done)
}

​
Custom Return Behavior

class LoginViewController: UIViewController, IQKeyboardReturnManagerDelegate {
    
    @IBOutlet var usernameField: UITextField!
    @IBOutlet var passwordField: UITextField!
    
    private lazy var returnKeyManager: IQKeyboardReturnManager = {
        let manager = IQKeyboardReturnManager(controller: self)
        manager.delegate = self
        return manager
    }()
    
    func shouldResignOnReturn(_ textInputView: UIView) -> Bool {
        if textInputView == passwordField {
            // Trigger login when user presses return on password field
            performLogin()
            return true
        }
        return false
    }
    
    func performLogin() {
        // Handle login logic
    }
}

​
API Reference

​
Initialization

init(controller: UIViewController)
Creates a return key manager for the specified view controller.

​
Properties

PropertyTypeDescription
delegateIQKeyboardReturnManagerDelegate?Delegate for custom behavior

​
Methods

MethodDescription
goNext()Move to next text field
goPrevious()Move to previous text field
resignFirstResponder()Dismiss keyboard

​
Delegate Methods

protocol IQKeyboardReturnManagerDelegate: AnyObject {
    
    // Called to determine if keyboard should dismiss on return
    func shouldResignOnReturn(_ textInputView: UIView) -> Bool
    
    // Called when text field begins editing
    func didBeginEditing(_ textInputView: UIView)
    
    // Called when text field ends editing
    func didEndEditing(_ textInputView: UIView)
}

​
Best Practices

Store the IQKeyboardReturnManager instance as a property to keep it in memory throughout the view controller’s lifetime.
private lazy var returnKeyManager = IQKeyboardReturnManager(controller: self)
Create one return key manager per view controller, not per text field.
// ✅ Correct - one manager for the view controller
class FormViewController: UIViewController {
    private lazy var returnKeyManager = IQKeyboardReturnManager(controller: self)
}

// ❌ Incorrect - don't create multiple managers
class FormViewController: UIViewController {
    private lazy var manager1 = IQKeyboardReturnManager(controller: self)
    private lazy var manager2 = IQKeyboardReturnManager(controller: self)
}
IQKeyboardReturnManager works seamlessly with IQKeyboardManager. Use both together for complete keyboard handling:
// In AppDelegate
IQKeyboardManager.shared.isEnabled = true

// In ViewController
private lazy var returnKeyManager = IQKeyboardReturnManager(controller: self)

IQKeyboardToolbarManager

Add Previous/Next/Done toolbar buttons

IQTextView

UITextView with placeholder support

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us