APL EditText

The EditText component displays text in an editable box that supports modifying a single line of text.

Some environments might not allow editable text. Use the environment property disallowEditText to determine whether the current device and configuration supports editable text.

Properties

The EditText component has the following properties:

• All actionable component properties
• All base component properties
• The EditText properties listed in following table. See the meaning of the columns.

When the EditText is the source or target of an event, the following values are reported in event.source or event.target:

{
  // EditText-specific values
  "type": "EditText",
  "text": String,      // Displayed text (never the hint text)
  "color": Color,      // The text color

  // General component values
  "bind": Map,         // Access to component data-binding context
  "checked": Boolean,  // Checked state
  "disabled": Boolean, // Disabled state
  "focused": Boolean,  // Focused state
  "height": Number,    // Height of the component, in dp (includes the padding)
  "id": ID,            // ID of the component
  "opacity": Number,   // Opacity of the component [0-1]
  "pressed": Boolean,  // Pressed state
  "uid": UID,          // Runtime-generated unique ID of the component
  "width": Number      // Width of the component, in dp (includes the padding)
}

layoutDirection component property

The component layoutDirection property determines the starting point and direction of the cursor for editing text:

• LTR: the cursor in the EditText component starts from the left and moves to the right.
• RTL: the cursor in the EditText component starts from the right and moves to the left.

borderColor

The color of the border surrounding the EditText box.

borderStrokeWidth

The width of the drawn border around the text box. When not specified, borderStrokeWidth defaults to the specified borderWidth. When specified, the actual width of the drawn border is the smaller value of the borderStrokeWidth and borderWidth. You can't draw a border outside of the border width.

Set this property separately from borderWidth when you want to vary the width of the drawn border without re-laying out the positions of components in their parent. For example, assume you set borderWidth to 2 and borderStrokeWidth to 1. The component displays with a one-pixel border, but occupies enough space on the viewport for a two-pixel border. When you change borderStrokeWidth to 2, the component displays with a two-pixel border without changing the amount of space the component occupies.

In contrast, if you use borderWidth on its own and change it from 1 to 2, the components displayed on the screen shift to accommodate the larger border.

borderWidth

The width of the border around the text box. Specify borderWidth in an absolute dimension. You can't use relative dimensions. The border width does not affect the padding of the EditText component.

color

The color of the displayed text. Defaults to #FAFAFA for a dark theme and #1E2222 for a light theme.

fontFamily

Specifies the font for the displayed text. The fontFamily property takes a single font name or a string containing a comma-separated list of font names. The APL runtime searches the list for the first named font installed on the device. If no valid font is found, the runtime defaults to the sans-serif font.

Font names can contain spaces. APL supports two types of font names:

• The specific name of an installed font such as "amazon-ember", "times", "times new roman".
• A generic name - either "serif" or "sans-serif".

Alexa devices don't guarantee a specific set of fonts. End your fontFamily list with either "serif" or "sans-serif" to make sure that a valid font is available.

{
"type": "Text",
"fontFamily", "times new roman, times, georgia, serif"
}

On many Alexa devices, "sans-serif" defaults to "Amazon Ember Display" and "serif" defaults to "Bookerly". In some Asian markets they default to "Noto Sans CJK".

For details about font styles available in the alexa-styles package, see Font family.

fontSize

The size of the font. Defaults to 40dp. Specify the font size in absolute dimensions, not relative.

fontStyle

The style of the font, either normal or italic. Defaults to normal.

fontWeight

The font weight for the displayed text. Defaults to normal. The normal and bold values are assigned at runtime. The integer values 100 through 900 correspond to progressively darker variations of the font. Most fonts don't support this many variations. For example, Amazon Ember Display has five weights (Thin, Light, Regular, Medium, Bold) which are assigned 100, 300, 500, 700, and 900 respectively.

Note that fontWeight represents an enumerated set, not integers or strings. For example, the value 750 is invalid and doesn't set the font to a weight between 700 and 800.

When you create a resource for a fontWeight, use a string resource. The following example resource block creates two resources for fontWeight called myMidFontWeight and myLightFontWeight.

{
  "resources": [
    {
      "strings": {
        "myMidFontWeight": "500",
        "myLightFontWeight": "100"
      }
    }
  ]
}

highlightColor

The color of the highlight shown behind a selected region of text. Defaults to #00CAFF4D for a dark theme and #0070BA4D for a light theme.

hint

A text string to display in the text block when there is no text to display. The hint displays when text is not set, or when the user deletes any text from the text block.

hintColor

The color of the hint text. Defaults to a theme-dependent and device-dependent value when not specified.

hintStyle

The style of the hint font – either normal or italic.

hintWeight

The weight of the hint font. This property works the same as the fontWeight property.

keyboardType

Specifies the type of keyboard to display for the component. Accepts one of the following values.

