Return Key Handling

Overview

The IQKeyboardReturnManager subspec provides automatic return key handling, allowing users to navigate between text fields by pressing the Return key on the keyboard. The manager automatically changes the return key type to “Next” or “Done” based on the field’s position in the form.

IQKeyboardReturnManager is now available as an independent library, similar to IQKeyboardToolbarManager.

Installation

CocoaPods

Podfile

# Include as part of IQKeyboardManagerSwift
pod 'IQKeyboardManagerSwift'

# Or include the specific subspec
pod 'IQKeyboardManagerSwift/IQKeyboardReturnManager'

# Or use the standalone library
pod 'IQKeyboardReturnManager'

Swift Package Manager

The IQKeyboardReturnManager is included in the main package or can be added separately:

https://github.com/hackiftekhar/IQKeyboardManager.git

How It Works

The Return Key Manager automatically:

Detects text field order in your form
Changes return key type to “Next” for fields with a next field
Changes return key type to “Done” for the last field
Handles return key taps to move to the next field or dismiss keyboard
Works with UITextField and UITextView

Basic Setup

Return key handling works automatically once IQKeyboardManager is enabled:

AppDelegate.swift

import IQKeyboardManagerSwift

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    
    // Enable keyboard management (return key handling is automatic)
    IQKeyboardManager.shared.isEnabled = true
    
    return true
}

No additional configuration is needed. Return key handling is enabled by default when IQKeyboardManager is active.

Return Key Types

The manager automatically sets appropriate return key types:

Used for fields that have a next text field in the form

Done

Used for the last text field to dismiss the keyboard

ViewController.swift

import UIKit

class RegistrationViewController: UIViewController {
    
    @IBOutlet weak var firstNameField: UITextField!  // Return key: Next
    @IBOutlet weak var lastNameField: UITextField!   // Return key: Next
    @IBOutlet weak var emailField: UITextField!      // Return key: Next
    @IBOutlet weak var passwordField: UITextField!   // Return key: Done
    
    override func viewDidLoad() {
        super.viewDidLoad()
        // Return keys are automatically configured!
    }
}

When the user:

Taps Return on firstNameField → moves to lastNameField
Taps Return on lastNameField → moves to emailField
Taps Return on emailField → moves to passwordField
Taps Return on passwordField → dismisses keyboard

Manual Return Key Control

You can still manually set return key types when needed:

ViewController.swift

class CustomFormViewController: UIViewController {
    
    @IBOutlet weak var searchField: UITextField!
    @IBOutlet weak var notesField: UITextView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Force specific return key types
        searchField.returnKeyType = .search
        notesField.returnKeyType = .default
    }
}

Manually set return key types will be respected by IQKeyboardManager.

Custom Return Key Actions

Implement UITextFieldDelegate to customize behavior:

ViewController.swift

class LoginViewController: UIViewController, UITextFieldDelegate {
    
    @IBOutlet weak var usernameField: UITextField!
    @IBOutlet weak var passwordField: UITextField!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        usernameField.delegate = self
        passwordField.delegate = self
    }
    
    func textFieldShouldReturn(_ textField: UITextField) -> Bool {
        if textField == usernameField {
            // Move to password field
            passwordField.becomeFirstResponder()
        } else if textField == passwordField {
            // Validate and submit
            view.endEditing(true)
            performLogin()
        }
        return true
    }
    
    func performLogin() {
        // Handle login
    }
}

UITextView Support

For multi-line text views, the manager handles return keys intelligently:

ViewController.swift

class FeedbackViewController: UIViewController {
    
    @IBOutlet weak var nameField: UITextField!       // Return key: Next
    @IBOutlet weak var emailField: UITextField!      // Return key: Next  
    @IBOutlet weak var feedbackTextView: UITextView! // Return key: Default (for line breaks)
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // UITextView allows line breaks by default
        // To make it advance to next field:
        feedbackTextView.returnKeyType = .next
    }
}

Setting returnKeyType = .next on a UITextView will make the Return key advance to the next field instead of inserting a line break.

Handling Special Cases

Search Fields

ViewController.swift

class SearchViewController: UIViewController, UITextFieldDelegate {
    
    @IBOutlet weak var searchField: UITextField!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        searchField.returnKeyType = .search
        searchField.delegate = self
    }
    
    func textFieldShouldReturn(_ textField: UITextField) -> Bool {
        performSearch(query: textField.text ?? "")
        textField.resignFirstResponder()
        return true
    }
    
    func performSearch(query: String) {
        // Execute search
    }
}

Submit Forms

ViewController.swift

class ContactFormViewController: UIViewController, UITextFieldDelegate {
    
    @IBOutlet weak var nameField: UITextField!
    @IBOutlet weak var emailField: UITextField!
    @IBOutlet weak var messageField: UITextView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Last field triggers submission
        messageField.returnKeyType = .send
    }
    
    func textFieldShouldReturn(_ textField: UITextField) -> Bool {
        if textField == emailField {
            messageField.becomeFirstResponder()
        }
        return true
    }
}

