User Tools

Site Tools


Text Controls and Elements in XAML

Text boxes:

  • TextBox
  • AutoSuggestBox
  • PasswordBox
  • RichEditBox
  • SearchBox - in Win10 use the AutoSuggestBox control instead of SearchBox

All text box elements support the PlaceholderText property.

Text elements:

  • TextBlock
  • RichTextBlock


AutoSuggestBox works well as a search box. It may also provide suggestions as the user types. To control how items are displayed in the suggestion list, you can use DisplayMemberPath or ItemTemplate.

Example: Use an AutoSuggestBox as a search box:

<AutoSuggestBox PlaceholderText="Enter a name"
                Header="What's your name?"
                IsSuggestionListOpen = "False"
                QuerySubmitted="AutoSuggestBox_QuerySubmitted" /> 
private void AutoSuggestBox_QuerySubmitted(AutoSuggestBox sender, AutoSuggestBoxQuerySubmittedEventArgs args)
    Debug.WriteLine("Search term: " + args.QueryText);

Example: Use an AutoSuggestBox as a suggestion list:

<AutoSuggestBox x:Name="AutoSuggestBox1"
                PlaceholderText="Enter a name"
                QuerySubmitted="AutoSuggestBox_QuerySubmitted" />
using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.Linq;
using Windows.UI.Xaml;
using Windows.UI.Xaml.Controls;
namespace TestApp
    public sealed partial class MainPage : Page
        private List<string> names = new List<string>();
        public MainPage()
            Loaded += MainPage_Loaded;
        private void MainPage_Loaded(object sender, RoutedEventArgs e)
            names = new List<string> { "john", "mike", "chris", "sophia", "jessica" };
            AutoSuggestBox1.ItemsSource = names;
        private void AutoSuggestBox_TextChanged(AutoSuggestBox sender, AutoSuggestBoxTextChangedEventArgs args)
            // CheckCurrent indicates if the value of the AutoSuggestBox has changed since the event was raised.
            // MSDN: Returns true if the text has not changed, false if it has (??? it seems to be opposite).
            if (args.CheckCurrent())
                Debug.WriteLine("TextChanged: " + AutoSuggestBox1.Text);
                var searchTerm = AutoSuggestBox1.Text.ToLower();
                var results = names.Where(n => n.Contains(searchTerm.ToLower())).ToList();
                AutoSuggestBox1.ItemsSource = results;
        private void AutoSuggestBox_SuggestionChosen(AutoSuggestBox sender, 
                                                     AutoSuggestBoxSuggestionChosenEventArgs args)
            var item = args.SelectedItem as string;
            AutoSuggestBox1.Text = item;
            Debug.WriteLine("SuggestionChosen: " + item);
        private void AutoSuggestBox_QuerySubmitted(AutoSuggestBox sender, 
                                                   AutoSuggestBoxQuerySubmittedEventArgs args)
            Debug.WriteLine("QuerySubmitted: " + args.QueryText);
            var searchTerm = args.QueryText.ToLower();
            var results = names.Where(n => n.Contains(searchTerm.ToLower())).ToList();
            AutoSuggestBox1.ItemsSource = results;
            AutoSuggestBox1.IsSuggestionListOpen = true;



PasswordBox-specific properties:

  • PasswordChar property - the masking character (default is the bullet 0x2022 = 8226).
  • Password - the contents of the PasswordBox

Use the PasswordRevealMode to control if the password is obscured. In UWP apps, the PasswordRevealMode property replaces the IsPasswordRevealButtonEnabled property.

<PasswordBox PasswordRevealMode="Visible" />
<PasswordBox PasswordRevealMode="Hidden" />


TextBox-specific properties:

  • PlaceholderText
  • TextWrapping - default: NoWrap
  • AcceptsReturn - set the AcceptsReturn property to true, to enable multi-line input.

You can restrict the number of characters the user can type by setting the MaxLength property. However, MaxLength does not restrict the length of pasted text.

A multi-line TextBox will continue to grow vertically unless it is constrained by its Height or MaxHeight property, or by a parent container. When in multi-line mode, vertical scrollbars are not shown by default. You can show the vertical scrollbars by setting the attached property ScrollViewer.VerticalScrollBarVisibility to Auto.

Example: Set focus on a TextBox programmatically:



The TextBlock element has a content property named Inlines of type InlineCollection. The InlineCollection can contain derivatives of the Inline class:

                InlineUIContainer (works only with RichTextBlock)
                Run (defines Text as its content property)
                Span (defines Inlines property)

The Inline class and its derivatives are located in the Windows.UI.Xaml.Documents namespace.

