APL EditText

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

Properties

The EditText component has the following properties:

Property Type Default Styled Dynamic Description
borderColor Color <none> Yes Yes Color of the border around the text box.
borderStrokeWidth Non-negative Absolute Dimension <borderWidth> Yes Yes Width of the border stroke around the text box.
borderWidth Non-negative Absolute Dimension 0 Yes No Width of the border.
color Color Depends on the theme Yes No Color of the text the user enters or the text provided in the text property.
fontFamily String sans-serif Yes No The name of the font family.
fontSize Positive Absolute Dimension 40dp Yes No The size of the text
fontStyle normal, italic normal Yes No The style of the font
fontWeight normal, bold, 100, 200, 300, 400, 500, 600, 700, 800, 900 normal Yes No The weight of the font
highlightColor Color Depends on the theme Yes No The highlight color to show behind selected text.
hint String "" Yes No Hint text to display when no text has been entered. Not shown when the text property contains a value.
hintColor Color Depends on the theme Yes No The color of the hint text.
hintStyle normal, italic normal Yes No The style of the hint font
hintWeight normal, bold, 100, 200, 300, 400, 500, 600, 700, 800, 900 normal Yes No The weight of the hint font
keyboardType KeyboardType normal Yes No The type of keyboard to display when the user selects the component.
maxLength Non-negative integer 0 Yes No The maximum number of characters the user can enter in the edit box.
onTextChange Array of Commands [] No No Command to execute when the text changes from a user event.
onSubmit Array of Commands [] No No Command to execute when the user submits the update by pressing the specified submit key (submitKeyType.
secureInput Boolean false Yes Yes Hide characters as they are typed if true.
selectOnFocus Boolean false Yes No When true, select the text when the EditText component gets the focus.
size Positive integer 8 Yes No Specifies approximately the number of characters to display.
submitKeyType SubmitKeyType done Yes No The type of the return key. The specified key sends an onSubmit event.
text String "" No Yes The text to display.
validCharacters String "" Yes No Restrict the characters that can be entered

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)
}

borderColor

The color of the border around 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.

Type Description
decimalPad Numbers and a decimal point
emailAddress Optimized for e-mail addresses, including the "@", ".", and space character.
normal Default keyboard
numberPad Numbers only (good for PIN codes)
phonePad Numbers and the "*" and "#" characters
url Optimized for entering URLs

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

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 execute 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 execute 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:

Type Example Label on Echo Show Devices (in en-US)
done Done
go Go
next Next
search Search
send Send

No matter what the label of the submit key, the onSubmit event executes 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:

Characters Meaning
- Specifies a range for Unicode code points. To include a hyphen (-) as a valid character, put it at the front of the string
\uXXXX Four hex digits, specifying a specific Unicode code point. Code points outside the Basic Multilingual Plane should be written using UTF-16 surrogate pairs.
\" Quotation mark
\\ Reverse solidus

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.

Copied to clipboard.

{
  "type": "APL",
  "version": "1.4",
  "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"
    }
  }
}