Password​Box Password​Box Password​Box Class

Definition

Represents a control for entering passwords.

public : sealed class PasswordBox : Control, IPasswordBox, IPasswordBox2, IPasswordBox3public sealed class PasswordBox : Control, IPasswordBox, IPasswordBox2, IPasswordBox3Public NotInheritable Class PasswordBox Inherits Control Implements IPasswordBox, IPasswordBox2, IPasswordBox3
<PasswordBox .../>
Inheritance
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Inherited Members

Inherited properties

Inherited events

Inherited methods

Examples

This example shows a PasswordBox control that demonstrates the Password property and the PasswordChanged event. When the user enters text into this PasswordBox, it's checked to see if it's the literal value, "Password". If it is, a message is displayed to the user.

<PasswordBox x:Name="passwordBox" Width="200" MaxLength="16"
             PasswordChanged="passwordBox_PasswordChanged"/>

<TextBlock x:Name="statusText" Margin="10" HorizontalAlignment="Center"/>

private void passwordBox_PasswordChanged(object sender, RoutedEventArgs e)
{
    if (passwordBox.Password == "Password")
    {
        statusText.Text = "'Password' is not allowed as a password.";
    }
    else
    {
        statusText.Text = string.Empty;
    }
}

Private Sub passwordBox_PasswordChanged(sender As Object, e As RoutedEventArgs)
    If passwordBox.Password = "Password" Then
        statusText.Text = "'Password' is not allowed as a password."
    Else
        statusText.Text = String.Empty
    End If
End Sub

Remarks

PasswordBox lets a user enter a masked password.

Password box control

The user can enter a single line of non-wrapping text in a PasswordBox control. The text is not displayed while it is entered; only password characters that mask the text are displayed. You can specify this password character by setting the PasswordChar property.

Use the Password property to get or set the content of the PasswordBox. Handle the PasswordChanged event to get the Password value while the user enters it.

For more info, see PasswordBox control guide.

Password reveal mode

The PasswordRevealMode property lets you customize the password viewing experience. By default, the PasswordBox has a built-in button that the user can press to display the password text. When the user releases it, the password is automatically hidden again.

Windows 10, version 1607, introduces a new keyboard shortcut for accessibility. When the focus is in the PasswordBox and the password reveal button is visible, the user can press and hold Alt+F8 to reveal their password. When they let go of either key press, the password is hidden again.

A password box with the password shown.

You can hide the password reveal button, or provide a custom UI to let the user reveal the password. For more info and examples, see PasswordRevealMode and PasswordBox control guide.

Note

Use the PasswordRevealMode property instead of the IsPasswordRevealButtonEnabled property. IsPasswordRevealButtonEnabled is deprecated in Windows 10 and any value is ignored.

Control style and template

You can modify the default Style and ControlTemplate to give the control a unique appearance. For information about modifying a control's style and template, see Styling controls. The default style, template, and resources that define the look of the control are included in the generic.xaml file. For design purposes, generic.xaml is available in the (Program Files)\Windows Kits\10\DesignTime\CommonConfiguration\Neutral\UAP&lt;SDK version>\Generic folder from a Windows Software Development Kit (SDK) installation. Styles and resources from different versions of the SDK might have different values.

Starting in Windows 10, version 1607 (Windows Software Development Kit (SDK) version 10.0.14393.0), generic.xaml includes resources that you can use to modify the colors of a control in different visual states without modifying the control template. In apps that target this software development kit (SDK) or later, modifying these resources is preferred to setting properties such as Background and Foreground. For more info, see the Light-weight styling section of the Styling controls article.

This table shows the resources used by the PasswordBox control. Resources that start with "TextControl" are shared by TextBox, PasswordBox, RichEditBox, and AutoSuggestBox.

