flutter_keyboard_controller

Frame-by-frame keyboard tracking for Flutter — smooth animations, auto-scroll forms, chat UIs, sticky toolbars, and a full imperative API. Built on native CADisplayLink (iOS) and WindowInsetsAnimationCompat + OnApplyWindowInsetsListener (Android).

Preview

1. Form auto-scroll

KeyboardAwareScrollView auto-scrolls to the focused field including labels and error text.

2. Chat lift

KeyboardChatScrollView lifts the message list with 4 configurable behaviors.

KeyboardToolbar slides in sync with the keyboard, pixel-perfect.

Why this library?

Flutter's built-in keyboard handling

Flutter ships two mechanisms:

Scaffold(resizeToAvoidBottomInset: true) (default)

Scaffold body shrinks in one jump when keyboard animation ends — not per-frame.
TextField.scrollPadding calls Scrollable.ensureVisible() on the raw TextField bounds — ignores labels or error text below the field.
Android: on some devices (Samsung) a keyboard-type switch causes a static layout pass with no animation, so Flutter's scroll simply doesn't fire.

MediaQuery.viewInsetsOf(context)

Returns height only after animation ends.
Every widget reading it rebuilds — cascades through the entire InheritedWidget tree.
No progress value (0→1), no lifecycle events, no interactive-dismiss tracking.

Deep comparison

	Flutter built-in	flutter_keyboard_controller
Height timing	After animation ends	Every frame
Progress 0→1	❌	✅ `progressNotifier`
Lifecycle events	❌	✅ `willShow / didShow / willHide / didHide / move / interactive`
iOS interactive dismiss	Estimated	✅ `CADisplayLink` exact position
Android keyboard-type switch	❌ Missed on Samsung	✅ `setOnApplyWindowInsetsListener` safety net
Rebuild scope	Entire `MediaQuery` subtree	Single `ValueListenableBuilder`
Auto-scroll to field	✅ raw `TextField` only	✅ full widget bounds (label + error) via `KeyboardScrollBoundary`
Auto-scroll when `resizeToAvoidBottomInset: false`	❌	✅
Global dismiss (tap/drag)	Per-ScrollView only	✅ `KeyboardProvider.dismissBehavior`
Chat lift behaviors	❌	✅ `KeyboardChatScrollView`
Sticky widget above keyboard	❌	✅ `KeyboardStickyView`
Prev/Next/Done toolbar	❌	✅ `KeyboardToolbar`
`dismiss(keepFocus, animated)`	❌	✅
Preload keyboard (iOS lag)	❌ ~300 ms	✅ `KeyboardController.preload()`
Android soft-input mode	Manifest only	✅ `setInputMode()` at runtime

Performance

Flutter built-in: O(N) — rebuilds the entire MediaQuery subtree (Scaffold → theme → every consumer)
                         every time the keyboard opens or closes.

This library:     O(1) — only the specific Padding/Transform wrapper updates via ValueListenableBuilder.
                         Heavy widgets (lists, cards, images) remain completely static.

Always pass stable content as child: to ValueListenableBuilder so it never rebuilds per-frame:

// ✅ child: never rebuilds — only Padding wrapper does (~60×/s during anim)
ValueListenableBuilder<double>(
  valueListenable: context.keyboard.heightNotifier,
  child: const MyList(),
  builder: (_, height, child) => Padding(
    padding: EdgeInsets.only(bottom: height),
    child: child,
  ),
);

What are you building?
│
├─ Form with many text fields → KeyboardAwareScrollView
│
├─ Chat / AI-chat UI         → KeyboardChatScrollView + KeyboardStickyView
│
├─ Fixed layout (compose,    → KeyboardAvoidingView  (adjusts whole container)
│  search bar, login page)     OR KeyboardStickyView (just the input bar)
│
└─ Form + Prev/Next/Done     → KeyboardToolbar (pair with KeyboardAwareScrollView)

`KeyboardAvoidingView` vs `KeyboardStickyView` — most common confusion

	`KeyboardAvoidingView`	`KeyboardStickyView`
