Skip to main content

​
Overview

This section provides comprehensive migration guides for upgrading IQKeyboardManager between major versions. Each guide details breaking changes, deprecated APIs, and step-by-step instructions to update your code.

​
Available Migration Guides

v7 to v8

Latest migration guide with modular architecture changes

v6 to v7

Configuration consolidation and wrapper pattern

v5 to v6

API renaming and new features

​
When to Migrate

Stay on Latest: We recommend staying on the latest major version to receive bug fixes, performance improvements, and new features.
Consider migrating when:
  • You need features only available in newer versions
  • Security updates require a newer version
  • You’re starting a new project (use the latest version)
  • Your dependencies require a newer version

​
General Migration Principles

​
1. Review Breaking Changes First

Before migrating, carefully read the breaking changes section in the relevant migration guide. This helps you understand the scope of changes required.

​
2. Update Dependencies

1

Update Package Manager

Update your Podfile, Package.swift, or Cartfile to the new version
2

Install Dependencies

Run your package manager to install the new version
3

Fix Compilation Errors

Address any compilation errors highlighted by Xcode
4

Test Thoroughly

Test all keyboard-related functionality in your app

​
3. Incremental Migration

Avoid Skipping Versions: If you’re multiple versions behind, migrate incrementally (e.g., v5 → v6 → v7 → v8) rather than jumping directly to the latest version.
Migrating one major version at a time:
  • Makes changes more manageable
  • Reduces the risk of introducing bugs
  • Helps you understand the evolution of the API

​
4. Use Compiler Warnings

The library marks deprecated APIs with compiler warnings. These warnings guide you to the new APIs: 
// Deprecated API (will show warning)
IQKeyboardManager.shared.shouldResignOnTouchOutside = true

// New API
IQKeyboardManager.shared.resignOnTouchOutside = true

​
5. Test Common Scenarios

After migration, test these common scenarios:
  • Text fields properly scroll when keyboard appears
  • Keyboard dismisses when tapping outside
  • Multiple text fields on screen work correctly
  • Previous/Next buttons navigate correctly
  • Done button dismisses keyboard
  • Custom toolbar items appear as expected
  • ScrollView with nested text fields
  • Text fields in table/collection view cells
  • Modal presentations and navigation
  • Landscape and iPad layouts

​
Support Policy

​
Active Support

Only the latest major version receives active feature development and bug fixes.

​
Security Updates

Critical security issues may be backported to the previous major version for a limited time.

​
Community Support

Older versions are community-supported through:
  • GitHub issues and discussions
  • Stack Overflow
  • Community forums

​
Getting Help

If you encounter issues during migration:
  1. Check the Migration Guide: Review the specific version migration guide thoroughly
  2. Search Issues: Look for similar issues on GitHub
  3. Ask for Help: Create a new issue with:
    • Source version and target version
    • Specific error messages or unexpected behavior
    • Minimal code example reproducing the issue
    • Steps you’ve already tried

​
Next Steps

Select the migration guide that matches your current and target versions:

v7 → v8

v6 → v7

v5 → v6

Build docs developers (and LLMs) love

Get started for freeTalk to us