Resource keyDescription
TextControlForegroundText color at rest and not focused
TextControlForegroundPointerOverText color on hover
TextControlForegroundFocusedText color when focused
TextControlForegroundDisabledText color when disabled
TextControlBackgroundBackground color at rest and not focused
TextControlBackgroundPointerOverBackground color on hover
TextControlBackgroundFocusedBackground color when focused
TextControlBackgroundDisabledBackground color when disabled
TextControlBorderBrushBorder color at rest and not focused
TextControlBorderBrushPointerOverBorder color on hover
TextControlBorderBrushFocusedBorder color when focused
TextControlBorderBrushDisabledBorder color when disabled
TextControlPlaceholderForegroundPlaceholder text color at rest and not focused
TextControlPlaceholderForegroundPointerOverPlaceholder text color on hover
TextControlPlaceholderForegroundFocusedPlaceholder text color when focused
TextControlPlaceholderForegroundDisabledPlaceholder text color when disabled
TextControlHeaderForegroundHeader text color
TextControlHeaderForegroundDisabledHeader text color when disabled
TextControlSelectionHighlightColorHighlight color of selected text
TextControlButtonBackgroundBackground color of reveal button at rest
TextControlButtonBackgroundPointerOverBackground color of reveal button on hover
TextControlButtonBackgroundPressedBackground color of reveal button when pressed
TextControlButtonBorderBrushBorder color of reveal button at rest
TextControlButtonBorderBrushPointerOverBorder color of reveal button on hover
TextControlButtonBorderBrushPressedBorder color of reveal button when pressed
TextControlButtonForegroundForeground color of reveal button at rest
TextControlButtonForegroundPointerOverForeground color of reveal button on hover
TextControlButtonForegroundPressedForeground color of reveal button when pressed

Notes for previous versions

Windows 8.x Use the IsPasswordRevealButtonEnabled property to specify whether the user can see the password, or see only the masking characters.

In Windows, the user reveals the password by pressing and holding a button in the text entry box. The password is automatically hidden when the user stops pressing the button.

In Windows Phone, the user reveals the password by checking a checkbox, so the password can stay shown while the user in entering it. (For more info on implementing this behavior in Universal Windows Platform (UWP) apps, see PasswordRevealMode.)

Constructors

PasswordBox() PasswordBox() PasswordBox()

Initializes a new instance of the PasswordBox class

public : PasswordBox()public PasswordBox()Public Sub New()
Attributes

Properties

Header Header Header

Gets or sets the content for the control's header.

public : PlatForm::Object Header { get; set; }public object Header { get; set; }Public ReadWrite Property Header As object
<PasswordBox Header="headerString"/>

Value
PlatForm::Object object object

The content of the control's header. The default is null.

Attributes

Remarks

You can set a data template for the Header value by using the HeaderTemplate property.

See Also

HeaderProperty HeaderProperty HeaderProperty

Identifies the Header dependency property.

public : static DependencyProperty HeaderProperty { get; }public static DependencyProperty HeaderProperty { get; }Public Static ReadOnly Property HeaderProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the Header dependency property.

Attributes

HeaderTemplate HeaderTemplate HeaderTemplate

Gets or sets the DataTemplate used to display the content of the control's header.

public : DataTemplate HeaderTemplate { get; set; }public DataTemplate HeaderTemplate { get; set; }Public ReadWrite Property HeaderTemplate As DataTemplate
<PasswordBox>
  <PasswordBox.HeaderTemplate>
    singleDataTemplate
  </PasswordBox.HeaderTemplate>
</PasswordBox>
Value
DataTemplate DataTemplate DataTemplate

The template that specifies the visualization of the header object. The default is null.

Attributes
See Also

HeaderTemplateProperty HeaderTemplateProperty HeaderTemplateProperty

Identifies the HeaderTemplate dependency property.

public : static DependencyProperty HeaderTemplateProperty { get; }public static DependencyProperty HeaderTemplateProperty { get; }Public Static ReadOnly Property HeaderTemplateProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the HeaderTemplate dependency property.

Attributes

InputScope InputScope InputScope

Gets or sets the context for input used by this PasswordBox.

