jh_keyboard_helper #

English | 简体中文

Predictable keyboard visibility, dismissal, interaction barriers, and layout helpers for Flutter applications.

Features #

• Observe keyboard visibility and height without platform plugins.
• Dismiss focus when a background area is tapped.
• Block underlying interactions while the keyboard is visible.
• Add keyboard padding only when Scaffold does not resize automatically.
• Keep keyboard behavior explicit and controlled at the application boundary.

Installation #

dependencies:
  jh_keyboard_helper: ^0.1.0

Quick start #

Install KeyboardBuilder near the application root:

import 'package:flutter/material.dart';
import 'package:jh_keyboard_helper/jh_keyboard_helper.dart';

Future<void> main() async {
  final cachedHeight = await loadKeyboardHeight();
  runApp(
    KeyboardBuilder(
      initialHeight: cachedHeight,
      onHeightSettled: saveKeyboardHeight,
      child: const MyApp(),
    ),
  );
}

Then use the focused helper for each screen:

KeyboardDismissOnTap(
  child: Scaffold(
    body: const TextField(),
  ),
)

Complete Flutter example #

The example directory is a complete, directly runnable Flutter application rather than a standalone code snippet. It includes Android, iOS, web, macOS, Linux, and Windows runner projects.

cd example
fvm flutter pub get
fvm flutter run

The application demonstrates:

• installing KeyboardBuilder at the application root;
• dismissing focus by tapping outside a text field;
• preventing the same tap from activating content below KeyboardBarrier;
• observing the keyboard height reported by KeyboardManager.

Controlled interaction barrier #

KeyboardBarrier deliberately intercepts all taps while the keyboard is visible. The first tap may dismiss the keyboard, but it never activates the underlying control. This is useful when accidental submissions or navigation must be prevented.

KeyboardBarrier(
  dismissOnTap: true,
  child: checkoutContent,
)

Set dismissOnTap to false when dismissal must be triggered by an explicit action. The barrier still blocks the content.

Keyboard-aware padding #

KeyboardPadding assumes the surrounding Scaffold uses its default resizeToAvoidBottomInset: true, so it does not add the keyboard height twice.

When scaffold resizing is disabled, configure both widgets consistently:

Scaffold(
  resizeToAvoidBottomInset: false,
  body: KeyboardPadding(
    scaffoldResizesForKeyboard: false,
    child: content,
  ),
)

Observing keyboard state #

final manager = KeyboardManager.instance;

ValueListenableBuilder<bool>(
  valueListenable: manager.visible,
  builder: (context, visible, child) {
    return Text(visible ? 'Visible' : 'Hidden');
  },
);

height exposes a ValueListenable<double>, while heightStream is available for stream-based consumers. Heights are expressed in logical pixels.

Flutter reports multiple intermediate inset values while the keyboard animates. KeyboardBuilder waits for those metrics to settle before calling onHeightSettled. Persist that value with the application's preferred storage and pass it back through initialHeight on the next launch. The restored height keeps layout stable while Flutter reports intermediate values. This package does not depend on a specific persistence library.

API overview #

Scope #

This package does not render a custom keyboard, manage form validation, or change platform window modes. It has no runtime dependency beyond Flutter.

License #

MIT License. See LICENSE.