# Titanium.UI.TextArea

A multiline text field that supports editing and scrolling.

Availability
0.8
0.8
9.2.0
4.1.0

# Overview

Android iOS Windows
Android iOS Windows

Use the Titanium.UI.createTextArea method or <TextArea> Alloy element to create a text area.

# click event in iOS

In iOS 11+, click event in text area is not fired due to changes from apple. Use touchstart event instead of click event.

# Examples

# Basic Text Area with Customizations

This example creates a highly customized text area.

var win = Ti.UI.createWindow({
  backgroundColor: 'white'
});
var textArea = Ti.UI.createTextArea({
  borderWidth: 2,
  borderColor: '#bbb',
  borderRadius: 5,
  color: '#888',
  font: {fontSize:20, fontWeight:'bold'},
  keyboardType: Ti.UI.KEYBOARD_NUMBER_PAD,
  returnKeyType: Ti.UI.RETURNKEY_GO,
  textAlign: 'left',
  value: 'I am a textarea',
  top: 60,
  width: 300, height : 70
});
win.add(textArea);
win.open();

# Text Area with Custom Keyboard Toolbar (iOS)

On iOS, a configurable toolbar can be displayed above the virtual keyboard. Toolbars can be used with both text areas and text fields. See Titanium.UI.iOS.Toolbar for more information.

This code excerpt creates a text area with a toolbar:

Example using a custom keyboard toolbar:

var send = Ti.UI.createButton({
    style : Ti.UI.iOS.SystemButtonStyle.DONE,
    title : 'Send'
});

var camera = Ti.UI.createButton({
    systemButton : Ti.UI.iOS.SystemButton.CAMERA
});

var cancel = Ti.UI.createButton({
    systemButton : Ti.UI.iOS.SystemButton.CANCEL
});

var flexSpace = Ti.UI.createButton({
    systemButton : Ti.UI.iOS.SystemButton.FLEXIBLE_SPACE
});

var textarea = Ti.UI.createTextArea({
    borderColor : '#000',
    color : '#000',
    keyboardToolbar : [cancel, flexSpace, camera, flexSpace, send],
    keyboardToolbarColor : '#999',
    keyboardToolbarHeight : 40,
    value : 'Focus to see keyboard with toolbar',
    top : 10,
    width : 300, height : 120
});

# Alloy XML Markup

Previous basic text area with customizations example as an Alloy view.

<Alloy>
    <Window id="win" backgroundColor="white">
        <TextArea id="textArea"
            borderWidth="2" borderColor="#bbb" borderRadius="5"
            color="#888" textAlign="left" value="I am a textarea"
            top="60" width="300" height="70" />
    </Window>
</Alloy>

# Properties

# appearance DEPRECATED

Availability
0.8
appearance :Number

DEPRECATED SINCE 5.2.0

Use keyboardAppearance instead.

Determines the appearance of the keyboard displayed when this text area is focused.

Default: Titanium.UI.KEYBOARD_APPEARANCE_DEFAULT


# attributedHintText

Availability
3.6.0
3.2.0
9.2.0
attributedHintText :Titanium.UI.AttributedString

Hint text attributed string.

The attributed hint text by the text area. If set, avoid setting common attributes in text area, such as hintText, color and font, as unexpected behaviors may result.

This has no effect when used with hintType Ti.UI.HINT_TYPE_ANIMATED.

Prior to Release 3.6.0, assign this property an object from the <Titanium.UI.iOS.AttributedString> class.

Since Appcelerator CLI 4.1.0 (Alloy 1.7.0), for Alloy, you can use an <AttributedHintText> element inside a <TextField> element and set the text property as node text:

<Alloy>
  <Window>
      <TextField>
        <AttributedHintText>
            Alloy is great!
        </AttributedHintText>
      </TextField>
  </Window>
</Alloy>

Then set attributes in the TSS file:

"AttributedString" : {
  attributes: [
    {
      type: Ti.UI.ATTRIBUTE_FOREGROUND_COLOR,
      value: 'red',
      range: [0, 5]
    },
    {
      type: Ti.UI.ATTRIBUTE_UNDERLINES_STYLE,
      value: Ti.UI.ATTRIBUTE_UNDERLINE_STYLE_SINGLE,
      range: [9, 5]
    }
  ]
}

