Skip to main content
The keyboard input system in Avalonia provides comprehensive support for handling keyboard events, key codes, and keyboard modifiers across different platforms and keyboard layouts.

​
KeyEventArgs

Provides information specific to a keyboard event.

​
Properties

​
Key
Key
The virtual key for the associated event. A given physical key can result in different virtual keys depending on the current keyboard layout. This is the key that is generally referred to when creating keyboard shortcuts.Use this property for letter-related shortcuts only. For example, when pressing the key at the Z position:
  • Returns Key.Z for English (QWERTY) layout
  • Returns Key.W for French (AZERTY) layout
  • Returns Key.Y for German (QWERTZ) layout
Avoid using this for shortcuts related to punctuation keys, as they differ wildly depending on keyboard layouts.
​
KeyModifiers
KeyModifiers
The key modifiers (Ctrl, Shift, Alt, Meta) that were active when the event was fired.
​
PhysicalKey
PhysicalKey
The physical key for the associated event. This value is independent of the current keyboard layout and usually corresponds to the key printed on a standard US English QWERTY keyboard.Use this property if you need to refer to a key given its position on the keyboard. A common usage is moving the player with WASD-like keys in games.
​
KeySymbol
string?
The unicode symbol of the key, or null if none is applicable. For example, when pressing the key at the Z position:
  • Returns "z" for English (QWERTY) layout
  • Returns "w" for French (AZERTY) layout
  • Returns "y" for German (QWERTZ) layout
  • Returns "я" for Russian (JCUKEN) layout
​
KeyDeviceType
KeyDeviceType
Type of the device that fired the event.

​
Key Enumeration

Defines the keys available on a keyboard. The enumeration includes:

​
Standard Keys

  • Navigation: Left, Right, Up, Down, Home, End, PageUp, PageDown
  • Editing: Back, Delete, Insert, Enter, Return, Tab, Escape, Space
  • Function Keys: F1 through F24
  • Modifier Keys: LeftShift, RightShift, LeftCtrl, RightCtrl, LeftAlt, RightAlt

​
Number and Letter Keys

  • Numbers: D0 through D9 (main keyboard)
  • Letters: A through Z
  • Numpad: NumPad0 through NumPad9, Multiply, Add, Subtract, Divide, Decimal

​
Special Keys

  • System: LWin, RWin, Apps, Sleep
  • Media: MediaPlayPause, MediaStop, MediaNextTrack, MediaPreviousTrack, VolumeUp, VolumeDown, VolumeMute
  • Browser: BrowserBack, BrowserForward, BrowserRefresh, BrowserStop, BrowserSearch

​
Platform-Specific Keys

  • macOS: FnLeftArrow, FnRightArrow, FnUpArrow, FnDownArrow
  • Remote Control: MediaRed, MediaGreen, MediaYellow, MediaBlue, MediaMenu, etc.

​
Usage Examples

​
Handling Keyboard Events

public class MyControl : Control
{
    protected override void OnKeyDown(KeyEventArgs e)
    {
        // Check for Ctrl+S shortcut using virtual key
        if (e.Key == Key.S && e.KeyModifiers.HasFlag(KeyModifiers.Control))
        {
            SaveDocument();
            e.Handled = true;
        }
        
        base.OnKeyDown(e);
    }
}

​
Using Physical Keys for Game Input

protected override void OnKeyDown(KeyEventArgs e)
{
    // Use PhysicalKey for position-based controls
    // This ensures WASD works regardless of keyboard layout
    switch (e.PhysicalKey)
    {
        case PhysicalKey.W:
            MoveForward();
            break;
        case PhysicalKey.A:
            MoveLeft();
            break;
        case PhysicalKey.S:
            MoveBackward();
            break;
        case PhysicalKey.D:
            MoveRight();
            break;
    }
}

​
Handling Text Input with KeySymbol

protected override void OnKeyDown(KeyEventArgs e)
{
    // Use KeySymbol to get the actual character
    if (e.KeySymbol != null)
    {
        ProcessTextInput(e.KeySymbol);
    }
}

​
Creating Key Gestures

<Window xmlns="https://github.com/avaloniaui">
    <Window.KeyBindings>
        <KeyBinding Gesture="Ctrl+N" Command="{Binding NewCommand}" />
        <KeyBinding Gesture="Ctrl+O" Command="{Binding OpenCommand}" />
        <KeyBinding Gesture="Ctrl+S" Command="{Binding SaveCommand}" />
        <KeyBinding Gesture="F5" Command="{Binding RefreshCommand}" />
    </Window.KeyBindings>
</Window>

​
KeyModifiers Enumeration

Defines keyboard modifier keys:
  • None - No modifiers
  • Alt - Alt key
  • Control - Control key (Cmd on macOS)
  • Shift - Shift key
  • Meta - Windows/Command key
// Check for multiple modifiers
if (e.KeyModifiers.HasFlag(KeyModifiers.Control | KeyModifiers.Shift))
{
    // Handle Ctrl+Shift+Key combination
}

​
Best Practices

  1. For Keyboard Shortcuts: Use the Key property for letter-based shortcuts
  2. For Position-Based Input: Use PhysicalKey for game controls and position-dependent functionality
  3. For Text Processing: Use KeySymbol to get the actual character being typed
  4. Avoid Punctuation in Shortcuts: Punctuation keys vary significantly across keyboard layouts
  5. Mark Events as Handled: Set e.Handled = true to prevent event bubbling when you’ve processed the event

Build docs developers (and LLMs) love

Get started for freeTalk to us