The component defaults to the normal (default) keyboard when the APL runtime doesn't support the requested keyboard.

lang

The language of the text. When set, APL attempts to find a language-specific version of the fontFamily for displaying the text.

If no valid font is found, APL ignores this property and uses the specified fontFamily.

Set the lang property to a BCP-47 string (for example, "en-US").

The following example displays an EditText component with a Japanese-style version of the NotoSans-CJK font:

{
    "type": "APL",
    "version": "2022.1",
    "mainTemplate": {
        "item": {
            "type": "EditText",
            "lang": "ja-JP",
            "fontFamily": "Noto Sans CJK"
        }
    }
}

Note: Alexa devices might not have the font in specific language installed. Test the experience on the device or devices to confirm that it works.

maxLength

The maximum length of the text permitted in the edit text component, in characters. Set to 0 to allow an unrestricted number of characters. Specific implementations may find it necessary to limit the maximum text length internally; it is recommended that they support at least 1024 characters.

onTextChange

Commands to run when the user changes the text displayed in the component. This action sets event.source.value to the text content of the EditText component.

This handler generates an event with the following form.

"event": {
  "source": {
    "type": "EditText",
    "handler": "TextChange",
    ...                     // Component source properties
  }
}

Refer to Event source for a description of event.source properties.

onSubmit

Commands to run when the user presses the defined submit key. Configure the key that means "submit" with the submitKeyType property.

This handler generates an event with the following form.

"event": {
  "source": {
    "type": "EditText",
    "handler": "Submit",
    ...                     // Component source properties
  }
}

Refer to Event source for a description of event.source properties.

secureInput

When true, the component obscures all characters as the user enters a value. Use this for sensitive text. This following keyboard types support secureInput:

• decimalPad
• normal
• numberPad

selectOnFocus

When true, the component highlights the text in the text block when the component gains focus. The user can delete all of the existing text in the component with a single backspace keystroke. When false, the cursor insertion point displays at the end of the text. This property defaults to false.

size

Specifies the default width of the EditText component assuming that there are size-number of "normal-width" characters in the current font. The actual number of characters that fit in the EditText component depends on the width of the actual characters.

submitKeyType

Specifies the type of the submit key. The label of the key depends on the underlying platform. The following types are available:

No matter what the label of the submit key, the onSubmit event runs when the user presses the key.

text

Text string to display in the text block. If set to an empty string, no text displays. Setting to null is equivalent to an empty string ("").

When text is empty or null, the EditText component displays the hintText. The text the user enters replaces the displayed text.

The character restrictions set in validCharacters apply to the text property. For example, if you set validCharacters to restrict the set of characters the user can enter, you must set text to a value meets those same restrictions.

validCharacters

When set, the characters that users can enter in the EditText component are restricted to the characters provided. When empty or not set, there aren't any restrictions on characters.

The restrictions apply to the text property. This includes all the scenarios in which you set or change the text property:

• You set an initial value for the text property in your APL document
• You use the SetValue command to set or change the value of the text property
• The user selects the EditText component and types a value

The validCharacters property doesn't apply to the hintText property.

The following example restricts the component to hexadecimal characters.

{
  "type": "EditText",
  "validCharacters": "0-9a-fA-F"
}

The validCharacters property is not a regular expression. The purpose of the validCharacters property is to restrict character entry, not to validate the correctness of the final expression. The following table lists the rules for special characters:

Examples:

"0-9"               // Pin-pad keyboard
"0-9."              // Cash amount in US (good for an ATM)
"-+a-zA-Z0-9_@."    // Classic e-mail address

EditText height and width

Set the component height and width properties. When you leave height and width not set, EditText calculates the height and width.

The height of the component is set to display a single line of characters in the specified font. The width of the edit text component is calculated using the size property.

EditText focus state

The EditText component doesn't automatically show focus state. Use APL styles and the borderWidth and borderColor properties to highlight the component when it gains focus.

The following example uses a conditional style to change both the border color and the border width when the EditText component gets the focus.

{
  "type": "APL",
  "version": "2022.1",
  "styles": {
    "EditStyle": {
      "values": [
        {
          "borderWidth": 2,
          "borderStrokeWidth": 1,
          "borderColor": "darkgrey",
          "hintColor": "grey",
          "hintWeight": "200",
          "color": "black",
          "fontSize": "20dp",
          "size": 10
        },
        {
          "when": "${state.focused}",
          "borderColor": "green",
          "borderStrokeWidth": 2
        }
      ]
    }
  },
  "mainTemplate": {
    "items": {
      "type": "EditText",
      "style": "EditStyle",
      "hint": "Zip code",
      "validCharacters": "-0-9"
    }
  }
}

Related topics

• Base Component Properties
• Actionable Component Properties
• APL Text