# attributedString

Availability
3.6.0
3.2.0
9.2.0
attributedString :Titanium.UI.AttributedString

TextArea attributed string.

The underlying attributed string drawn by the textArea. If set, avoid setting common attributes in textArea, such as value, color and font, as unexpected behaviors may result.

Prior to Release 3.6.0, assign this property an object from the <Titanium.UI.iOS.AttributedString> class.

Since Appcelerator CLI 4.1.0 (Alloy 1.7.0), for Alloy, you can use an <AttributedString> element inside a <TextArea> element and set the text property as node text:

<Alloy>
  <Window>
      <TextArea>
        <AttributedString>
            Alloy is great!
        </AttributedString>
      </TextArea>
  </Window>
</Alloy>

Then set attributes in the TSS file:

"AttributedString" : {
  attributes: [
    {
      type: Ti.UI.ATTRIBUTE_FOREGROUND_COLOR,
      value: 'red',
      range: [0, 5]
    },
    {
      type: Ti.UI.ATTRIBUTE_UNDERLINES_STYLE,
      value: Ti.UI.ATTRIBUTE_UNDERLINE_STYLE_SINGLE,
      range: [9, 5]
    }
  ]
}

# autocapitalization

Availability
0.8
0.8
9.2.0
autocapitalization :Number

Determines how text is capitalized during typing.

Default: Titanium.UI.TEXT_AUTOCAPITALIZATION_NONE


# autocorrect

Availability
0.8
0.8
9.2.0
autocorrect :Boolean

Determines whether to automatically correct text entered into this text area.

Set to true to enable automatic spelling correction. On iOS 9+, this can be used to disable QuickType suggestions.

If this property is not explicitly defined, it behaves as though it were set to true.

On Android and iOS, the returned default value is undefined, but behave as if the value is true.


# autofillType

Availability
6.3.0
6.3.0
9.2.0
autofillType :String

Sets the autofill type for the text area.

This sets the hint or content type to aid the autofill feature of iOS and Android to function.

Default: undefined


Availability
3.0.0
0.8
9.2.0
autoLink :Number

Automatically convert text to clickable links.

iOS supports an additional autolink type, AUTOLINK_CALENDAR.

Multiple autolink values can be combined with a bitwise OR. For example:

textArea.autoLink = Ti.UI.AUTOLINK_MAP_ADDRESSES|Ti.UI.AUTOLINK_PHONE_NUMBERS;

Prior to Release 3.0, this field used platform-specific constants. These are now deprecated in favor of the AUTOLINK constants.

On Android, the LINKIFY legacy constants are defined in Titanium.UI.Android.

On iOS, the AUTODETECT legacy constants are defined in Titanium.UI.iOS.

Default: Titanium.UI.AUTOLINK_NONE


# clearOnEdit

Availability
0.8
clearOnEdit :Boolean

Determines whether the value of this text area should be cleared when it is focused.

Default: false


# color

Availability
0.8
0.8
9.2.0
color :String | Titanium.UI.Color

Color of the text in this text area, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.


# editable

Availability
0.8
0.8
9.2.0
editable :Boolean

Determines whether this field can be edited.

Default: true


# ellipsize

Availability
0.8
ellipsize :Boolean

Determines whether an ellipsis (...) should be used to indicate truncated text.

Default: false


# enableCopy

Availability
10.0.1
10.0.1
10.0.1
enableCopy :Boolean

Determines if user can copy or cut text from the text area.

When set false, the "copy" and "cut" options will not appear in the context menu. The Command+C and Command+X keyboard shortcuts will be ignored as well.

Default: true


# enableReturnKey

Availability
0.8
0.8
9.2.0
enableReturnKey :Boolean

Determines whether the return key is enabled automatically when there is text in this text area.

If true, the return key is disabled when this text area is empty, and automatically enabled as soon as the user types any text in the area.

Default: false


# focused READONLY

Availability
9.1.0
9.1.0
9.2.0
focused :Boolean

Determines whether this TextArea has focus.

Default: false


# font

Availability
0.8
0.8
9.2.0
font :Font

Font to use for text.


# fullscreen

Availability
6.1.0
fullscreen :Boolean

Leave some space above the keyboard in landscape mode or not.