Properties of the TextBlock:

  • CharacterSpacing - Specified in units of a thousandth of an em.
  • FlowDirection - LeftToRight (the default) or RightToLeft.
  • IsTextSelectionEnabled - False or True
  • LineHeight - The height of each line in the TextBlock, specified in DIPs (device-independent pixels). A value of zero (the default value) indicates that the line height is determined automatically.
  • LineStackingStrategy - Specifies how a line box is determined for each line:
    • MaxHeight (the default value)
    • BlockLineHeight
    • BaselineToBaseline
  • TextTrimming:
    • None (the default value) - text is clipped when it overflows
    • WordEllipsis - an ellipsis is placed in the end
  • TextWrapping - NoWrap (the default) or Wrap

Example: A few examples of the Inline derivatives. Note that the plain text is automatically converted to a Run element:

<TextBlock TextWrapping="Wrap" Foreground="Black" FontSize="25">
    <!-- this text is converted to a Run element automatically -->
    Examples of Inline derivatives:
    <LineBreak />
    <LineBreak />

Example: A TextBlock embedded in a ScrollViewer:

<Grid Background="White">
    <ScrollViewer Foreground="Navy" Padding="10" Width="400" Height="300" 
                  BorderBrush="Black" BorderThickness="1">
        <TextBlock TextWrapping="Wrap">
        <Run FontSize="25">
            Lorem ipsum...
        <!-- LineBreak is not allowed within a Run element -->
        <LineBreak />
        <LineBreak />
        <Run FontSize="25" FontStyle="Italic">
            Inermis docendi...

Example: TextAlignment values: Left, Right, Center, Justify.

<Grid Background="White" Width="300" Height="500">
    <StackPanel Margin="10">
        <TextBlock TextAlignment="Left" TextWrapping="Wrap">
            This text is a very long line of text in a TextBlock element. It is left-aligned.
        <Rectangle Margin="0,5" Height="1" Fill="Black" />
        <TextBlock TextAlignment="Right" TextWrapping="Wrap">
            This text is a very long line of text in a TextBlock element. It is right-aligned.
        <Rectangle Margin="0,5" Height="1" Fill="Black" />
        <TextBlock TextAlignment="Center" TextWrapping="Wrap">
            This text is a very long line of text in a TextBlock element. It is centered.
        <Rectangle Margin="0,5" Height="1" Fill="Black" />
        <TextBlock TextAlignment="Justify" TextWrapping="Wrap">
            This text is a very long line of text in a TextBlock element. It is justified.

Example: The CharacterSpacing property sets the spacing between characters in units of a thousandth of an em (an em is the size of the the element's font).

Default spacing:



<TextBlock TextWrapping="Wrap" Foreground="Black" FontSize="20" CharacterSpacing="50">
    Lorem ipsum...

Example: Left-justify text if it is short and clip it at the left if it is long:

<Grid Background="White" Width="300" Height="100">
        <RowDefinition />
        <RowDefinition />
    <Border HorizontalAlignment="Left" Padding="5"  Margin="5" 
            BorderThickness="1" BorderBrush="Blue" Grid.Row="0">
        <TextBlock Text="This is a short text" 
                   HorizontalAlignment="Right" VerticalAlignment="Top" />
    <Border HorizontalAlignment="Left" Padding="5" Margin="5" 
            BorderThickness="1" BorderBrush="Green" Grid.Row="1">
        <TextBlock Text="Testing a very long text that is clipped" 
                   HorizontalAlignment="Right" VerticalAlignment="Top" />


Set the content of a RichTextBlock using the Paragraph element and Bold, Italic, or Underline tags. You can also embed any element that derives from the UIElement class by using the InlineUIContainer element.

If text does not fit in the available area of a RichTextBlock control, you can continue remaining text in a sequence of RichTextBlockOverflow controls.

Example: Wrap a RichTextBlock element into a ScrollViewer and include an InlineUIContainer to display an image inline:

<Grid Background="White" Width="400" Height="400">
        <RichTextBlock TextWrapping="Wrap">
            <Paragraph FontSize="20">
                Lorem ipsum dolor...
            <Paragraph FontSize="20" FontStyle="Italic">
                    <Image Source="Assets/test.jpg" Stretch="None" />
                    Nec altera utamur facilisi ex...

Example: Flow text into subsequent RichTextBlockOverflow elements:

<Grid Background="White">
        <ColumnDefinition />
        <ColumnDefinition />
        <ColumnDefinition />
    <!-- column 1 -->
    <RichTextBlock Grid.Column="0" Margin="10" 
                   FontSize="20" Foreground="Navy" TextAlignment="Justify"
                   OverflowContentTarget="{Binding ElementName=OverflowContainer1}">
            Lorem ipsum dolor sit amet...
    <!-- column 2 -->
    <RichTextBlockOverflow x:Name="OverflowContainer1" 
                           Grid.Column="1" Margin="10" 
                           OverflowContentTarget="{Binding ElementName=OverflowContainer2}" />
    <!-- column 3 -->
    <RichTextBlockOverflow x:Name="OverflowContainer2" 
                           Grid.Column="2" Margin="10" />
notes/uwp/textboxes.txt · Last modified: 2020/08/26 (external edit)