public : InputScope InputScope { get; set; }public InputScope InputScope { get; set; }Public ReadWrite Property InputScope As InputScope
<PasswordBox>
  <PasswordBox.InputScope>
    <InputScope>
      <InputScope.Names>
        <InputScopeName NameValue="inputScopeName"/>
      </InputScope.Names>
    </InputScope>
  </PasswordBox.InputScope>
</PasswordBox>
Value
InputScope InputScope InputScope

The input scope, which provides a hint at the type of text input expected by the control. The default is null.

Attributes

Examples

Here's how to set the InputScope in XAML and in code.

<PasswordBox x:Name="pinBox" Header="Enter PIN">
    <PasswordBox.InputScope>
        <InputScope>
            <InputScope.Names>
                <InputScopeName NameValue="NumericPin"/>
            </InputScope.Names>
        </InputScope>
    </PasswordBox.InputScope>
</PasswordBox>
PasswordBox passwordBox = new PasswordBox();
passwordBox.Header = "Enter password";

InputScope scope = new InputScope();
InputScopeName scopeName = new InputScopeName();
scopeName.NameValue = InputScopeNameValue.Password;
scope.Names.Add(scopeName);
passwordBox.InputScope = scope;

Remarks

The InputScope property on PasswordBox supports only the Password and NumericPin values. Any other value is ignored.

The input scope provides a hint at the type of text input expected by the control. Various elements of the system can respond to the hint provided by the input scope and provide a specialized UI for the input type. For example, the soft keyboard might show a number pad for text input when the control has its InputScope set to NumericPin.

The input scope does not perform any validation, and does not prevent the user from providing any input through a hardware keyboard or other input device.

InputScopeProperty InputScopeProperty InputScopeProperty

Identifies the InputScope dependency property.

public : static DependencyProperty InputScopeProperty { get; }public static DependencyProperty InputScopeProperty { get; }Public Static ReadOnly Property InputScopeProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the InputScope dependency property.

Attributes
See Also

IsPasswordRevealButtonEnabled IsPasswordRevealButtonEnabled IsPasswordRevealButtonEnabled

Gets or sets a value that specifies whether the visual UI of the PasswordBox includes a button element that toggles showing or hiding the typed characters. In Windows 10 and later, use PasswordRevealMode instead.

public : PlatForm::Boolean IsPasswordRevealButtonEnabled { get; set; }public bool IsPasswordRevealButtonEnabled { get; set; }Public ReadWrite Property IsPasswordRevealButtonEnabled As bool
<PasswordBox IsPasswordRevealButtonEnabled="bool" />
Value
PlatForm::Boolean bool bool

True to show a password reveal button; false to not show a password reveal button. The default is false.

Attributes

Remarks

Windows 10 PasswordRevealMode replaces IsPasswordRevealButtonEnabled to give you more options for how the user is able to view their password. The IsPasswordRevealButtonEnabled property is ignored.

The value of this property is not the only factor that determines whether a password reveal button is visible to the user. Other factors include whether the control is displayed above a minimum width, whether the PasswordBox has focus, and whether the text entry field contains at least one character.

IsPasswordRevealButtonEnabledProperty IsPasswordRevealButtonEnabledProperty IsPasswordRevealButtonEnabledProperty

Identifies the IsPasswordRevealButtonEnabled dependency property.

public : static DependencyProperty IsPasswordRevealButtonEnabledProperty { get; }public static DependencyProperty IsPasswordRevealButtonEnabledProperty { get; }Public Static ReadOnly Property IsPasswordRevealButtonEnabledProperty As DependencyProperty
Attributes

MaxLength MaxLength MaxLength

Gets or sets the maximum length for passwords to be handled by this PasswordBox.

public : int MaxLength { get; set; }public int MaxLength { get; set; }Public ReadWrite Property MaxLength As int
<PasswordBox MaxLength="int"/>
Value
int int int

An integer that specifies the maximum number of characters for passwords to be handled by this PasswordBox. A value of zero (0) means no limit. The default is 0 (no length limit).

Attributes

MaxLengthProperty MaxLengthProperty MaxLengthProperty

Identifies the MaxLength dependency property.

