Xamarin.Forms Entry

Single-line text or password input

The Xamarin.Forms Entry is used for single-line text input. The Entry, like the Editor view, supports multiple keyboard types. Additionally, the Entry can be used as a password field.

Display Customization

Setting and Reading Text

The Entry, like other text-presenting views, exposes the Text property. This property can be used to set and read the text presented by the Entry. The following example demonstrates setting the Text property in XAML:

<Entry Text="I am an Entry" />

In C#:

var MyEntry = new Entry { Text = "I am an Entry" };

To read text, access the Text property in C#:

var text = MyEntry.Text;

Note

The width of an Entry can be defined by setting its WidthRequest property. Do not depend on the width of an Entry being defined based on the value of its Text property.

Limiting Input Length

The MaxLength property can be used to limit the input length that's permitted for the Entry. This property should be set to a positive integer:

<Entry ... MaxLength="10" />
var entry = new Entry { ... MaxLength = 10 };

A MaxLength property value of 0 indicates that no input will be allowed, and a value of int.MaxValue, which is the default value for an Entry, indicates that there is no effective limit on the number of characters that may be entered.

Setting the Cursor Position and Text Selection Length

The CursorPosition property can be used to return or set the position at which the next character will be inserted into the string stored in the Text property:

<Entry Text="Cursor position set" CursorPosition="5" />
var entry = new Entry { Text = "Cursor position set", CursorPosition = 5 };

The default value of the CursorPosition property is 0, which indicates that text will be inserted at the start of the Entry.

In addition, the SelectionLength property can be used to return or set the length of text selection within the Entry:

<Entry Text="Cursor position and selection length set" CursorPosition="2" SelectionLength="10" />
var entry = new Entry { Text = "Cursor position and selection length set", CursorPosition = 2, SelectionLength = 10 };

The default value of the SelectionLength property is 0, which indicates that no text is selected.

Customizing the Keyboard

The keyboard that's presented when users interact with an Entry can be set programmatically via the Keyboard property, to one of the following properties from the Keyboard class:

  • Chat – used for texting and places where emoji are useful.
  • Default – the default keyboard.
  • Email – used when entering email addresses.
  • Numeric – used when entering numbers.
  • Plain – used when entering text, without any KeyboardFlags specified.
  • Telephone – used when entering telephone numbers.
  • Text – used when entering text.
  • Url – used for entering file paths & web addresses.

This can be accomplished in XAML as follows:

<Entry Keyboard="Chat" />

The equivalent C# code is:

var entry = new Entry { Keyboard = Keyboard.Chat };

Examples of each keyboard can be found in our Recipes repository.

The Keyboard class also has a Create factory method that can be used to customize a keyboard by specifying capitalization, spellcheck, and suggestion behavior. KeyboardFlags enumeration values are specified as arguments to the method, with a customized Keyboard being returned. The KeyboardFlags enumeration contains the following values:

  • None – no features are added to the keyboard.
  • CapitalizeSentence – indicates that the first letter of the first word of each entered sentence will be automatically capitalized.
  • Spellcheck – indicates that spellcheck will be performed on entered text.
  • Suggestions – indicates that word completions will be offered on entered text.
  • CapitalizeWord – indicates that the first letter of each word will be automatically capitalized.
  • CapitalizeCharacter – indicates that every character will be automatically capitalized.
  • CapitalizeNone – indicates that no automatic capitalization will occur.
  • All – indicates that spellcheck, word completions, and sentence capitalization will occur on entered text.

The following XAML code example shows how to customize the default Keyboard to offer word completions and capitalize every entered character:

<Entry Placeholder="Enter text here">
    <Entry.Keyboard>
        <Keyboard x:FactoryMethod="Create">
            <x:Arguments>
                <KeyboardFlags>Suggestions,CapitalizeCharacter</KeyboardFlags>
            </x:Arguments>
        </Keyboard>
    </Entry.Keyboard>
</Entry>

The equivalent C# code is:

var entry = new Entry { Placeholder = "Enter text here" };
entry.Keyboard = Keyboard.Create(KeyboardFlags.Suggestions | KeyboardFlags.CapitalizeCharacter);

Customizing the Return Key

The appearance of the return key on the soft keyboard, which is displayed when an Entry has focus, can be customized by setting the ReturnType property to a value of the ReturnType enumeration:

  • Default – indicates that no specific return key is required and that the platform default will be used.
  • Done – indicates a "Done" return key.
  • Go – indicates a "Go" return key.
  • Next – indicates a "Next" return key.
  • Search – indicates a "Search" return key.
  • Send – indicates a "Send" return key.

The following XAML example shows how to set the return key:

<Entry ReturnType="Send" />

The equivalent C# code is:

var entry = new Entry { ReturnType = ReturnType.Send };

Note

The exact appearance of the return key is dependent upon the platform. On iOS, the return key is a text-based button. However, on the Android and Universal Windows Platforms, the return key is a icon-based button.

