Vuer

KeyboardMonitor

The KeyboardMonitor component captures keyboard events from the browser and sends them to your Python backend through WebSocket. This invisible component enables keyboard-based interactions in your Vuer applications.

This is ideal for:

  • Building keyboard-controlled interfaces
  • Implementing keyboard shortcuts
  • Creating interactive applications with key bindings
  • Capturing user input for text-based interactions
  • Game controls and navigation

Basic Usage

A minimal example that monitors keyboard events:

from vuer import Vuer, VuerSession
from vuer.schemas import Scene, KeyboardMonitor, DefaultScene

app = Vuer()

@app.add_handler("KeyDown")
async def on_key_down(event, session: VuerSession):
    key_data = event.value
    print(f"Key pressed: {key_data['key']}")
    print(f"Key code: {key_data['code']}")
    if key_data['ctrlKey']:
        print("Ctrl modifier active")

@app.spawn(start=True)
async def main(session: VuerSession):
    session.set @ DefaultScene(
        KeyboardMonitor(
            enableKeyDown=True,
            enableKeyUp=True,
            key="keyboard-monitor",
        ),
    )

    await session.forever()

Key Parameters

Parameter Type Default Description
key str - Unique identifier for the component
enableKeyDown bool False Enable monitoring of keydown events
enableKeyUp bool False Enable monitoring of keyup events
enableKeyPress bool False Enable monitoring of keypress events

Note: At least one event type must be enabled for the component to be useful.

Event Types

The component sends three types of events to Python handlers:

KeyDown

Triggered when a key is pressed down. Repeats if the key is held.

@app.add_handler("KeyDown")
async def on_key_down(event, session):
    print(f"Key down: {event.value['key']}")

KeyUp

Triggered when a key is released.

@app.add_handler("KeyUp")
async def on_key_up(event, session):
    print(f"Key up: {event.value['key']}")

KeyPress

Triggered when a key that produces a character value is pressed.

@app.add_handler("KeyPress")
async def on_key_press(event, session):
    print(f"Key press: {event.value['key']}")

Event Data Format

All keyboard events contain the following data in event.value:

{
    'key': str,           # Character value (e.g., 'a', 'Enter', 'ArrowUp')
    'code': str,          # Physical key code (e.g., 'KeyA', 'Space', 'ArrowUp')
    'shiftKey': bool,     # True if Shift key is pressed
    'ctrlKey': bool,      # True if Ctrl key is pressed
    'altKey': bool,       # True if Alt key is pressed
    'metaKey': bool,      # True if Meta/Command key is pressed
    'repeat': bool,       # True if key is being held down
    'isComposing': bool,  # True if part of an IME composition
}

Key vs Code

  • key: The character or action represented (e.g., 'a', 'A', 'Enter', 'ArrowUp')
  • code: The physical key location (e.g., 'KeyA', 'Space', 'ArrowUp')

For most use cases, use key for character input and code for keyboard layout-independent bindings.

Notes

  • The component is invisible and does not render any visual elements
  • Keyboard events are only captured when the browser window has focus
  • Some browser shortcuts (like Ctrl+T, Ctrl+W) cannot be prevented
  • For text input, consider using HTML input elements instead
  • The component automatically handles keyboard focus management