public : static DependencyProperty MaxLengthProperty { get; }public static DependencyProperty MaxLengthProperty { get; }Public Static ReadOnly Property MaxLengthProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the MaxLength dependency property.

Attributes

Password Password Password

Gets or sets the password currently held by the PasswordBox.

public : PlatForm::String Password { get; set; }public string Password { get; set; }Public ReadWrite Property Password As string
<PasswordBox Password="string"/>
Value
PlatForm::String string string

A string that represents the password currently held by the PasswordBox. The default is an empty string.

Attributes

PasswordChar PasswordChar PasswordChar

Gets or sets the masking character for the PasswordBox.

public : PlatForm::String PasswordChar { get; set; }public string PasswordChar { get; set; }Public ReadWrite Property PasswordChar As string
<PasswordBox PasswordChar="char"/>
Value
PlatForm::String string string

A masking character to echo when the user enters text into the PasswordBox. The default value is a bullet character (‚óŹ).

Attributes

PasswordCharProperty PasswordCharProperty PasswordCharProperty

Identifies the PasswordChar dependency property.

public : static DependencyProperty PasswordCharProperty { get; }public static DependencyProperty PasswordCharProperty { get; }Public Static ReadOnly Property PasswordCharProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the PasswordChar dependency property.

Attributes

PasswordProperty PasswordProperty PasswordProperty

Identifies the Password dependency property.

public : static DependencyProperty PasswordProperty { get; }public static DependencyProperty PasswordProperty { get; }Public Static ReadOnly Property PasswordProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the Password dependency property.

Attributes

PasswordRevealMode PasswordRevealMode PasswordRevealMode

Gets or sets a value that specifies whether the password is always, never, or optionally obscured.

public : PasswordRevealMode PasswordRevealMode { get; set; }public PasswordRevealMode PasswordRevealMode { get; set; }Public ReadWrite Property PasswordRevealMode As PasswordRevealMode
Value
PasswordRevealMode PasswordRevealMode PasswordRevealMode

A value of the enumeration that specifies whether the password is always, never, or optionally obscured. The default is Peek.

Attributes

Examples

This example shows how to use a CheckBox to let a user switch the reveal mode of a PasswordBox.

<StackPanel Width="200">
    <PasswordBox Name="passwordBox1" 
                 PasswordRevealMode="Hidden"/>
    <CheckBox Name="revealModeCheckBox" Content="Show password"
              IsChecked="False" 
              Checked="CheckBox_Changed" Unchecked="CheckBox_Changed"/>
</StackPanel>
private void CheckBox_Changed(object sender, RoutedEventArgs e)
{
    if (revealModeCheckBox.IsChecked == true)
    {
        passwordBox1.PasswordRevealMode = PasswordRevealMode.Visible;
    }
    else
    {
        passwordBox1.PasswordRevealMode = PasswordRevealMode.Hidden;
    }
}

Private Sub CheckBox_Changed(sender As Object, e As RoutedEventArgs)
    If revealModeCheckBox.IsChecked = True Then
        passwordBox1.PasswordRevealMode = PasswordRevealMode.Visible
    Else
        passwordBox1.PasswordRevealMode = PasswordRevealMode.Hidden
    End If
End Sub

Remarks

PasswordRevealMode replaces IsPasswordRevealButtonEnabled to give you more options for how the user is able to view their password. The IsPasswordRevealButtonEnabled property is ignored.

To change the character used to obscure the password, set the PasswordChar property.

Peek mode

By default, the password reveal button (or "peek" button) is shown. The user must continuously press the button to view the password, so that a high level of security is maintained.

A password box with the password shown.

The value of this property is not the only factor that determines whether a password reveal button is visible to the user. Other factors include whether the control is displayed above a minimum width, whether the PasswordBox has focus, and whether the text entry field contains at least one character. The password reveal button is shown only when the PasswordBox receives focus for the first time and a character is entered. If the PasswordBox loses focus and then regains focus, the reveal button is not shown again unless the password is cleared and character entry starts over.

Note