When the return key is pressed, the Completed event fires and any ICommand specified by the ReturnCommand property is executed. In addition, any object specified by the ReturnCommandParameter property will be passed to the ICommand as a parameter. For more information about commands, see The Command Interface.

Enabling and Disabling Spell Checking

The IsSpellCheckEnabled property controls whether spell checking is enabled. By default, the property is set to true. As the user enters text, misspellings are indicated.

However, for some text entry scenarios, such as entering a username, spell checking provides a negative experience and should be disabled by setting the IsSpellCheckEnabled property to false:

<Entry ... IsSpellCheckEnabled="false" />
var entry = new Entry { ... IsSpellCheckEnabled = false };

Note

When the IsSpellCheckEnabled property is set to false, and a custom keyboard isn't being used, the native spell checker will be disabled. However, if a Keyboard has been set that disables spell checking, such as Keyboard.Chat, the IsSpellCheckEnabled property is ignored. Therefore, the property cannot be used to enable spell checking for a Keyboard that explicitly disables it.

Enabling and Disabling Text Prediction

The IsTextPredictionEnabled property controls whether text prediction and automatic text correction is enabled. By default, the property is set to true. As the user enters text, word predictions are presented.

However, for some text entry scenarios, such as entering a username, text prediction and automatic text correction provides a negative experience and should be disabled by setting the IsTextPredictionEnabled property to false:

<Entry ... IsTextPredictionEnabled="false" />
var entry = new Entry { ... IsTextPredictionEnabled = false };

Note

When the IsTextPredictionEnabled property is set to false, and a custom keyboard isn't being used, text prediction and automatic text correction is disabled. However, if a Keyboard has been set that disables text prediction, the IsTextPredictionEnabled property is ignored. Therefore, the property cannot be used to enable text prediction for a Keyboard that explicitly disables it.

Setting Placeholder Text

The Entry can be set to show placeholder text when it is not storing user input. This is accomplished by setting the Placeholder property to a string, and is often used to indicate the type of content that is appropriate for the Entry. In addition, the placeholder text color can be controlled by setting the PlaceholderColor property to a Color:

<Entry Placeholder="Username" PlaceholderColor="Olive" />
var entry = new Entry { Placeholder = "Username", PlaceholderColor = Color.Olive };

Password Fields

Entry provides the IsPassword property. When IsPassword is true, the contents of the field will be presented as black circles:

In XAML:

<Entry IsPassword="true" />

In C#:

var MyEntry = new Entry { IsPassword = true };

Placeholders may be used with instances of Entry that are configured as password fields:

In XAML:

<Entry IsPassword="true" Placeholder="Password" />

In C#:

var MyEntry = new Entry { IsPassword = true, Placeholder = "Password" };

Colors

Entry can be set to use a custom background and text colors via the following bindable properties:

  • TextColor – sets the color of the text.
  • BackgroundColor – sets the color shown behind the text.

Special care is necessary to ensure that colors will be usable on each platform. Because each platform has different defaults for text and background colors, you'll often need to set both if you set one.

Use the following code to set the text color of an entry:

In XAML:

<Entry TextColor="Green" />

In C#:

var entry = new Entry();
entry.TextColor = Color.Green;

Note that the placeholder is not affected by the specified TextColor.

To set the background color in XAML:

<Entry BackgroundColor="#2c3e50" />

In C#:

var entry = new Entry();
entry.BackgroundColor = Color.FromHex("#2c3e50");

Be careful to make sure that the background and text colors you choose are usable on each platform and don't obscure any placeholder text.

Events and Interactivity

Entry exposes two events:

  • TextChanged – raised when the text changes in the entry. Provides the text before and after the change.
  • Completed – raised when the user has ended input by pressing the return key on the keyboard.

Completed

The Completed event is used to react to the completion of an interaction with an Entry. Completed is raised when the user ends input with a field by pressing the return key on the keyboard. The handler for the event is a generic event handler, taking the sender and EventArgs:

void Entry_Completed (object sender, EventArgs e)
{
    var text = ((Entry)sender).Text; //cast sender to access the properties of the Entry
}

The completed event can be subscribed to in XAML:

<Entry Completed="Entry_Completed" />

and C#:

var entry = new Entry ();
entry.Completed += Entry_Completed;

After the Completed event fires, any ICommand specified by the ReturnCommand property is executed, with the object specified by the ReturnCommandParameter property being passed to the ICommand.

TextChanged

The TextChanged event is used to react to a change in the content of a field.

TextChanged is raised whenever the Text of the Entry changes. The handler for the event takes an instance of TextChangedEventArgs. TextChangedEventArgs provides access to the old and new values of the Entry Text via the OldTextValue and NewTextValue properties:

void Entry_TextChanged (object sender, TextChangedEventArgs e)
{
    var oldText = e.OldTextValue;
    var newText = e.NewTextValue;
}

The TextChanged event can be subscribed to in XAML:

<Entry TextChanged="Entry_TextChanged" />

and C#:

var entry = new Entry ();
entry.TextChanged += Entry_TextChanged;