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