Switch between a fullscreen keyboard in landscape mode (default) or a non-fullscreen keyboard which will leave some space to display UI elements.

Default: true


Availability
3.2.0
9.2.0
handleLinks :Boolean

Specifies if the text area should allow user interaction with the given URL in the given range of text.

When the text is specified using an attributed string and the text has an attribute of type ATTRIBUTE_LINK, this property controls if the system should handle that link automatically.

Default: false


# hintText

Availability
0.8
hintText :String

Hint text to display when the field is empty.

Hint text is hidden when the user enters text into this text area.

Use the backslash and letter n line feed character combination, ie \n, to force a new line.

Use unicode characters, such as those included in (but not limited to) the Unicode List of Useful Symbols section of wikipedia, to insert special characters and symbols.

Default: No hint text.


# hintTextColor

Availability
4.1.0
hintTextColor :String

Color of hint text that displays when field is empty.

Hint text color in Android is determined by the theme of the application. By default, a Titanium app uses a Dark theme. When you create the background to be white, the hint text color would also be white, hence not visible to the user. To change this, you can edit the "tiapp.xml" file with another theme. Example as follows:

<android xmlns:android="http://schemas.android.com/apk/res/android">
    <manifest>
        <application android:theme="@style/Theme.MaterialComponents.Light.Bridge"/>
    </manifest>
</android>

Another way to change the hint text color is to use this property and specify a color.

This has no effect when used with hintType Ti.UI.HINT_TYPE_ANIMATED. Instead a theme must be used that defines the android:textColorHint attribute.

Default: Default Android theme's hint text color.


# hintType

Availability
7.0.0
hintType :Number

Hint type to display on the text field.

Setting this to HINT_TYPE_ANIMATED will use the animated TextInputLayout on Android.

This API can be assigned the following constants:

Default: Titanium.UI.HINT_TYPE_STATIC


# keyboardAppearance

Availability
0.8
9.2.0
keyboardAppearance :Number

Determines the appearance of the keyboard displayed when this text area is focused.

Default: Titanium.UI.KEYBOARD_APPEARANCE_DEFAULT


# keyboardToolbar

Availability
0.8
9.2.0

Array of toolbar button objects or a Titanium.UI.iOS.Toolbar to be used when the keyboard is displayed.

As of Release 2.0, because iOS disallows a view (including toolbar buttons) to be in two places at once, developers desiring textAreas or Titanium.UI.TextField to share a toolbar can instead use a single Titanium.UI.iOS.Toolbar instead of having arrays sharing toolbar buttons.


# keyboardToolbarColor

Availability
0.8
9.2.0
keyboardToolbarColor :String | Titanium.UI.Color

Color of the keyboard toolbar if keyboardToolbar is an array, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.


# keyboardToolbarHeight

Availability
0.8
9.2.0
keyboardToolbarHeight :Number

Height of the keyboard toolbar if keyboardToolbar is an array.


# keyboardType

Availability
0.8
0.8
9.2.0
keyboardType :Number

Keyboard type to display when this text area is focused.

When asking for a specific kind of user input, such as a phone number or email address, you should always specify the appropriate keyboard type.

Default: Titanium.UI.KEYBOARD_DEFAULT


# lines

Availability
7.5.0
lines :Number

Number of lines tall the text area height will be, if set.

Sets the height of the text area by line height. Set to -1 to respect the view's height property instead.

Default: 1


# maxLength

Availability
3.0.0
3.0.0
9.2.0
maxLength :Number

Maximum length of text field input.

Any attempt to input text beyond this length (including pasting a string larger than maxLength) will not edit the field's contents. A value of -1 indicates unlimited length.

Default: -1


# maxLines

Availability
7.5.0
maxLines :Number

Maximum line count of text field input.

Sets the maximum of lines that the field will be extended to when pressing Return.

Default: -1


# padding

Availability
6.0.0
6.1.0
9.2.0
padding :Padding

Sets the left and right padding of this TextArea. The text will always be vertically centered.


# scrollable

Availability
0.8
9.2.0
scrollable :Boolean

Determines whether this text area can be scrolled.

Default: true


# scrollsToTop

Availability
2.1.2
9.2.0
scrollsToTop :Boolean