What adjusts	The entire layout container	One specific widget
Content behind keyboard	✅ Never hidden	❌ Keyboard overlaps it
Use case	Compose screen	Chat input bar

Installation

dependencies:
  flutter_keyboard_controller: ^1.0.0

Android: min SDK 24.
iOS: min iOS 13.

Quick start

import 'package:flutter_keyboard_controller/flutter_keyboard_controller.dart';

void main() {
  runApp(
    // ⚠️ KeyboardProvider must wrap your entire app (above MaterialApp /
    // CupertinoApp). Placing it below Scaffold causes keyboard state to reset
    // on every route push/pop and bottom-sheet open.
    KeyboardProvider(
      dismissBehavior: KeyboardDismissBehavior.onTapAndDrag,
      child: MaterialApp(home: MyApp()),
    ),
  );
}

KeyboardProvider

Root widget. Required for all features.

⚠️ Important: Always place KeyboardProvider above MaterialApp / CupertinoApp. If placed below Scaffold, keyboard state resets on every route push/pop and breaks overlay handling for dialogs and bottom sheets.

KeyboardProvider(
  enabled: true,
  dismissBehavior: KeyboardDismissBehavior.onTapAndDrag,
  child: MaterialApp(...),  // ✅ correct — wraps the entire app
)

`KeyboardDismissBehavior`	Effect
`manual`	Never auto-dismiss (default)
`onTap`	Dismiss on tap outside
`onDrag`	Dismiss on scroll
`onTapAndDrag`	Both

Reading keyboard state

final animation = context.keyboard;          // subscribes — widget rebuilds
final animation = context.keyboardOrNull;    // no subscription

KeyboardAwareScrollView

When to use: Multi-field forms (sign-up, profile, settings).

How it works:

Adds bottom padding = keyboard height so maxScrollExtent grows → content is scrollable above keyboard.
_onFocusChanged fires on every focus change → addPostFrameCallback triggers _scrollToFocusedInput.
KeyboardGeometryService calculates the target scroll offset using the field's RenderBox coordinates.
_isDismissing + ModalRoute.isCurrent prevent unwanted scrolls when a bottom sheet opens.
Android: setOnApplyWindowInsetsListener catches static keyboard-type switches that WindowInsetsAnimationCompat misses.

vs Flutter built-in:

Flutter: body snaps, scrolls to raw TextField bounds only, fails on resizeToAvoidBottomInset: false.
This: smooth per-frame padding, scrolls to full widget height (labels + errors), works independently of Scaffold.

Scaffold(
  resizeToAvoidBottomInset: false,
  body: KeyboardAwareScrollView(
    padding: const EdgeInsets.all(16),
    children: [
      // Plain field — scrolled to raw TextField bounds
      TextField(decoration: InputDecoration(labelText: 'Email')),

      // Custom widget — KeyboardScrollBoundary tells the scroll view to
      // include the label AND the red error text below the field.
      // Without it, only the raw TextField bounds are used and the error
      // text gets hidden behind the keyboard.
      KeyboardScrollBoundary(
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.start,
          children: [
            const Text('Password'),
            const TextField(obscureText: true),
            const Text(
              'Must be at least 8 characters',
              style: TextStyle(color: Colors.red, fontSize: 12),
            ),
          ],
        ),
      ),

      FilledButton(onPressed: submit, child: const Text('Sign in')),
    ],
  ),
)

`KeyboardScrollBoundary` — for custom input widgets

Wrap your custom widget's root once so KeyboardAwareScrollView measures the full widget height (label + input + error text). No per-screen config needed — every screen using KeyboardAwareScrollView benefits automatically.

// Inside AppTextInput.build() — wrap once, works everywhere:
return KeyboardScrollBoundary(
  child: Column(children: [label, textField, errorText]),
);

Parameters

Param	Default	Description
`children`	required	Content widgets
`padding`	`null`	Outer padding
`scrollPadding`	`EdgeInsets.all(20)`	Gap between field and keyboard edge
`animationDuration`	`300 ms`	Scroll animation duration
`animationCurve`	`Curves.easeOut`	Scroll animation curve
`physics`	platform	`ScrollPhysics`
`scrollContextFinder`	`null`	Override ancestor traversal

