Registry / web-framework / simple-keyboard

simple-keyboard

library3.8.133jsnpmunverified

Simple-Keyboard is a robust, lightweight, and highly customizable JavaScript virtual keyboard library designed for web applications. Currently at version 3.8.133, it maintains a stable release cadence with frequent updates addressing bugs and adding features. Key differentiators include broad browser compatibility (down to IE11 with specific bundles), built-in TypeScript support since v3.0.0, and a modular architecture allowing extensions for autocorrect, input masks, and key navigation. It is designed to be framework-agnostic, easily integrating into vanilla JavaScript, React, Angular, and Vue projects, providing an on-screen input solution suitable for touchscreens, kiosks, and general web input fields.

web-framework http-networking

npm install simple-keyboard

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SIMPLE-KEYBOARD

simple-keyboard

web-frameworkjavascriptv3.8.133

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SimpleKeyboard

✓ import SimpleKeyboard from 'simple-keyboard';

✗ import { SimpleKeyboard } from 'simple-keyboard';

The `SimpleKeyboard` class is exported as a default. Since v3.7.0, ESM output is available. For CommonJS, `require('simple-keyboard')` directly returns the class.

KeyboardOptions

✓ import type { KeyboardOptions } from 'simple-keyboard';

This is the TypeScript interface for configuring the keyboard options, useful for type-checking your configuration object.

CSS Styles

✓ import 'simple-keyboard/build/css/index.css';

Imports the basic default styling for the keyboard. For modern browsers, `index.modern.css` is also available. Custom themes typically override these styles.

Initializes simple-keyboard with a custom layout, demonstrating how to handle input changes, key presses, and dynamically switch between 'default', 'shift', and 'numbers' layouts.

import SimpleKeyboard from 'simple-keyboard'; import 'simple-keyboard/build/css/index.css'; // Create a target input element in your HTML: <input class="input" value="" /> // And a container for the keyboard: <div class="simple-keyboard"></div> const inputElement = document.querySelector('.input') as HTMLInputElement; const keyboard = new SimpleKeyboard({ onChange: (input: string) => onChange(input), onKeyPress: (button: string) => onKeyPress(button), input: inputElement || undefined, // Pass the input element or its selector theme: 'hg-theme-default hg-layout-default', layout: { default: [ 'q w e r t y u i o p', 'a s d f g h j k l', '{shift} z x c v b n m {backspace}', '{numbers} {space} {ent}' ], shift: [ 'Q W E R T Y U I O P', 'A S D F G H J K L', '{shift} Z X C V B N M {backspace}', '{numbers} {space} {ent}' ], numbers: [ '1 2 3', '4 5 6', '7 8 9', '{abc} 0 .' ] } }); function onChange(input: string) { if (inputElement) { inputElement.value = input; } console.log('Input changed:', input); } function onKeyPress(button: string) { console.log('Button pressed:', button); if (button === '{shift}' || button === '{lock}') { handleShift(); } if (button === '{numbers}' || button === '{abc}') { handleLayoutChange(button); } } function handleShift() { const currentLayout = keyboard.options.layoutName; const newLayout = currentLayout === 'default' ? 'shift' : 'default'; keyboard.setOptions({ layoutName: newLayout }); } function handleLayoutChange(button: string) { const newLayout = button === '{numbers}' ? 'numbers' : 'default'; keyboard.setOptions({ layoutName: newLayout }); }

Debug

Known issues

breakingAs of `simple-keyboard` v3.5.0, the `display` option's styling rules were extended to also affect `layoutCandidates` box items. This could lead to unexpected visual changes if you previously relied on separate styling for these elements.

fix

Review and adjust your CSS rules targeting `layoutCandidates` if their appearance changed unexpectedly after upgrading.

affects: >=3.5.0

breakingIn `simple-keyboard` v3.1.0, the `{delete}` button's functionality was changed to perform forward deletion (deleting characters *after* the caret). If your application used a button named `{delete}` and expected it to behave like a backspace, its behavior will have changed.

fix

If you need backspace functionality, ensure your layout uses the `{backspace}` button. For forward delete, `{delete}` is now standard.

affects: >=3.1.0

breakingVersion 3.0.0 of `simple-keyboard` introduced a simplified module architecture. Custom modules are now simple functions that receive the `keyboard` instance as a parameter, replacing previous module integration patterns. Existing custom modules will require refactoring.

fix

Update any custom modules to adhere to the new function-based structure, directly accepting the `keyboard` instance. Consult the official documentation for updated module creation guidelines.

affects: >=3.0.0

gotchaPrior to v3.7.0, `simple-keyboard` primarily provided CommonJS modules. From v3.7.0 onwards, an ESM output (`index.modern.esm.js`) is included. Mixing import styles (e.g., using `require` in an ESM context) or incorrect module resolution for versions `>=3.7.0` can lead to runtime errors.

fix

For modern applications, prefer `import SimpleKeyboard from 'simple-keyboard';`. For Node.js CommonJS environments, `const SimpleKeyboard = require('simple-keyboard');` should work. Ensure your build tooling (e.g., Webpack, Rollup) is configured for proper dual ESM/CJS package resolution.

affects: >=3.7.0

gotchaIn `simple-keyboard` v3.4.0, the TypeScript type definitions were relocated from `build/types` directly to the `build` directory. This internal change could potentially affect projects with highly customized `tsconfig.json` configurations or those relying on absolute paths to type declaration files.

fix

Verify your TypeScript configuration, particularly `typeRoots` or `paths` settings, if you encounter type resolution errors after upgrading to v3.4.0 or later.

affects: >=3.4.0

gotcha`simple-keyboard` supports IE11 but requires using the `index.js` bundle. The `index.modern.js` bundle (introduced in v3.3.0) and ESM outputs are optimized for modern browsers and will not function correctly in IE11.

fix

For IE11 compatibility, explicitly target `simple-keyboard/build/index.js` in your `<script>` tag or bundler configuration, rather than `index.modern.js` or ESM builds.

affects: >=3.3.0

Errors

Common errors & fixes

TypeError: SimpleKeyboard is not a constructor

Attempting to instantiate `SimpleKeyboard` using incorrect import syntax (e.g., named import for a default export) or incorrect CommonJS `require` for ESM interop.

fix

Ensure you are using a default import: `import SimpleKeyboard from 'simple-keyboard';`. For CommonJS, `const SimpleKeyboard = require('simple-keyboard');` should correctly resolve the default export.

ReferenceError: document is not defined

`simple-keyboard` is a DOM-dependent library. This error occurs when attempting to initialize or interact with the keyboard in a non-browser environment, such as during Server-Side Rendering (SSR) without proper hydration or a mocked DOM.

fix

Ensure `simple-keyboard` initialization code is executed only in a client-side (browser) environment. For SSR applications, use dynamic imports with a `typeof window !== 'undefined'` check or a dedicated SSR solution to defer client-side code.

Argument of type 'HTMLElement | null' is not assignable to parameter of type 'string | HTMLInputElement'

In TypeScript, `document.querySelector` can return `null` or a generic `Element`, neither of which directly satisfies `simple-keyboard`'s `input` option (which expects `string | HTMLInputElement`).

fix

Add a type assertion to `HTMLInputElement` and ensure the element exists before passing it: `document.querySelector('.input') as HTMLInputElement;` then check if `inputElement` is not `null` before passing, or pass the CSS selector string directly to `input`.

Upgrade

Version history

3.8.133latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/hodgef/simple-keyboard ↗

packagehttps://www.npmjs.com/package/simple-keyboard ↗

homepagehttps://simple-keyboard.com ↗