Controls whether the scroll-to-top gesture is effective.

The scroll-to-top gesture is a tap on the status bar; The default value of this property is true. This gesture works when you have a single visible text area. If there are multiple table views, web views, text areas, and/or scroll views visible, you will need to disable (set to false) on the above views you DON'T want this behaviour on. The remaining view will then respond to scroll-to-top gesture.

Default: true


# selection READONLY

Availability
3.3.0
3.3.0
9.2.0

Returns the currently selected text of the text area.

This property is useful to track the current cursor position of the text area. On iOS this property can be used in lieu of the selected event.

This method will return null on android and undefined on iOS if the view has not yet been attached to the window.


# showUndoRedoActions

Availability
5.0.0
9.2.0
showUndoRedoActions :Boolean

Determinates if the undo and redo buttons on the left side of the keyboard should be displayed or not. Only valid on iOS9 and above. This property can only be set upon creation.

Default: true


# suppressReturn

Availability
0.8
9.2.0
suppressReturn :Boolean

Determines if the return key should be suppressed during text entry.


# textAlign

Availability
0.8
0.8
9.2.0
textAlign :String | Number

Text alignment within this text area.

This has no effect on hintText when hintType is Ti.UI.HINT_TYPE_ANIMATED.

Default: Titanium.UI.TEXT_ALIGNMENT_LEFT


# value

Availability
0.8
0.8
9.2.0
value :String

Value of this text area, which may be set programmatically and modified by the user.

Use the backslash and letter n line feed character combination, ie \n, to force a new line.

Use unicode characters, such as those included in (but not limited to) the Unicode List of Useful Symbols section of wikipedia, to insert special characters and symbols.


# verticalAlign

Availability
0.8
verticalAlign :Number | String

Vertical alignment within this text area.

Default: Titanium.UI.TEXT_VERTICAL_ALIGNMENT_TOP

# Methods

# blur

Availability
0.8
0.8
9.2.0
blur() void

Forces this text area to lose focus.

Returns

Type
void

# focus

Availability
0.8
0.8
9.2.0
focus() void

Forces this text area to gain focus.

Returns

Type
void

# hasText

Availability
2.1.0
2.1.0
9.2.0
hasText() Boolean

Returns true if this text area contains text.

Returns

True if this text area contains text.

Type
Boolean

# setSelection

Availability
3.0.0
3.0.0
9.2.0
setSelection(start, end) void

Selects the text in range (start, end).

Selects the text in range (start, end). If start equals end, no text will be selected, and the cursor will move to the start position. End is not inclusive, meaning setSelection(0,0) will not select the first character, but will move the cursor to the position before the first character.

On iOS, soft keyboard would show when text is selected.

Parameters

Name Type Description
start Number

Start index for selection. Value ranges from 0 to the text's length.

end Number

End index for selection, not inclusive. Value ranges from 0 to the text's length.

Returns

Type
void

# Events

# focus

Availability
0.9
4.1.0

Fired when this text area gains focus.

This event only fires when using the trackball to navigate.

Properties

Name Type Description
value String

Value of this text area.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# blur

Availability
0.8
0.8
9.2.0

Fired when this text area loses focus.

Properties

Name Type Description
value String

Value of this text area.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


Availability
3.2.0
9.2.0

Fired when user interacts with a URL in the text area. See handleLinks.

The URL is set using the ATTRIBUTE_LINK property on the attributedString. This event is fired even in handleLinks is set to false. Only valid on iOS7 and above.

Properties

Name Type Description
url String

The URL that is associated with this event.

range Array

An array of two numbers [location, length] describing the character range of the text associated with this URL.

bubbles Boolean

This is false. This event does not bubble.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# change

Availability
0.8
0.8
9.2.0
4.1.0

Fired when this text area value changes.

Properties

Name Type Description
value String

New value of this text area.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# return

Availability
0.8
0.8
9.2.0
4.1.0

Fired when the return key is pressed on the keyboard.

Properties

Name Type Description
value String

Value of this text area.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.


# selected

Availability
0.8
9.2.0
4.1.0

Fired when text in this text area is selected.

Properties

Name Type Description
range textAreaSelectedParams

Dictionary that describes the position and length of the selected text.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

source Object

Source object that fired the event.

type String

Name of the event fired.