Disable Return Key Handling

If you want to disable automatic return key handling while keeping other IQKeyboardManager features:

AppDelegate.swift

// IQKeyboardManager doesn't expose a specific disable flag for return key handling
// Instead, set return key types manually or implement UITextFieldDelegate

The return key manager is lightweight and non-intrusive. It only changes return key types and doesn’t interfere with custom UITextFieldDelegate implementations.

Return Key Navigation

Advantages:

Natural typing flow
No additional UI
Familiar to users
Works great for short forms

Disadvantages:

Less discoverable
No previous button
Requires pressing return

Toolbar Navigation

Advantages:

Visible Previous/Next/Done buttons
Can go back to previous fields
More discoverable
Better for long forms

Disadvantages:

Takes up space above keyboard
Additional UI element

You can use both return key handling and toolbar navigation together for maximum flexibility.

Combined Example

CompleteFormViewController.swift

import UIKit
import IQKeyboardManagerSwift

class CompleteFormViewController: UIViewController {
    
    @IBOutlet weak var firstNameField: UITextField!
    @IBOutlet weak var lastNameField: UITextField!
    @IBOutlet weak var emailField: UITextField!
    @IBOutlet weak var phoneField: UITextField!
    @IBOutlet weak var notesField: UITextView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        setupForm()
    }
    
    func setupForm() {
        // Return keys are automatic, but you can customize:
        phoneField.returnKeyType = .next
        notesField.returnKeyType = .default // Allow line breaks
        
        // Enable toolbar for additional navigation
        // IQKeyboardManager.shared.enableAutoToolbar = true
    }
}

extension CompleteFormViewController: UITextFieldDelegate {
    
    func textFieldShouldReturn(_ textField: UITextField) -> Bool {
        switch textField {
        case firstNameField:
            lastNameField.becomeFirstResponder()
        case lastNameField:
            emailField.becomeFirstResponder()
        case emailField:
            phoneField.becomeFirstResponder()
        case phoneField:
            notesField.becomeFirstResponder()
        default:
            textField.resignFirstResponder()
        }
        return true
    }
}

Best Practices

Let the manager handle return keys automatically

Unless you have specific requirements, let IQKeyboardManager automatically configure return key types. It’s smart enough to handle most scenarios.

Use .search for search fields

Set returnKeyType = .search for search fields to show the search icon instead of “Next” or “Done”.

Consider UX for multi-line text views

For fields that need line breaks (like comments or notes), use .default return key type. For single-line behavior, use .next or .done.

Test the flow

Always test the complete navigation flow to ensure users can easily move through your form using the Return key.

Troubleshooting

Return key not advancing to next field

Verify IQKeyboardManager is enabled
Check if you’ve implemented textFieldShouldReturn that returns false
Ensure text fields are in the view hierarchy
Check that next field is a valid text input view

Wrong return key type showing

Check if you’ve manually set returnKeyType
Verify the field order in your view hierarchy
Try reloading the keyboard: textField.reloadInputViews()

Return key dismissing keyboard unexpectedly

Check if the field is detected as the last field
Verify all text fields are properly connected
Ensure hidden fields are actually visible when needed

Next Steps

Toolbar Management

Add Previous/Next/Done buttons for additional navigation

Resign Keyboard

Dismiss keyboard by tapping outside text fields

Advanced Configuration

Fine-tune keyboard behavior

Debugging

Troubleshoot return key issues

Get Started

Core Concepts

Guides

Migration

Overview

Installation

CocoaPods

Swift Package Manager

How It Works

Basic Setup

Return Key Types

Next

Done

Navigation Flow

Manual Return Key Control

Custom Return Key Actions

UITextView Support

Handling Special Cases

Search Fields

Submit Forms

Disable Return Key Handling

Return Key Navigation

Toolbar Navigation

Combined Example

Best Practices

Troubleshooting

Next Steps

Toolbar Management

Resign Keyboard

Advanced Configuration

Debugging

​Overview

​Installation

​CocoaPods

​Swift Package Manager

​How It Works

​Basic Setup

​Return Key Types

Next

Done

​Navigation Flow

​Manual Return Key Control

​Custom Return Key Actions

​UITextView Support

​Handling Special Cases

​Search Fields

​Submit Forms

​Disable Return Key Handling

​Return Key vs Toolbar Navigation

Return Key Navigation

Toolbar Navigation

​Combined Example

​Best Practices

​Troubleshooting

​Next Steps

Toolbar Management

Resign Keyboard

Advanced Configuration

Debugging

Overview

Installation

CocoaPods

Swift Package Manager

How It Works

Basic Setup

Return Key Types

Navigation Flow

Manual Return Key Control

Custom Return Key Actions

UITextView Support

Handling Special Cases

Search Fields

Submit Forms

Disable Return Key Handling

Return Key vs Toolbar Navigation

Combined Example

Best Practices

Troubleshooting

Next Steps