mt-react-keyboard

Customizable virtual on-screen keyboard component for React (TypeScript). Supports a standard QWERTY layout with optional key scrambling and full-screen mode.

Features

• Standard QWERTY layout with optional key scrambling
• Full-screen or inline display modes
• Customizable key colors, hover effects, and text styles
• Integration with input or textarea elements
• Supports action keys: shift, caps lock, backspace, tab, enter, space
• Responsive design for mobile and desktop
• Portal rendering for full-screen mode

Installation

npm install mt-react-keyboard
# or
yarn add mt-react-keyboard
# or
pnpm add mt-react-keyboard

Peer dependencies (ensure these exist in your app):

npm install react react-dom

Usage

Here’s an example of how to use the MTKeyboard component:

import React, { useRef } from "react";
import MTKeyboard from "./MTKeyboard";

const App = () => {
  const inputRef = useRef<HTMLInputElement>(null);

  return (
    <div>
      <input ref={inputRef} type="text" placeholder="Type here" />
      <MTKeyboard
        targetRef={inputRef}
        scramble={true}
        fullScreen={true}
        isVisible={true}
        onClose={() => console.log("Keyboard closed")}
        keysBgColor="#ffffff"
        hoverBgColor="#e0e0e0"
        actionsBgColor="#d3d3d3"
        keysMainTextColor="#000000"
        keysVariantTextColor="#666666"
      />
    </div>
  );
};

export default App;

Props

The MTKeyboard component accepts the following props:

| Prop | Type | Default | Description | |-----------------------|-----------------------------------------|---------------|-----------------------------------------------------------------------------| | scramble | boolean | false | Randomizes the position of printable keys if true. | | fullScreen | boolean | false | Renders the keyboard as a full-screen overlay if true. | | isVisible | boolean | true | Toggles the visibility of the keyboard. | | targetRef | React.RefObject<HTMLInputElement \| HTMLTextAreaElement \| null> | undefined | Ref to the target input or textarea element. If not provided, uses the active element. | | onClose | () => void | undefined | Callback function to handle closing the keyboard (used in full-screen mode). | | keysBgColor | CSSProperties["color"] | #ffffff | Background color for regular keys. | | hoverBgColor | CSSProperties["color"] | #e0e0e0 | Background color for keys on hover. | | actionsBgColor | CSSProperties["color"] | #e0e0e0 | Background color for action keys (e.g., shift, caps). | | keysMainTextColor | CSSProperties["color"] | #010101 | Text color for main key labels. | | keysVariantTextColor| CSSProperties["color"] | inherit | Text color for variant labels (e.g., shift key symbols). |

Key Features Explained

• Scramble Mode: When scramble is true, printable keys are randomized, while action keys (e.g., shift, enter) remain in place.
• Full-Screen Mode: When fullScreen is true, the keyboard is rendered at the bottom of the screen using a portal, with a close button.
• Shift and Caps Lock: Shift toggles temporarily, while caps lock persists for letters only. Both display their respective states visually.
• Responsive Design: Keys adjust their font size and padding based on the window width (smaller for mobile devices).
• Input Handling: The keyboard inserts text at the cursor position and supports text selection for backspace and other operations.

Styling

The keyboard uses CSS grid for layout, with row-specific grid templates to match a standard QWERTY keyboard. You can customize the appearance using the provided color props. For example:

<MTKeyboard
  keysBgColor="#f0f0f0"
  hoverBgColor="#cccccc"
  actionsBgColor="#aaaaaa"
  keysMainTextColor="#333333"
  keysVariantTextColor="#666666"
/>

Notes

• The keyboard prevents default mouse down behavior to maintain focus on the target input.
• In full-screen mode, the keyboard uses createPortal to render directly in the document.body.
• The component assumes a QWERTY layout.
• The keyboard supports left-to-right (ltr) direction to ensure consistent rendering.

License

MIT © Kiaksar. See LICENSE. Installation: npm install mt-react-captcha