WinUI TextBox Input Techniques

TextBox handles single-line and multiline text input with built-in spell checking, undo support, and customizable keyboards. Use the patterns below to embed inputs inside flyouts, capture special keys, and keep validation responsive.

Overview

• Supports AcceptsReturn and TextWrapping for multiline content, automatically handling scrollbars as needed.
• Offers built-in placeholder text (PlaceholderText) and header support for accessible labeling.
• Provides InputScope hints so touch keyboards surface context-aware key layouts (email, number, search, etc.).

Prerequisites

• WinUI 3 project with Microsoft.UI.Xaml.Controls.TextBox
• Awareness of your validation and trimming requirements
• Optional: custom IValueConverter when binding to non-string types

Use TextBox inside flyouts

When hosting a TextBox inside an AppBarButton flyout, enable focus handoff so users can interact without dismissing the popup.

<AppBarButton AllowFocusOnInteraction="True">
    <AppBarButton.Flyout>
        <Flyout>
            <StackPanel Width="320">
                <TextBox PlaceholderText="Add a comment"
                         AcceptsReturn="True"
                         TextWrapping="Wrap" />
            </StackPanel>
        </Flyout>
    </AppBarButton.Flyout>
</AppBarButton>

AllowFocusOnInteraction="True" temporarily shifts focus into the flyout. Provide a clear dismissal affordance (for example an OK button) so users can commit the text before the flyout closes.

Handle Tab key input

Tabs are not inserted by default in multiline boxes because they typically move focus. Capture the key and inject the tab character manually.

<TextBox Text="{x:Bind Text, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}"
         TextWrapping="Wrap"
         AcceptsReturn="True"
         KeyDown="TextBox_KeyDownTabHandler"/>

using Microsoft.UI.Xaml.Input;

private void TextBox_KeyDownTabHandler(object sender, KeyRoutedEventArgs e)
{
    if (e.Key != VirtualKey.Tab)
    {
        return;
    }

    if (sender is TextBox textBox)
    {
        var caretPosition = textBox.SelectionStart;
        textBox.Text = textBox.Text.Insert(caretPosition, "\t");
        textBox.SelectionStart = caretPosition + 1;
    }

    e.Handled = true;
}

Validation and best practices

• Trimming: Set TextTrimming or use TextChanging to enforce maximum lengths before the value is committed.
• Undo support: Leave IsUndoEnabled="True" so users can revert unintended edits; disable only for sensitive fields.
• Assistive tech: Provide AutomationProperties.Name or use the Header property for context. For password-like fields, switch to PasswordBox to prevent screen readers from echoing characters.
• Spell checking: Enable IsSpellCheckEnabled="True" for notes or comments and disable it for structured content like IDs or codes.