KeyboardAvoidingView

When to use: Fixed layouts where the entire container must adapt to the keyboard — login screen, compose screen, search overlay.

How it works:

LayoutBuilder captures parent height once. ValueListenableBuilder on heightNotifier applies the behavior per-frame.
Always returns the same wrapper widget type regardless of keyboard state, so Flutter never unmounts the subtree and FocusNodes keep their state.

vs Flutter built-in:

Flutter's resizeToAvoidBottomInset: true snaps the body in one step.
KeyboardAvoidingView follows the keyboard smoothly every frame.

Scaffold(
  resizeToAvoidBottomInset: false,
  body: KeyboardAvoidingView(
    behavior: KeyboardAvoidingBehavior.padding,
    child: Column(children: [
      Expanded(child: content),
      inputBar,  // lifts smoothly with keyboard
    ]),
  ),
)

Behaviors

`behavior`	Effect	Constraints
`padding`	Adds `paddingBottom`	Works with any parent
`height`	Reduces `maxHeight`	Parent must give loose constraints (`Flexible`, not `Expanded`)
`position`	Translates view upward	Content may go behind AppBar
`translateWithPadding`	Half translate + half padding	Middle ground

⚠️ height behavior requires a parent with loose constraints. Use Flexible instead of Expanded.

Why? Expanded passes tight constraints (exact size) to its child. When the Flutter layout engine receives tight constraints it ignores any attempt to shrink the child — KeyboardAvoidingView simply can't reduce its height. Flexible passes loose constraints (maximum size), which allows the view to actually shrink to dodge the keyboard.

KeyboardChatScrollView

When to use: Chat, messaging, AI assistant — reversed list with a floating input bar.

How it works:

ListView(reverse: true) with padding.bottom adjusted per-frame via heightNotifier.
No viewport resize — keyboard overlays. Lifting is pure padding change (no jumpTo needed).
Four lift behaviors match popular apps.

vs Flutter built-in: No built-in equivalent. The naive resizeToAvoidBottomInset: true approach causes the list to flash/jump on keyboard open.

Scaffold(
  resizeToAvoidBottomInset: false,
  body: Stack(children: [
    Positioned.fill(
      child: KeyboardChatScrollView(
        liftBehavior: KeyboardLiftBehavior.whenAtEnd,
        extraBottomPadding: 72,  // floating input bar height
        safeAreaBottom: MediaQuery.of(context).viewPadding.bottom,
        children: messages.map((m) => MessageBubble(m)).toList(),
      ),
    ),
    ValueListenableBuilder<double>(
      valueListenable: context.keyboard.heightNotifier,
      child: InputBar(),
      builder: (_, kbH, child) => Positioned(
        left: 0, right: 0, bottom: kbH, child: child!,
      ),
    ),
  ]),
)

Lift behaviors

`liftBehavior`	When lifts	Inspired by
`always`	Every time keyboard opens	Telegram
`whenAtEnd`	Only when at newest message	WhatsApp, ChatGPT
`persistent`	Opens and stays lifted	Claude.ai
`never`	Never lifts	Perplexity

KeyboardStickyView

When to use: A single widget (input bar, send button) that must always sit just above the keyboard.

How it works:

Align(bottomCenter) + Padding(bottom: kbH + extraOffset) driven by heightNotifier.
Follows the keyboard pixel-perfectly every frame including iOS interactive swipe-dismiss.

vs Flutter built-in: MediaQuery.viewInsetsOf only updates after animation — widget teleports. KeyboardStickyView slides smoothly.

Stack(
  children: [
    Positioned.fill(child: chatList),
    KeyboardStickyView(
      offset: const KeyboardStickyOffset(closed: 0, opened: 8),
      child: InputBar(),
    ),
  ],
)

KeyboardToolbar

When to use: Forms with multiple fields where Prev/Next/Done navigation improves UX.

How it works:

