Keyboard

An on-screen virtual keyboard component designed for touch interfaces and accessibility, with configurable layouts and physical keyboard synchronization.

Import#

import { KeyboardProvider, useKeyboard } from "asheeui";

Usage#

KeyboardProvider is a global feature provider. Wrap your application root once, placed strictly below <AsheeUIProvider>. The provider automatically renders the keyboard at the bottom of the screen when needed.

Then enable the virtual keyboard on any Input component by setting enableVirtualKeyboard={true} (it's true by default).

import {
  AsheeUIProvider,
  KeyboardProvider,
  Input,
} from "asheeui";

function App() {
  return (
    <AsheeUIProvider>
      {/* Feature providers MUST be placed below AsheeUIProvider */}
      <KeyboardProvider size="md">
        <div>
          <Input name="username" placeholder="Enter username" enableVirtualKeyboard />
          <Input name="password" placeholder="Enter password" enableVirtualKeyboard />
        </div>
      </KeyboardProvider>
    </AsheeUIProvider>
  );
}

Examples#

Size variants#

Multiple input fields#

Disable virtual keyboard on specific inputs#

Custom layouts#

Custom display labels#

Styling keyboard keys#

Manual control with useKeyboard#

KeyboardProvider Props#

* Falls back through Global Configuration if not set. See below.

useKeyboard API#

KeyboardOpenOptions#

Portal Behavior#

The OnScreenKeyboard is rendered in a Floating UI portal by default. This means the keyboard is attached to document.body rather than staying in the component's DOM hierarchy.

Why use a portal?#

• Escapes CSS containment: The keyboard appears at the bottom of the screen even when the input is inside containers with overflow: hidden or contain: layout
• Avoids stacking context issues: The keyboard maintains proper z-index regardless of parent stacking contexts
• Works with any parent: The keyboard functions correctly regardless of where the input is placed in the component tree
• Prevents clipping: The keyboard is never clipped by parent containers

When to disable the portal#

You may want to disable the portal (by setting portal={false}) when:

• You need the keyboard to stay within a specific container for testing purposes
• You are rendering inside a shadow DOM or iframe where document.body is not appropriate
• You have specific layout requirements that depend on the keyboard remaining in the DOM hierarchy

Global Configuration#

Keyboard reads defaults from four places, in this order of precedence:

1. Instance prop: set directly on <KeyboardProvider />
2. Component config: components.keyboard in your ashee.config
3. Theme default: defaultVariant / defaultColor / defaultRadius in your ashee.config
4. Built-in fallback: component's internal default values

Component config#

// ashee.config.ts
import type { ExternalConfig } from "asheeui";

export const config: ExternalConfig = {
  components: {
    keyboard: {
      defaultLayout: "default",
      size: "md",
      autoShiftBack: true,
      variant: "solid",
      color: "primary",
      radius: "md",
      portal: true,
      disabled: false,
    },
  },
};

Built-in fallbacks#

{
  defaultLayout: "default",
  size: "md",
  variant: "solid",
  color: "primary",
  radius: "md",
  portal: true,
  disabled: false,
  closeDelay: 500,
  autoShiftBack: true,
}

Input Integration#

The virtual keyboard integrates directly with AsheeUI's Input component. Set enableVirtualKeyboard={true} (default) to enable keyboard support.

Input props for keyboard integration

<Input
  name="username"
  label="Username"
  enableVirtualKeyboard  // default: true
/>

The useKeyboardField hook handles the focus/blur events automatically: no additional wiring needed.

Layouts#

The keyboard comes with four default layouts:

Default Layout#

Shift Layout#

Symbols Layout#

Numeric Layout#

Special Keys#

Accessibility#

• Keyboard has aria-label="Virtual Keyboard" for screen readers
• Supports physical keyboard input with visual key highlighting
• Escape key closes the keyboard
• Focus management with cursor position preservation
• All keys are accessible via keyboard navigation
• Keyboard stays open while interacting with keys
• Clicking outside the input area doesn't immediately close the keyboard (uses close delay)

Notes#

• Provider Required: The KeyboardProvider must wrap your app root (placed below <AsheeUIProvider>) for the keyboard to work.
• Automatic Rendering: The KeyboardProvider automatically renders the keyboard at the bottom of the screen. You don't need to manually add <OnScreenKeyboard /> anywhere.
• Default Layouts: The keyboard comes with default, shift, symbols, and numeric layouts out of the box.
• Custom Layouts: You can provide custom layouts and display labels via the layouts and display props.
• Auto Shift Back: When autoShiftBack is true, the keyboard automatically returns to the default layout after pressing a key in shift mode.
• Close Delay: The closeDelay prop prevents accidental closures when moving focus between inputs.
• Portal: The keyboard is portaled to document.body by default. This can be disabled via the portal prop or component config.
• Per-Instance Overrides: Each keyboard instance can override size, variant, color, radius, and portal settings via KeyboardOpenOptions.
• Physical Keyboard Sync: The virtual keyboard highlights keys when the physical keyboard is used, providing a consistent experience.
• Cursor Management: The keyboard preserves cursor position and handles selections when inserting or deleting characters.