Understanding Flutter Keyboard Invocation, Issues, and Performance Optimizations

Background

When using Flutter we often encounter keyboard‑related problems; this article describes the soft‑keyboard invocation process, the underlying mechanisms, and several known issues with their solutions.

Flutter Keyboard Process and Principles

Keyboard pop‑up involves Android’s InputMethodManager.showSoftInput via TextInputPlugin and iOS’s UITextInput.becomeFirstResponder . The system triggers the keyboard animation, while Flutter shifts the UI by changing WindowInsets , causing a repaint.

Page Repaint Logic

When the keyboard appears, WindowInsets changes, propagating to Metrics , which are transferred from the platform thread to the UI thread, finally invoking scheduleForceFrame to force a frame draw.

Page Shrink Animation

Adding an AnimatedContainer that reacts to window.viewInsets.bottom / window.devicePixelRatio provides a smoother animation.

Keyboard‑Related Issues

Keyboard Animation Jank

On some devices (e.g., Samsung S10) the keyboard animation triggers a build on every frame, causing noticeable jank. The root cause is repeated MediaQuery updates because WindowInsets changes continuously.

Solutions: set a flag Performance.setCurrentIsKeyboardScene to suppress MediaQuery changes for 300 ms, and replace AnimatedContainer with Padding when rapid metric changes are detected.

Keyboard Not Dismissing After Lock Screen

When the device locks while the keyboard is visible, the focus is lost but the native TextInput.hide call is not executed because the textInputMethodHandler becomes null during FlutterView.detachFromFlutterEngine . The fix records the keyboard state and explicitly calls hide when the handler is cleared.

Sogou Input Method on iOS – Send Button Inserts Space

Long‑pressing the send button generates a carriage‑return (ASCII 13) instead of a line‑feed (ASCII 10). Replacing the character in EditableTextState.updateEditingValue or the plugin resolves the issue.

iOS Cursor Animation CPU Spike

The default cursor fade animation consumes 16 % CPU on iPhone 12. Switching to the Android‑style instant‑alpha animation reduces the load.

Cursor Remains After Keyboard Dismissal on iOS

Flutter keeps the cursor flashing after the iOS keyboard hides. Listening to keyboard‑hide notifications and clearing the cursor restores native behavior.

iOS12+ Long‑Press Space Cursor Lag with Non‑Latin Text

Long‑press space for cursor movement stalls on non‑English characters. Adding a UITextInteraction to FlutterTextInputView (as in Flutter engine PR #26486) fixes the lag.

Conclusion

Understanding the full keyboard invocation flow—native calls, WindowInsets changes, MediaQuery updates, and frame scheduling—helps locate and resolve performance or functional bugs in Flutter applications. Tools such as Systrace and Instruments are valuable for tracing these issues.