API Reference

Complete documentation of all components, props, hooks, and utilities

VirtualKeyboard

The main keyboard component with extensive customization options.

Required Props

Prop	Type	Description
`focusedInputRef`	`RefObject<HTMLInputElement \| HTMLTextAreaElement>`	Ref to the currently focused input element
`isInputFocused`	`boolean`	Whether an input is currently focused

Layout & Type Props

Prop	Type	Default	Description
`inputType`	`HTMLInputTypeAttribute`	`'text'`	HTML input type (affects layout and validation)
`defaultLayout`	`'letters' \| 'symbols' \| 'numbers'`	`'letters'`	Initial keyboard layout to display
`customLayouts`	`{ letters?: string[][], symbols?: string[][], numbers?: string[][] }`	`undefined`	Override default keyboard layouts

Callback Props

Prop	Type	Description
`onChange`	`(value: string) => void`	Called when input value changes
`onEnterClick`	`() => void`	Called when Enter key is pressed
`validate`	`(value: string) => boolean`	Custom validation function

Customization Props

Prop	Type	Default	Description
`keyLabels`	`Record<string, string>`	`{}`	Custom labels for keys (e.g., { 'enter': 'Submit' })
`hiddenKeys`	`string[]`	`[]`	Array of keys to hide from keyboard
`disabledKeys`	`string[]`	`[]`	Array of keys to disable (grayed out)
`renderKey`	`(key: string, defaultRender: ReactNode) => ReactNode`	`undefined`	Custom render function for individual keys
`renderSpecialKey`	`(type: string, defaultRender: ReactNode) => ReactNode`	`undefined`	Custom render function for special keys

Behavior Props

Prop	Type	Default	Description
`syncWithHardwareKeyboard`	`boolean`	`true`	Enable/disable hardware keyboard synchronization
`continuousPressConfig`	`{ initialDelay?: number, interval?: number }`	`{ initialDelay: 500, interval: 50 }`	Configuration for hold-to-repeat behavior
`scrollConfig`	`{ enabled?: boolean, offset?: number }`	`{ enabled: true }`	Auto-scroll configuration when keyboard appears

Theming Props

Prop	Type	Description
`className`	`string`	Additional CSS class name
`theme`	`VirtualKeyboardTheme`	Theme configuration object (see Theme Type below)

GlobalVirtualKeyboard

Automatically shows keyboard when any input is focused.

Prop	Type	Default	Description
`enabled`	`boolean`	`true`	Enable/disable the global keyboard
`className`	`string`	`undefined`	Custom CSS class name
`onVisibilityChange`	`(visible: boolean) => void`	`undefined`	Called when keyboard visibility changes
`onEnterClick`	`() => void`	`undefined`	Called when Enter key is pressed
`onChange`	`(value: string) => void`	`undefined`	Called when input value changes

VirtualKeyboardTheme

Theme configuration object for customizing keyboard appearance.

Property	Type	Description
`backgroundColor`	`string`	Background color of keyboard container
`keyColor`	`string`	Default key background color
`keyTextColor`	`string`	Text color on keys
`keyActiveColor`	`string`	Key color when pressed
`keyHoverColor`	`string`	Key color on hover
`activeStateColor`	`string`	Color for active states (e.g., Caps Lock on)
`keyBorderRadius`	`string`	Border radius for keys
`keyFontSize`	`string`	Font size for key labels
`keyHeight`	`string`	Height of keys

Utility Functions

Pure functions exported for advanced usage.

createCaretManager

function createCaretManager(
  getInputRef: () => HTMLInputElement | HTMLTextAreaElement | null
): {
  insertText: (text: string) => void;
  backspace: () => void;
}

Creates a caret manager for manipulating text in input elements.

setupHardwareKeyboard

function setupHardwareKeyboard(handlers: {
  onBackspace: () => void;
  onEnter: () => void;
  onSpace: () => void;
  onCapsToggle: () => void;
  onKeyClick: (key: string) => void;
}): () => void // Returns cleanup function

Sets up hardware keyboard event listeners. Returns cleanup function.

Hooks

React hooks for state management and effects.

useContinuousPress

function useContinuousPress(
  callback: () => void,
  options?: {
    enableContinuousPress?: boolean;
    delay?: number;
    interval?: number;
  }
): {
  handleMouseDown: () => void;
  handleMouseUp: () => void;
  handleMouseLeave: () => void;
}

Implements hold-to-repeat functionality (e.g., for backspace key).

useKeyboardScroll

function useKeyboardScroll(
  keyboardRef: RefObject<HTMLElement>
): {
  scrollInput: (input: HTMLElement) => void;
  resetScroll: () => void;
}

Manages scrolling input elements into view when keyboard appears.