Prior to Windows 10, the password reveal button was not shown by default. If the security of your app requires that the password is always obscured, be sure to set PasswordRevealMode to Hidden.

Hidden and Visible modes

The other PasswordRevealMode enumeration values, Hidden and Visible, hide the password reveal button and let you programmatically manage whether the password is obscured.

To always obscure the password, set PasswordRevealMode to Hidden. Unless you need the password to be always obscured, you can provide a custom UI to let the user toggle the PasswordRevealMode between Hidden and Visible.

In previous versions of Windows Phone, PasswordBox used a CheckBox to toggle whether the password was obscured. You can create a similar UI for your app, as shown in the example. You can also use other controls, like ToggleButton, to let the user switch modes.

A password box with a custom reveal toggle.

See Also

PasswordRevealModeProperty PasswordRevealModeProperty PasswordRevealModeProperty

Identifies the PasswordRevealMode dependency property.

public : static DependencyProperty PasswordRevealModeProperty { get; }public static DependencyProperty PasswordRevealModeProperty { get; }Public Static ReadOnly Property PasswordRevealModeProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the PasswordRevealMode dependency property.

Attributes
See Also

PlaceholderText PlaceholderText PlaceholderText

Gets or sets the text that is displayed in the control until the value is changed by a user action or some other operation.

public : PlatForm::String PlaceholderText { get; set; }public string PlaceholderText { get; set; }Public ReadWrite Property PlaceholderText As string
<PasswordBox PlaceholderText="placeholderString"/>

Value
PlatForm::String string string

The text that is displayed in the control when no value is entered. The default is an empty string ("").

Attributes

PlaceholderTextProperty PlaceholderTextProperty PlaceholderTextProperty

Identifies the PlaceholderText dependency property.

public : static DependencyProperty PlaceholderTextProperty { get; }public static DependencyProperty PlaceholderTextProperty { get; }Public Static ReadOnly Property PlaceholderTextProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the PlaceholderText dependency property.

Attributes

PreventKeyboardDisplayOnProgrammaticFocus PreventKeyboardDisplayOnProgrammaticFocus PreventKeyboardDisplayOnProgrammaticFocus

Gets or sets a value that indicates whether the on-screen keyboard is shown when the control receives focus programmatically.

public : PlatForm::Boolean PreventKeyboardDisplayOnProgrammaticFocus { get; set; }public bool PreventKeyboardDisplayOnProgrammaticFocus { get; set; }Public ReadWrite Property PreventKeyboardDisplayOnProgrammaticFocus As bool
<PasswordBox PreventKeyboardDisplayOnProgrammaticFocus="bool"/>
Value
PlatForm::Boolean bool bool

true if the on-screen keyboard is not shown when the control receives focus programmatically; otherwise, false. The default is false.

Attributes

Remarks

Set this property to true to prevent the onscreen touch keyboard from showing when focus is programmatically set on a text box. By default, the onscreen touch keyboard is displayed whenever focus moves to an editable text box and the most recent input was generated by touch. This happens whether focus is set programmatically or by user interaction. In some situations, you might not want the keyboard to show when focus is set programmatically. For example, you might want to prevent the keyboard from covering part of your UI until the user is ready to continue their interaction.

PreventKeyboardDisplayOnProgrammaticFocusProperty PreventKeyboardDisplayOnProgrammaticFocusProperty PreventKeyboardDisplayOnProgrammaticFocusProperty

Identifies the PreventKeyboardDisplayOnProgrammaticFocus dependency property.

public : static DependencyProperty PreventKeyboardDisplayOnProgrammaticFocusProperty { get; }public static DependencyProperty PreventKeyboardDisplayOnProgrammaticFocusProperty { get; }Public Static ReadOnly Property PreventKeyboardDisplayOnProgrammaticFocusProperty As DependencyProperty
Attributes

SelectionHighlightColor SelectionHighlightColor SelectionHighlightColor

Gets or sets the brush used to highlight the selected text.

