Troubleshooting

The failures that come up most, and what each one usually turns out to be.

Install#

flutter pub add virtual_keypad

import 'package:virtual_keypad/virtual_keypad.dart';

Both keyboards appear#

The system keyboard opens alongside the on-screen one. Almost always a missing standalone: true: without it the keypad does not take over the field, so the platform opens its own.

VirtualKeypad(standalone: true)

Do not reach for readOnly: true to silence the system keyboard. It works, and it also removes the caret and text selection, which users notice.

Nothing types#

Check in this order. No field is focused, so there is nowhere to type. Or the keypad is in scope mode without a VirtualKeypadScope above it. Or a plain TextField is being used in scope mode, where VirtualKeypadTextField is required.

VirtualKeypadScope(
  child: Column(
    children: [
      VirtualKeypadTextField(controller: controller),
      const VirtualKeypad(),
    ],
  ),
)

The keyboard is invisible or has no height#

A keyboard inside an unbounded parent gets no height to lay out in. A Column inside a SingleChildScrollView is the usual source. Give it a bounded box or put it outside the scroll view.

Keys are cut off at the sides#

The keyboard fills the width it is given, so a narrow parent squeezes the keys. Set width explicitly, or use the floating panel with maxWidth, which was made for this.

Switching language does nothing#

initializeKeyboardLayouts() was never called, so only English is registered and every switch resolves back to it. Call it once at startup, before the keyboard is built.

void main() {
  initializeKeyboardLayouts();
  runApp(const MyApp());
}

The language picker never opens#

It opens on a long press of the space bar, and only when availableLanguages holds more than one code. With one entry there is nothing to pick.

Emoji are blank boxes#

On web, a first offline load has no emoji font yet. The package bundles a subset font for exactly that, so if you are still seeing boxes the font asset is likely missing from the build. On older Android some emoji genuinely have no glyph; checkEmojiPlatformCompatibility: true hides those instead of showing boxes.

A custom layout throws on build#

customLayout and type: KeyboardType.custom must be used together. Each without the other asserts in debug on purpose, so the mistake surfaces at build time rather than as an empty keyboard.

The D-pad moves app focus instead of the highlight#

enableDpadNavigation: true is missing. Note also that an arrow at the edge of the grid is deliberately left unhandled so focus can leave the keyboard, and that space does not press a key, so a paired Bluetooth keyboard still types spaces.

Keys click twice, or not at all#

Feedback is driven by the feedback parameter, not by Material's ink response, so a press is confirmed the same way whether it came from a tap or a D-pad. KeyFeedback.sound is the default; use none for silence or both to add a vibration.

VirtualKeypad(feedback: KeyFeedback.none)

Something else#

The issue tracker is the place. The platform, the mode you are using, and the smallest snippet that reproduces it are what make a report actionable.