_ToolbarVisibility subscribes to lastEventNotifier (not heightNotifier) so it reacts to lifecycle events, not per-frame height.
Slides in/out via ClipRect + Align(heightFactor) in sync with keyboard animation.
KeyboardToolbarScaffold with resizeToAvoidBottomInset: false uses a Stack + Positioned.fill(VLB) so Positioned inside VLB issue is avoided.
Android: _isSwitching flag + _savedKbH keeps toolbar at correct height during keyboard-type switches.

vs Flutter built-in: No built-in toolbar. Workarounds using MediaQuery cause the toolbar to teleport (appear/disappear in one frame) instead of sliding.

KeyboardToolbarScaffold(
  resizeToAvoidBottomInset: false,
  toolbar: KeyboardToolbar(
    margin: const EdgeInsets.fromLTRB(8, 0, 8, 8),
    borderRadius: BorderRadius.circular(100),  // pill
    doneLabel: 'Xong',
    arrowColor: Colors.blue,
    doneColor: Colors.blue,
    onPrev: () => FocusScope.of(context).previousFocus(),
    onNext: () => FocusScope.of(context).nextFocus(),
    actions: [
      KeyboardToolbarAction(icon: Icons.tag, onPressed: insertTag),
      KeyboardToolbarAction(
        icon: Icons.photo_camera_outlined,
        onPressed: openCamera,
        isSelected: _cameraMode,
        selectedColor: Colors.blue,
      ),
    ],
  ),
  body: KeyboardAwareScrollView(children: [...]),
)

`KeyboardToolbar` parameters

Param	Default	Description
`doneLabel`	`'Done'`	Dismiss button text (multilang)
`arrowColor`	primary	Prev/Next arrow color
`doneColor`	primary	Done button color
`showArrows`	`true`	Show Prev/Next arrows
`actions`	`[]`	Custom icon buttons (≤ 5)
`margin`	`null`	Outer margin for floating pill effect
`borderRadius`	`null`	Corner radius for pill shape
`toolbarScrollClearance`	`64`	Extra scroll padding so fields clear the toolbar

KeyboardAnimation — raw values

final animation = context.keyboard;

// Only this widget rebuilds per frame
ValueListenableBuilder<double>(
  valueListenable: animation.heightNotifier,
  child: const MyFAB(),
  builder: (_, height, fab) => Positioned(
    right: 16, bottom: 16 + height, child: fab!,
  ),
);

Notifier	Type	Description
`heightNotifier`	`ValueNotifier<double>`	Keyboard height in dp (0 when hidden)
`progressNotifier`	`ValueNotifier<double>`	Progress 0→1
`isVisibleNotifier`	`ValueNotifier<bool>`	Whether keyboard is visible
`lastEventNotifier`	`ValueNotifier<KeyboardEventData?>`	Last native event

Lifecycle events

animation.lastEventNotifier.addListener(() {
  switch (animation.lastEvent?.type) {
    case KeyboardEventType.willShow: // about to appear
    case KeyboardEventType.didShow:  // fully visible
    case KeyboardEventType.willHide: // about to hide
    case KeyboardEventType.didHide:  // fully hidden
    case KeyboardEventType.move:     // per-frame during animation
    case KeyboardEventType.interactive: // iOS swipe-dismiss
  }
});

KeyboardController — imperative API

await KeyboardController.dismiss();
await KeyboardController.dismiss(keepFocus: true);   // hide keys, cursor stays
await KeyboardController.dismiss(animated: false);   // iOS: instant

final visible = await KeyboardController.isVisible();
final state   = await KeyboardController.state();    // height, isVisible

KeyboardController.preload();                        // iOS: eliminate cold-start lag

// Android only
KeyboardController.setInputMode(AndroidSoftInputMode.adjustNothing);
KeyboardController.setDefaultMode();

Architecture notes

Android — two-layer keyboard tracking

This library uses two complementary mechanisms on Android:

WindowInsetsAnimationCompat.Callback — tracks per-frame height during animated keyboard transitions. Fires willShow/move/didShow/willHide/didHide events.
setOnApplyWindowInsetsListener (safety net) — catches static keyboard-type switches (e.g. text → number keyboard) where Android performs a layout pass with no animation. Without this, heightNotifier would stay at the old value and the toolbar/scroll would appear mispositioned.