public : SolidColorBrush SelectionHighlightColor { get; set; }public SolidColorBrush SelectionHighlightColor { get; set; }Public ReadWrite Property SelectionHighlightColor As SolidColorBrush
<PasswordBox SelectionHighlightColor="{StaticResource resourceName}"/>

Value
SolidColorBrush SolidColorBrush SolidColorBrush

The brush used to highlight the selected text. The default is a null brush from a pure code perspective, but the default control template for PasswordBox applies a theme resource brush for this in a runtime instance of a PasswordBox control.

Attributes

Remarks

The control template sets the default selection highlight color to the system resource TextSelectionHighlightColorThemeBrush. To change the selection highlight color for all editable text controls in your app, you can override the TextSelectionHighlightColorThemeBrush system resource in App.xaml. This will affect PasswordBox, TextBox, and RichEditBox controls. For more info, see XAML theme resources or PasswordBox styles and templates.

See Also

SelectionHighlightColorProperty SelectionHighlightColorProperty SelectionHighlightColorProperty

Identifies the SelectionHighlightColor dependency property.

public : static DependencyProperty SelectionHighlightColorProperty { get; }public static DependencyProperty SelectionHighlightColorProperty { get; }Public Static ReadOnly Property SelectionHighlightColorProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the SelectionHighlightColor dependency property.

Attributes

TextReadingOrder TextReadingOrder TextReadingOrder

Gets or sets a value that indicates how the reading order is determined for the PasswordBox.

public : TextReadingOrder TextReadingOrder { get; set; }public TextReadingOrder TextReadingOrder { get; set; }Public ReadWrite Property TextReadingOrder As TextReadingOrder
<PasswordBox TextReadingOrder="textReadingOrderValue"/>
Value
TextReadingOrder TextReadingOrder TextReadingOrder

A value that indicates how the reading order is determined for the PasswordBox. The default is DetectFromContent.

Attributes

Remarks

This property can be useful when the base direction of the text is unknown, and may not match the user's language or direction. For more info, see the Remarks section of the TextReadingOrder enumeration or How to support bidirectional UI.

See Also

TextReadingOrderProperty TextReadingOrderProperty TextReadingOrderProperty

Identifies the TextReadingOrder dependency property.

public : static DependencyProperty TextReadingOrderProperty { get; }public static DependencyProperty TextReadingOrderProperty { get; }Public Static ReadOnly Property TextReadingOrderProperty As DependencyProperty
Value
DependencyProperty DependencyProperty DependencyProperty

The identifier for the TextReadingOrder dependency property.

Attributes
See Also

Methods

SelectAll() SelectAll() SelectAll()

Selects all the characters in the PasswordBox.

public : void SelectAll()public void SelectAll()Public Function SelectAll() As void
Attributes

Events

ContextMenuOpening ContextMenuOpening ContextMenuOpening

Occurs when the system processes an interaction that displays a context menu.

public : event ContextMenuOpeningEventHandler ContextMenuOpeningpublic event ContextMenuOpeningEventHandler ContextMenuOpeningPublic Event ContextMenuOpening
<PasswordBox ContextMenuOpening="eventhandler" />
Attributes

PasswordChanged PasswordChanged PasswordChanged

Occurs when the value of the Password property changes.

public : event RoutedEventHandler PasswordChangedpublic event RoutedEventHandler PasswordChangedPublic Event PasswordChanged
<PasswordBox PasswordChanged="eventhandler"/>
Attributes

Paste Paste Paste

Occurs when text is pasted into the control.

public : event TextControlPasteEventHandler Pastepublic event TextControlPasteEventHandler PastePublic Event Paste
<PasswordBox Paste="eventhandler"/>
Attributes

Remarks

The Paste event occurs before any content is inserted into the control. You can handle this event to check the contents of the clipboard and perform any actions on the content before it's inserted. If you perform any action, set the handled property to true; otherwise, the default paste action is performed. If you set the handled property to true, then it's assumed the app has handled the insertion, and no default action is performed. You are responsible for determining the insertion point and clipboard content to insert, and inserting the content.

See Also