WinUI Keyboard Accelerator Patterns

Keyboard accelerators let users trigger common actions without leaving the keyboard. They improve efficiency for power users and provide alternate access paths for assistive technologies.

Overview

• Accelerators can be attached to any focusable control through the KeyboardAccelerators collection.
• When multiple handlers match, precedence is UIElement → App → CoreWindow, so scope them carefully.
• Use ScopeOwner to limit accelerators to a specific section (for example, a dialog) without affecting the rest of the window.

Prerequisites

• WinUI 3 project targeting Windows 10 version 1809 or later
• Reference to Microsoft.UI.Xaml.Input.KeyboardAccelerator
• Clear command naming conventions to avoid collisions with system shortcuts

Register scoped accelerators

The example below assigns Ctrl+F to a search box while allowing the accelerator to bubble to the page when focus is elsewhere.

<Page
    x:Class="KeyboardAcceleratorExample.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:KeyboardAcceleratorExample">

    <Grid>
        <StackPanel>
            <TextBox x:Name="SearchBox"
                     PlaceholderText="Search"
                     Width="320" />

            <Button Content="Search" Click="OnSearch" Width="120" />
        </StackPanel>

        <Page.KeyboardAccelerators>
            <KeyboardAccelerator Key="F" Modifiers="Control" Invoked="OnSearchAccelerator"/>
        </Page.KeyboardAccelerators>
    </Grid>
</Page>

public sealed partial class MainPage : Page
{
    public MainPage()
    {
        InitializeComponent();
    }

    private void OnSearchAccelerator(KeyboardAccelerator sender, KeyboardAcceleratorInvokedEventArgs args)
    {
        if (FocusManager.TryFocusAsync(SearchBox, FocusState.Programmatic).Status == AsyncStatus.Completed)
        {
            args.Handled = true;
        }
    }

    private void OnSearch(object sender, RoutedEventArgs e)
    {
        // Execute search command
    }
}

Use KeyboardAcceleratorPlacementMode to control whether tooltips expose the shortcut automatically. This helps discoverability without building custom tooltip strings.

Best practices

• Avoid conflicts: Reserve common shortcuts (Ctrl+C, Ctrl+V, Ctrl+S) for their standard meanings unless your experience is very specialized.
• Accessibility: Document shortcuts in your help content and ensure alternate mouse/touch paths exist for every action.
• Security: Avoid binding accelerators to operations that mutate sensitive data without confirmation to prevent accidental triggers.
• Testing: Verify accelerators under high contrast mode and with screen readers; make sure focus moves to relevant UI before executing commands.