Understanding System Keyboard Height and Custom Keyboard Integration in Flutter

The article begins with a narrative introduction and then dives into the technical details of handling system and custom keyboards in Flutter, focusing on achieving smooth transitions by accurately measuring the system keyboard height.

System Keyboard State

To switch seamlessly between the system keyboard and a custom keyboard, you need to know the system keyboard's status. In Flutter, this information is accessed via WidgetsBinding.instance.window , although some APIs are deprecated in newer versions.

viewInsets

The viewInsets.bottom property represents the real-time height of the keyboard, which must be divided by the device pixel ratio to obtain logical pixels.

final WindowPadding viewInsets;

viewPadding

viewPadding.bottom indicates the fixed safe area at the bottom of the screen, typically a constant value (e.g., 34 on iPhone).

final WindowPadding viewPadding;

padding

The padding.bottom value changes with the keyboard visibility, becoming zero when the keyboard is shown.

final WindowPadding padding;

Debugging Values

Using MediaQuery.of(context) , the article logs keyboard height, viewPadding, and padding values on an iPhone simulator, showing how they evolve when the keyboard opens and closes.

flutter: keyboardHeight:0.0------viewPadding:34.0-----padding:34.0
flutter: keyboardHeight:346.0------viewPadding:34.0-----padding:0.0

SafeArea

Instead of directly accessing WidgetsBinding.instance.window , the recommended approach is to use MediaQuery through the widget context, which automatically rebuilds when window metrics change.

MediaQuery.of(context).viewInsets.bottom
MediaQuery.of(context).viewPadding.bottom
MediaQuery.of(context).padding.bottom

Custom Keyboard Design

The article outlines design goals for a custom keyboard: simplicity, pure Flutter implementation, and smooth switching with the system keyboard. Two keyboard “wheelchairs” are proposed to meet different scenarios.

SystemKeyboard

A manager that caches system keyboard height for later reuse.

Future
main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await SystemKeyboard().init();
  runApp(const MyApp());
}

KeyboardBuilder & KeyboardTypeBuilder

These widgets allow toggling between system and custom keyboards while preserving focus. Example code shows a TextField set to readOnly: true and showCursor: true to prevent the system keyboard from appearing.

TextField(
  showCursor: true,
  readOnly: true,
)

CustomKeyboardController

Provides methods such as showCustomKeyboard() , showSystemKeyboard() , hideCustomKeyboard() , and unfocus() to control keyboard behavior.

TextInputScope

Wraps the input area and custom keyboards, ensuring Scaffold.resizeToAvoidBottomInset is set to false for proper layout handling.

Scaffold(
  resizeToAvoidBottomInset: false,
  body: SafeArea(
    bottom: true,
    child: KeyboardBuilder(
      builder: (context, systemKeyboardHeight) => Container(),
      bodyBuilder: (readOnly) => Column(
        children: [
          TextField(readOnly: readOnly, showCursor: true),
          // toggle button using KeyboardTypeBuilder
        ],
      ),
    ),
  ),
);

Installation

Add the extended_keyboard package to pubspec.yaml or run flutter pub add extended_keyboard .

dependencies:
  extended_keyboard: ^latest_version

Conclusion

The article concludes that the system keyboard height includes the safe area, and provides a formula to calculate custom keyboard height: customHeight = systemHeight - fixedSafeArea + variableSafeArea . This knowledge enables developers to create custom keyboards that match the system keyboard's dimensions for a seamless user experience.