Xamarin.Forms Editor

Multi-line text input

The Editor control is used to accept multi-line input. This article covers:

Customization

Setting and Reading Text

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

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

In C#:

var MyEditor = new Editor { Text = "I am an Editor" };

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

var text = MyEditor.Text;

Limiting Input Length

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

<Editor ... MaxLength="10" />
var editor = new Editor { ... 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 Editor, indicates that there is no effective limit on the number of characters that may be entered.

Auto-Sizing an Editor

An Editor can be made to auto-size to its content by setting the Editor.AutoSize property to TextChanges, which is a value of the EditoAutoSizeOption enumeration. This enumeration has two values:

  • Disabled indicates that automatic resizing is disabled, and is the default value.
  • TextChanges indicates that automatic resizing is enabled.

This can be accomplished in code as follows:

<Editor Text="Enter text here" AutoSize="TextChanges" />
var editor = new Editor { Text = "Enter text here", AutoSize = EditorAutoSizeOption.TextChanges };

When auto-resizing is enabled, the height of the Editor will increase when the user fills it with text, and the height will decrease as the user deletes text.

Note

An Editor will not auto-size if the HeightRequest property has been set.

Customizing the Keyboard

The keyboard that's presented when users interact with an Editor 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:

<Editor Keyboard="Chat" />

The equivalent C# code is:

var editor = new Editor { 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:

<Editor>
    <Editor.Keyboard>
        <Keyboard x:FactoryMethod="Create">
            <x:Arguments>
                <KeyboardFlags>Suggestions,CapitalizeCharacter</KeyboardFlags>
            </x:Arguments>
        </Keyboard>
    </Editor.Keyboard>
</Editor>

The equivalent C# code is:

var editor = new Editor();
editor.Keyboard = Keyboard.Create(KeyboardFlags.Suggestions | KeyboardFlags.CapitalizeCharacter);

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 so should be disabled by setting the IsSpellCheckEnabled property to false:

<Editor ... IsSpellCheckEnabled="false" />
var editor = new Editor { ... 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.

Colors

Editor can be set to use a custom background color via the BackgroundColor property. Special care is necessary to ensure that colors will be usable on each platform. Because each platform has different defaults for text color, you may need to set a custom background color for each platform. See Working with Platform Tweaks for more information about optimizing the UI for each platform.

In C#:

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        //dark blue on UWP & Android, light blue on iOS
        var editor = new Editor { BackgroundColor = Device.RuntimePlatform == Device.iOS ? Color.FromHex("#A4EAFF") : Color.FromHex("#2c3e50") };
        layout.Children.Add(editor);
    }
}

In XAML:

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    x:Class="TextSample.EditorPage"
    Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor>
                <Editor.BackgroundColor>
                    <OnPlatform x:TypeArguments="x:Color">
                        <On Platform="iOS" Value="#a4eaff" />
                        <On Platform="Android, UWP" Value="#2c3e50" />
                    </OnPlatform>
                </Editor.BackgroundColor>
            </Editor>
        </StackLayout>
    </ContentPage.Content>
</ContentPage>

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

Interactivity

Editor exposes two events:

  • TextChanged – raised when the text changes in the editor. 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 Editor. Completed is raised when the user ends input with a field by entering the return key on the keyboard. The handler for the event is a generic event handler, taking the sender and EventArgs:

void EditorCompleted (object sender, EventArgs e)
{
    var text = ((Editor)sender).Text; // sender is cast to an Editor to enable reading the `Text` property of the view.
}

The completed event can be subscribed to in code and XAML:

In C#:

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        var editor = new Editor ();
        editor.Completed += EditorCompleted;
        layout.Children.Add(editor);
    }
}

In XAML:

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="TextSample.EditorPage"
Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor Completed="EditorCompleted" />
        </StackLayout>
    </ContentPage.Content>
</Contentpage>

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 Editor changes. The handler for the event takes an instance of TextChangedEventArgs. TextChangedEventArgs provides access to the old and new values of the Editor Text via the OldTextValue and NewTextValue properties:

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

The completed event can be subscribed to in code and XAML:

In code:

public partial class EditorPage : ContentPage
{
    public EditorPage ()
    {
        InitializeComponent ();
        var layout = new StackLayout { Padding = new Thickness(5,10) };
        this.Content = layout;
        var editor = new Editor ();
        editor.TextChanged += EditorTextChanged;
        layout.Children.Add(editor);
    }
}

In XAML:

<?xml version="1.0" encoding="UTF-8"?>
<ContentPage xmlns="http://xamarin.com/schemas/2014/forms"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="TextSample.EditorPage"
Title="Editor Demo">
    <ContentPage.Content>
        <StackLayout Padding="5,10">
            <Editor TextChanged="EditorTextChanged" />
        </StackLayout>
    </ContentPage.Content>
</ContentPage>