Guidelines and checklist for text input (Windows Store apps)

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Follow these guidelines for adding text input controls to your Windows Store app using C++, C#, or Visual Basic.

Roadmap: How does this topic relate to others? See:

Is this the right control?

Text input controls let users enter and edit a text or numeric value. Consider these questions when deciding whether to use a text input control.

  • Is it practical to enumerate all the valid values efficiently? If so, consider using one of the selection controls instead.
  • Is the valid data completely unconstrained? Or is the valid data constrained only by format (constrained length or character types)? If so, use a text input control.
  • Does the value represent a data type that has a specialized common control? If so, use the appropriate control instead of a text input control.
  • If the data is numeric:
    • Do users perceive the setting as a relative quantity? If so, use a slider.
    • Would the user benefit from instant feedback on the effect of setting changes? If so, use a slider, possibly along with an accompanying control.

There are single-line and multi-line text input controls. The next section describes when to use single-line text input controls, and later sections describe multi-line text input controls.

Choosing the right single-line text input control

For short strings, use a single-line text input control. This table describes when to use the different types of text input controls.

Basic data input

Use single-line text input controls to gather small pieces of text from users.

The following example shows a single-line text box to capture an answer to a security question. The answer is expected to be short, and so a single-line text box is appropriate here. Because the information collected does not match any of the specialized input types that Windows recognizes, the generic TextBox type is appropriate.

Formatted data input

Use a set of short, fixed-sized, TextBox controls to enter data with a specific format.

Assisted data input

Use a single-line, unconstrained TextBox control to enter or edit strings, combined with a command button that helps users select valid values.

Numeric input

Use a TextBox control to enter or edit numbers. Set the InputScope value to InputScopeNameValue.Number.

Telephone number input

Use a TextBox control or a set of short, fixed-sized, TextBox controls for entering telephone numbers. Set the InputScope value to InputScopeNameValue.TelephoneNumber.

Email input

Use a TextBox control to enter an email address. Set the InputScope value to InputScopeNameValue.EmailSmtpAddress.

URL input

Use a TextBox control for entering web addresses. Set the InputScope value to InputScopeNameValue.Url.

Password and PIN input

Use a PasswordBox control to enter passwords and PINs securely.


Do's and dont's for single-line input boxes


Use several single-line text boxes to capture many small pieces of text information. If the text boxes are related in nature, you should group them together.

Provide placeholder text in your single-line text boxes if you believe users need additional instructions for entering a value.

Make the size of your single-line text boxes slightly wider than the longest anticipated input. If doing so makes the control too wide, separate it into two controls; for example, you could split a single address input into "Address line 1" and "Address line 2".

Set a maximum length. If the backing data source doesn't allow a long input string, set the MaxLength property to limit the input and use a validation popup to let users know when they reach the limit.


Don't use a text box as a search box. It's common practice in web pages to use an TextBox element to create a search box. However, you create a much better and more consistent experience when you use the Search charm instead. The Search charm provides a consistent searching experience that your app can plug into. For more info, see Adding search.

Don't put another control right next to a password input box. The PasswordBox has a password reveal button for users to verify the passwords they have typed. Having another control right next to it might make users accidentally reveal their passwords when they try to interact with the other control. To prevent this from happening, put some spacing between the PasswordBox and the other control, or put the other control on the next line.


Choosing the right multi-line text input control

When users need to enter or edit long strings, use a multi-line text control. There are two types of multi-line text input control.

  • If the primary purpose of the multi-line text box is for creating documents (such as blog entries or the contents of an email message), and those documents require rich text, use a RichEditBox control.
  • If you want users to be able to format their text, use a RichEditBox control.
  • When capturing text that will only be consumed, and not redisplayed at a later time to users, use a TextBox control. For example, suppose you have a survey; the user completes the survey and the data is sent to some server, but the user doesn't ever see it again. It is generally unnecessary to allow users to style this text.
  • For all other scenarios, use a TextBox control whenever possible.

Do's and dont's for multi-line text input controls


When you create a rich text box, provide styling buttons and implement their actions. (Windows Store apps using C++, C#, or Visual Basic don't automatically provide these controls for you. )

Use a font that represents the feel of your app.

Make the height of the text control tall enough to accommodate typical entries.

When capturing long spans of text where users are expected to keep their word count or character count below some maximum, use a plain text box and provide a live-running counter to show the user how many characters or words they have left before they reach the limit. You will need to create the counter yourself; place it near the text box and update it dynamically as the user enters each character or word.


Don't let your text input controls grow in height while users type.

Don't use a multi-line text box when users only need a single line.

Don't use a rich text control if plain text is adequate.