The isAnimating flag prevents duplicate events when both fire for the same transition.

`KeyboardGeometryService`

DOM traversal and scroll-offset math are extracted into KeyboardGeometryService (under lib/src/services/). This means:

KeyboardAwareScrollView is a thin UI layer — only renders and triggers events.
Geometry logic is independently unit-testable without rendering.

`KeyboardScrollBoundary`

A zero-overhead marker widget (build returns child unchanged). KeyboardGeometryService.resolveTargetContext walks ancestors looking for it. Wrap your custom input's root widget once — no per-screen config.

API summary

Widgets

Widget	Purpose
`KeyboardProvider`	Root — required. Enables all features.
`KeyboardScrollBoundary`	Marks full bounds of a custom input (label + input + error)
`KeyboardAwareScrollView`	Form scroll — auto-scrolls focused field above keyboard
`KeyboardAvoidingView`	Adjusts entire container with 4 behaviors
`KeyboardChatScrollView`	Chat list with 4 lift behaviors
`KeyboardStickyView`	Sticks one widget to keyboard top edge
`KeyboardToolbar`	Prev/Next/Done toolbar above keyboard
`KeyboardToolbarScaffold`	Convenience scaffold wiring `KeyboardToolbar`

Enums

Enum	Values
`KeyboardDismissBehavior`	`manual`, `onTap`, `onDrag`, `onTapAndDrag`
`KeyboardAvoidingBehavior`	`padding`, `height`, `position`, `translateWithPadding`
`KeyboardLiftBehavior`	`always`, `whenAtEnd`, `persistent`, `never`
`KeyboardEventType`	`willShow`, `didShow`, `willHide`, `didHide`, `move`, `interactive`
`AndroidSoftInputMode`	`adjustResize`, `adjustPan`, `adjustNothing`, `adjustUnspecified`

Changelog

See CHANGELOG.md.

flutter_keyboard_controller

Preview

1. Form auto-scroll

2. Chat lift

Why this library?

Flutter's built-in keyboard handling

Deep comparison

Performance

Which widget should I use?

`KeyboardAvoidingView` vs `KeyboardStickyView` — most common confusion

Installation

Quick start

KeyboardProvider

Reading keyboard state

KeyboardAwareScrollView

`KeyboardScrollBoundary` — for custom input widgets

Parameters

KeyboardAvoidingView

Behaviors

KeyboardChatScrollView

Lift behaviors

KeyboardStickyView

KeyboardToolbar

`KeyboardToolbar` parameters

KeyboardAnimation — raw values

Lifecycle events

KeyboardController — imperative API

Architecture notes

Android — two-layer keyboard tracking

`KeyboardGeometryService`

`KeyboardScrollBoundary`

API summary

Widgets

Enums

Changelog

License

Libraries

flutter_keyboard_controller package

flutter_keyboard_controller

Preview

1. Form auto-scroll

2. Chat lift

3. Sticky toolbar

Why this library?

Flutter's built-in keyboard handling

Deep comparison

Performance

Which widget should I use?

KeyboardAvoidingView vs KeyboardStickyView — most common confusion

Installation

Quick start

KeyboardProvider

Reading keyboard state

KeyboardAwareScrollView

KeyboardScrollBoundary — for custom input widgets

Parameters

KeyboardAvoidingView

Behaviors

KeyboardChatScrollView

Lift behaviors

KeyboardStickyView

KeyboardToolbar

KeyboardToolbar parameters

KeyboardAnimation — raw values

Lifecycle events

KeyboardController — imperative API

Architecture notes

Android — two-layer keyboard tracking

KeyboardGeometryService

KeyboardScrollBoundary

API summary

Widgets

Enums

Changelog

License

Libraries

flutter_keyboard_controller package

`KeyboardAvoidingView` vs `KeyboardStickyView` — most common confusion

`KeyboardScrollBoundary` — for custom input widgets

`KeyboardToolbar` parameters

`KeyboardGeometryService`

`KeyboardScrollBoundary`