repository·master·Indexed 25 days ago
https://github.com/hodgef/simple-keyboardA JavaScript virtual keyboard library providing a customizable UI for virtual text input. It is compatible with web frameworks such as React, Angular, and Vue. The library supports internal input state management, custom layouts, and extensibility through modules like Autocorrect, Input Mask, Key Navigation, and Swipe Keyboard. It includes features for caret positioning, multi-instance synchronization, and flexible styling via button themes and attributes.
The core functionality of simple-keyboard can be extended using specialized modules. Available modules include:
You can also create your own custom modules by following the instructions on the Modules page.
simple-keyboard supports older browsers like Internet Explorer 11. If you do not need to support legacy browsers, you can use the Modern Browsers bundle (index.modern.js) located in the build directory to reduce bundle size and improve performance.You can integrate simple-keyboard into your project using either an npm installation or by including a <script> tag from a CDN. For detailed implementation steps, refer to the Getting Started documentation.
To install via npm:
npm install simple-keyboardSimpleKeyboard automatically tracks the caret (cursor) position in input and textarea elements.
disableCaretPositioning: If set to true in options, the keyboard will not attempt to track or update the caret position.syncInstanceInputs: When enabled, the keyboard will detect input events from any instance that has the data-skInstance attribute, allowing multiple keyboards to potentially interact with the same input focus logic.updateCaretOnSelectionChange: If enabled, the keyboard listens to the selectionchange event to keep the caret position in sync with user selections (Note: Firefox may have limitations with this event).You can create a new instance of SimpleKeyboard by passing a selector (string), a DOM element, or an options object to the constructor.
If you pass a string, it is treated as the CSS class of the container element. If you pass an HTMLDivElement, it must have a class name. If you pass an object, it is treated as the KeyboardOptions object.
Note: The keyboard maintains an internal, non-persistent input state to decouple it from the DOM. You can manage multiple inputs by specifying an inputName in the options.
You can customize the appearance and HTML attributes of buttons using the buttonTheme and buttonAttributes options.
buttonTheme: An array of objects used to apply specific CSS classes to certain buttons. Each object must contain a class string (the classes to apply) and a buttons string (a space-separated list of button names that should receive these classes).buttonAttributes: An array of objects used to add custom HTML attributes to buttons. Each object must contain an attribute string, a value string, and optionally a buttons string (space-separated list of button names). If buttons is omitted, the attribute is applied to all buttons.To synchronize the visual state of the virtual keyboard with a physical keyboard, use these options:
physicalKeyboardHighlight: Enables highlighting of keys pressed on a physical keyboard.physicalKeyboardHighlightPress: If true, calls keyboard.handleButtonClicked(buttonName) for the highlighted button.physicalKeyboardHighlightPressUseClick: If true, triggers a native button.click() on the highlighted button.physicalKeyboardHighlightPressUsePointerEvents: Determines if physicalKeyboardHighlightPress should use pointer events.physicalKeyboardHighlightTextColor: Sets the text color for the highlighted key.physicalKeyboardHighlightBgColor: Sets the background color for the highlighted key.physicalKeyboardHighlightPreventDefault: If true, uses preventDefault to disable default browser actions during highlighting.The KeyboardOptions object allows you to customize the behavior and appearance of the keyboard. Key options include:
| Option | Type | Description |
|---|---|---|
layoutName | string | Specifies which layout to use (default: "default"). |
theme | string | CSS class for the keyboard wrapper. |
inputName | string | Identifier for the internal input (default: "default"). |
onKeyPress | function | Callback triggered on key press. Receives (button: string, event: KeyboardHandlerEvent). |
onChange | function | Callback triggered on input change. Receives (input: string, event: KeyboardHandlerEvent). |
onInit | function | Callback triggered once on first render. |
onRender | function | Callback triggered every time the keyboard renders. |
maxLength | number | object | Restrains input length. Can be a number or an object mapping input names to lengths. |
inputPattern | RegExp | object | Restrains input to a specific regular expression. |
syncInstanceInputs | boolean | If true, synchronizes the internal input of all SimpleKeyboard instances. |
enableLayoutCandidates | boolean | Enables support for an input method editor candidate list. |
debug | boolean | Logs key presses and input changes to the console. |
Simple-keyboard supports Input Method Editor (IME) candidate lists via the following options:
enableLayoutCandidates: Enables candidate list support.layoutCandidates: An object { [key: string]: string } defining character suggestions for specific key presses.layoutCandidatesPageSize: Determines the size of the candidate list.layoutCandidatesCaseSensitiveMatch: Determines if matches are case-sensitive.disableCandidateNormalization: If true, disables automatic normalization for selected candidates.enableLayoutCandidatesKeyPress: Enables onKeyPress triggering for candidate items.SimpleKeyboard instances and have enabled syncInstanceInputs, you can use dispatch(callback: (instance: SimpleKeyboard, key?: string) => void) to execute a command on every active instance simultaneously.setOptions(options: Partial<KeyboardOptions>). This method detects which options have changed and performs necessary side effects, such as re-rendering the keyboard or resetting the candidate box.