APL Text (APL 1.4 to 1.5)

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

(This is not the most recent version of APL. Use the Other Versions option to see the documentation for the most recent version of APL)

The Text component displays text in either a single line or multiple lines.

Properties

The Text component has the following properties in addition to the base component properties. See the meaning of the columns.

Property	Type	Default	Styled	Dynamic	Description
`color`	Color	depends on the theme	Yes	Yes	The color of the text.
`fontFamily`	String	sans-serif	Yes	No	Font family (such as "Amazon Ember Display").
`fontSize`	Non-negative absolute Dimension	40dp	Yes	No	The size of the text.
`fontStyle`	`normal`, `italic`	normal	Yes	No	The font style to display.
`fontWeight`	`normal`, `bold`, 100, 200, 300, 400, 500, 600, 700, 800, 900	normal	Yes	No	The font weight to display.
`letterSpacing`	Absolute Dimension	0	Yes	No	Additional space to add between letters.
`lineHeight`	Number (percentage)	125%	Yes	No	Line-height multiplier.
`maxLines`	Non-negative integer	0	Yes	No	The maximum number of lines of text to display. The text will be truncated with an ellipsis if not all text is visible.
`text`	String	""	No	Yes	The markup to display in this text box. If this value is set to `null` or an empty string "", no content appears.
`textAlign`	`auto`, `left`, `right`, `center`	auto	Yes	No	Alignment of text within a paragraph.
`textAlignVertical`	`auto`, `top`, `bottom`, `center`	auto	Yes	No	Vertical alignment of text.

Most of these properties have default values specified by the current text style. Refer to Resources for a discussion of styles.

A Text component does not scroll unless it is placed within a ScrollView.

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

{
  // Text-specific values
  "type": "Text",
  "text": String,      // Displayed 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)
}

color

The color of the text. If the theme is light, the default is #1E2222. If the theme is dark, the default is #FAFAFA.

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.

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"
      }
    }
  ]
}

letterSpacing

Additional space to add between letters. Defaults to 0.

lineHeight

Line-height multiplier. Defaults to 125%.

The leading of the font is the fontSize multiplied by the lineHeight. For example, on a 320 dpi display with 100dp fontSize and 120% lineHeight, the font size is 200 pixels and the leading is 240 pixels. Setting the lineHeight to less than 100% can cause characters to overlap.

maxLines

The maximum number of lines of text to display. Defaults to 0, which indicates no maximum. Set to a positive integer to clip the text to the specified number of lines and insert an ellipsis to show that the text is truncated.

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 ("").

Text blocks support simple markup. Supported tags include:

Tag	Description	Example	Display
`<br>`	Insert a line break. Line breaks may be repeated.	Line 1`<br>`Line 2	Line 1 Line 2
`<strong>`, `<b>`	Bold a span of text.	`<b>`Large`</b>` dogs are friendly.	Large dogs are friendly.
`<em>`, `<i>`	Italic a span of text.	Read `<em>`Emma`</em>` for homework.	Read Emma for homework.
`<strike>`	~~Strikethrough~~ a span of text	The document is `<strike>`fine`</strike>` pretty good.	The document is ~~fine~~ pretty good.
`<u>`	Underline a span of text	I just `<u>`loved`</u>` the chocolate!	I just loved the chocolate!
`<tt>`, `<code>`	Monospace a span of text.	The `<code>`main`</code>` function is the entry point.	The `main` function is the entry point.
`<sup>`, `<sub>`	Superscript and subscript a span of text.	See Gibson`<sup>`1`</sup>` for the H`<sub>`2`</sub>`O formula.	See Gibson¹ for the H₂O formula.

Markup elements can be nested. Improperly nested markup gives undefined behavior. For example, the following code might not render correctly because the <b> and <u> elements aren't nested correctly.

<b>Once upon a time, <u>a small dog</b> ate a grasshopper and felt ill.</u>.

Markup characters in text must be replaced with character entity references.

Entity	Character	Description
`&`	\&	Ampersand
`<`	<	Less-than
`>`	>	Greater-than
`&#nn;`	Any Decimal Unicode code-point.	"nn" is a valid integer.
`&#xnn;`	Hexadecimal Unicode code-point.	"nn" is a valid hexadecimal number

textAlign

Controls the positioning of lines of text: left, center, right, auto. The default is auto, which uses the default font direction (for example, left for English).

textAlignVertical

Positions the text within the text box. Only used if the text box is taller than the text content. Defaults to top.

Sample Text

{
 "type": "Text",
 "width": "100%",
 "textAlign": "center",
 "style": "textStylePrimary2",
 "text": "<b>Hello!</b> This is your <i>Alexa</i> assistant speaking!",
 "maxLines": 2
}

Was this page helpful?

Provide feedback

Last updated: Jun 18, 2024