Soft Keyboard Controller

A lightweight, dependency-free JavaScript library that gives you control over when the browser's soft (virtual) keyboard is allowed to appear.

Designed especially for:

• 📦 Warehouse applications
• 📱 Android PDA / Barcode Scanner devices
• 🏪 Inventory management systems
• 🛒 POS systems
• 🌐 Progressive Web Apps (PWA)

Instead of constantly showing the on-screen keyboard, the library uses the standard HTML inputmode attribute to suppress it until the user intentionally enables it.

Features

• ✅ Zero dependencies
• ✅ Framework agnostic (Vanilla JS, React, Vue, Angular, Svelte, etc.)
• ✅ Supports dynamic DOM elements
• ✅ Enable/Disable keyboard globally
• ✅ Automatic disable when all inputs lose focus
• ✅ Double-click activation
• ✅ Double-tap activation (mobile-friendly)
• ✅ Manual activation mode
• ✅ Configurable selectors
• ✅ Preserve original inputmode
• ✅ Ignore specific inputs
• ✅ Lifecycle callbacks
• ✅ Destroy and cleanup
• ✅ Tiny footprint

Installation

npm

npm install soft-keyboard-controller

Yarn

yarn add soft-keyboard-controller

pnpm

pnpm add soft-keyboard-controller

Node.js Support

Using the package

The published package is built before being published to npm.

• Node.js >= 14 is supported for consuming the package.

Building from source

If you clone the repository and build it yourself, the development toolchain has additional requirements:

• Node.js >= 22 is required to run npm run build (Rollup 4.x and related tooling).

This requirement only applies to contributors building the project from source and does not affect users installing the published package from npm.

Basic Usage

ESM (recommended)

import { SoftKeyboardController } from "soft-keyboard-controller";

const keyboard = new SoftKeyboardController();

Default import (also supported)

import SoftKeyboardController from "soft-keyboard-controller";

const keyboard = new SoftKeyboardController();

By default:

• Soft keyboard starts disabled
• Double-clicking an input enables it
• Keyboard stays enabled while an input is focused
• Keyboard automatically disables when no supported input has focus

Configuration

const keyboard = new SoftKeyboardController({

    selector:
        'input[type="text"], input[type="search"], textarea',

    defaultEnabled: false,

    activation: "dblclick",

    deactivateOnBlur: true,

    blurDelay: 10,

    inputModeEnabled: "text",

    inputModeDisabled: "none",

    preserveInputMode: true,

    ignore: ".no-keyboard",

    onEnable() {
        console.log("Keyboard enabled");
    },

    onDisable() {
        console.log("Keyboard disabled");
    }

});

Options

| Option | Type | Default | Description | | ----------------- | ----------------- | ------------ | ----------------------------------------- | | selector | string | text inputs | CSS selector of controlled elements | | defaultEnabled | boolean | false | Initial keyboard state | | activation | string | "dblclick" | Activation method | | deactivateOnBlur | boolean | true | Disable when all inputs lose focus | | blurDelay | number | 10 | Delay before blur check (ms) | | doubleTapDelay | number | 300 | Maximum time (ms) between taps for double‑tap detection.| | inputModeEnabled | string | "text" | inputmode applied when enabled | | inputModeDisabled | string | "none" | inputmode applied when disabled | | preserveInputMode | boolean | true | Restore each element's original inputmode | | ignore | string / function | null | Ignore elements |

Activation Modes

Double Click

activation: "dblclick"

Desktop-friendly.

Double Tap

activation: "doubletap"

Recommended for Android PDA devices.

Click

activation: "click"

Enable keyboard with a single click.

Manual

activation: "manual"

The library never enables the keyboard automatically.

You control it yourself:

keyboard.enable();

Public API

enable()

Enable the soft keyboard globally.

keyboard.enable();

disable()

Disable the soft keyboard globally.

keyboard.disable();

toggle()

Toggle the current state.

keyboard.toggle();

refresh()

Refresh controlled elements.

Useful when new inputs are added dynamically.

keyboard.refresh();

destroy()

Removes all event listeners.

keyboard.destroy();

setSelector()

Change controlled elements.

keyboard.setSelector(".scan-input");

Properties

enabled

Returns current keyboard state.

if (keyboard.enabled) {

}

Ignoring Elements

Using a selector:

ignore: ".manual-only"

<input class="manual-only">

Using a function:

ignore(element) {
    return element.dataset.keyboard === "false";
}

<input data-keyboard="false">

Preserve Original Input Mode

The library remembers the original inputmode of every element.

Example:

<input inputmode="numeric">

When enabled, the library restores:

numeric

instead of forcing:

text

Dynamic Inputs

Works with dynamically added elements.

document.body.insertAdjacentHTML(
    "beforeend",
    '<input type="text">'
);

keyboard.refresh();

CommonJS Example

const { SoftKeyboardController } = require("soft-keyboard-controller");

const keyboard = new SoftKeyboardController();

React Example

import { useEffect } from "react";
import { SoftKeyboardController } from "soft-keyboard-controller";

export default function App() {

    useEffect(() => {

        const keyboard =
            new SoftKeyboardController();

        return () => keyboard.destroy();

    }, []);

    return (
        <input type="text" />
    );

}

Vue Example

import { SoftKeyboardController }
from "soft-keyboard-controller";

const keyboard =
new SoftKeyboardController();

Scanner Workflow

Recommended settings for Android PDA devices.

new SoftKeyboardController({

    activation: "doubletap",

    defaultEnabled: false,

    deactivateOnBlur: true

});

Workflow:

1. User scans barcode.
2. Soft keyboard stays hidden.
3. User double taps an input.
4. Keyboard appears.
5. User can move between fields.
6. Clicking outside disables the keyboard again.

Browser Support

Supports modern browsers that implement the HTML inputmode attribute.

• Chrome
• Edge
• Firefox (partial)
• Safari
• Android Chrome
• Android WebView
• Most enterprise Android PDA browsers

Limitations

This library does not directly control the operating system keyboard.

Instead, it uses the standard HTML inputmode attribute, allowing browsers that support it to suppress the soft keyboard.

Some older Android WebViews may ignore inputmode="none".

Contributing

Issues and pull requests are welcome.

Please open an issue before submitting major changes.

License

MIT License

🍉 Solidarity & Action

If this project has helped you, please consider taking a moment to support the people of Gaza.

• 🏥 Medical Aid for Palestinians (MAP)
• 🍽️ World Food Programme - Palestine
• 📰 Decolonize Palestine (Educational Resource)