# Titanium.UI.TextArea

> A multiline text field that supports editing and scrolling.

- Source: https://titaniumsdk.com/docs/sdk/13.2.0/Titanium.UI.TextArea
- Titanium SDK version: 13.2.0
- Kind: view
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 0.8
- Extends: Titanium.UI.View
- Inheritance: Titanium.UI.View > Titanium.Proxy

| Android | iOS |
| ------- | --- |
| ![Android](./textarea_android.png) | ![iOS](./textarea_ios.png) |

Use the [Titanium.UI.createTextArea](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createTextArea) method or **&lt;TextArea&gt;** 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.

## Example: Basic Text Area with Customizations

This example creates a highly customized text area.

``` js
var win = Ti.UI.createWindow();
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();
```

## Example: 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:

``` js
var send = Ti.UI.createButton({
    style : Ti.UI.BUTTON_STYLE_OPTION_POSITIVE,
    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
});
```

## Example: Alloy XML Markup

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

``` xml
<Alloy>
    <Window id="win">
        <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

### attributedHintText

- Type: Titanium.UI.AttributedString
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.6.0, iPhone 3.2.0, iPad 3.2.0

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.

For Alloy, you can use an `<AttributedHintText>`
element inside a `<TextField>` element and set the text property as node text:

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

Then set attributes in the TSS file:

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

Since 13.2.0 you can also use the AttributedString object without `Titanium.UI.createAttributedString()`:
``` js
var text =  'Bacon ipsum dolor Titanium SDK rocks! sit amet fatback leberkas salami sausage tongue strip steak.';
var label = Titanium.UI.createLabel({
    attributedString: {
        text: text,
        attributes: [
            {
                type: Titanium.UI.ATTRIBUTE_UNDERLINES_STYLE,
                value: Ti.UI.ATTRIBUTE_UNDERLINE_STYLE_SINGLE,
                range: [text.indexOf('Titanium'), ('Titanium').length]
            },
            {
                type: Titanium.UI.ATTRIBUTE_BACKGROUND_COLOR,
                value: "red",
                range: [text.indexOf('Titanium'), ('Titanium').length]
            }
        ]
    }
});
```

### attributedString

- Type: Titanium.UI.AttributedString
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 3.6.0, iPhone 3.2.0, iPad 3.2.0

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.

For Alloy, you can use an `<AttributedString>`
element inside a `<TextArea>` element and set the text property as node text:

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

Then set attributes in the TSS file:

``` js
"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

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Default: `<Titanium.UI.TEXT_AUTOCAPITALIZATION_NONE>`

Determines how text is capitalized during typing.

Accepts: `Titanium.UI.TEXT_AUTOCAPITALIZATION_ALL`, `Titanium.UI.TEXT_AUTOCAPITALIZATION_NONE`, `Titanium.UI.TEXT_AUTOCAPITALIZATION_SENTENCES`, `Titanium.UI.TEXT_AUTOCAPITALIZATION_WORDS`

### autocorrect

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS

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

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 6.3.0
- Default: `undefined`

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.

Accepts: `Titanium.UI.AUTOFILL_TYPE_ADDRESS`, `Titanium.UI.AUTOFILL_TYPE_ADDRESS_CITY`, `Titanium.UI.AUTOFILL_TYPE_ADDRESS_CITY_STATE`, `Titanium.UI.AUTOFILL_TYPE_ADDRESS_LINE1`, `Titanium.UI.AUTOFILL_TYPE_ADDRESS_LINE2`, `Titanium.UI.AUTOFILL_TYPE_ADDRESS_STATE`, `Titanium.UI.AUTOFILL_TYPE_CARD_EXPIRATION_DATE`, `Titanium.UI.AUTOFILL_TYPE_CARD_EXPIRATION_DAY`, `Titanium.UI.AUTOFILL_TYPE_CARD_EXPIRATION_MONTH`, `Titanium.UI.AUTOFILL_TYPE_CARD_EXPIRATION_YEAR`, `Titanium.UI.AUTOFILL_TYPE_CARD_NUMBER`, `Titanium.UI.AUTOFILL_TYPE_CARD_SECURITY_CODE`, `Titanium.UI.AUTOFILL_TYPE_COUNTRY_NAME`, `Titanium.UI.AUTOFILL_TYPE_EMAIL`, `Titanium.UI.AUTOFILL_TYPE_FAMILY_NAME`, `Titanium.UI.AUTOFILL_TYPE_GIVEN_NAME`, `Titanium.UI.AUTOFILL_TYPE_JOB_TITLE`, `Titanium.UI.AUTOFILL_TYPE_LOCATION`, `Titanium.UI.AUTOFILL_TYPE_MIDDLE_NAME`, `Titanium.UI.AUTOFILL_TYPE_NAME`, `Titanium.UI.AUTOFILL_TYPE_NAME_PREFIX`, `Titanium.UI.AUTOFILL_TYPE_NAME_SUFFIX`, `Titanium.UI.AUTOFILL_TYPE_NEW_PASSWORD`, `Titanium.UI.AUTOFILL_TYPE_NICKNAME`, `Titanium.UI.AUTOFILL_TYPE_ONE_TIME_CODE`, `Titanium.UI.AUTOFILL_TYPE_ORGANIZATION_NAME`, `Titanium.UI.AUTOFILL_TYPE_PASSWORD`, `Titanium.UI.AUTOFILL_TYPE_PHONE`, `Titanium.UI.AUTOFILL_TYPE_POSTAL_CODE`, `Titanium.UI.AUTOFILL_TYPE_SUBLOCALITY`, `Titanium.UI.AUTOFILL_TYPE_URL`, `Titanium.UI.AUTOFILL_TYPE_USERNAME`

### autoLink

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.0.0
- Default: `<Titanium.UI.AUTOLINK_NONE>`

Automatically convert text to clickable links.

iOS supports an additional autolink type, [AUTOLINK_CALENDAR](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#AUTOLINK_CALENDAR).

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

``` js
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](https://titaniumsdk.com/docs/sdk/Titanium.UI.Android.md).

On iOS, the `AUTODETECT` legacy constants are defined in [Titanium.UI.iOS](https://titaniumsdk.com/docs/sdk/Titanium.UI.iOS.md).

Accepts: `Titanium.UI.AUTOLINK_ALL`, `Titanium.UI.AUTOLINK_CALENDAR`, `Titanium.UI.AUTOLINK_EMAIL_ADDRESSES`, `Titanium.UI.AUTOLINK_FLIGHT_NUMBER`, `Titanium.UI.AUTOLINK_LOOKUP_SUGGESTION`, `Titanium.UI.AUTOLINK_MAP_ADDRESSES`, `Titanium.UI.AUTOLINK_MONEY`, `Titanium.UI.AUTOLINK_NONE`, `Titanium.UI.AUTOLINK_PHONE_NUMBERS`, `Titanium.UI.AUTOLINK_PHYSICAL_VALUE`, `Titanium.UI.AUTOLINK_SHIPMENT_TRACKING_NUMBER`, `Titanium.UI.AUTOLINK_URLS`

### borderStyle

- Type: Number
- Platforms: Android
- Since: Titanium SDK 10.0.0
- Default: `<Titanium.UI.INPUT_BORDERSTYLE_FILLED>`

Border style for the text area.

Accepts: `Titanium.UI.INPUT_BORDERSTYLE_BEZEL`, `Titanium.UI.INPUT_BORDERSTYLE_FILLED`, `Titanium.UI.INPUT_BORDERSTYLE_LINE`, `Titanium.UI.INPUT_BORDERSTYLE_NONE`, `Titanium.UI.INPUT_BORDERSTYLE_ROUNDED`, `Titanium.UI.INPUT_BORDERSTYLE_UNDERLINED`

### clearOnEdit

- Type: Boolean
- Platforms: Android
- Default: `false`

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

### color

- Type: String | Titanium.UI.Color
- Platforms: Android, iPhone, iPad, macOS

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](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

### editable

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Default: `true`

Determines whether this field can be edited.

### ellipsize

- Type: Boolean
- Platforms: Android
- Default: `false`

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

### enableCopy

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 10.0.1
- Default: `true`

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.

### enableReturnKey

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Default: `false`

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.

### focused

- Type: Boolean
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 9.1.0
- Permission: read-only
- Default: `false`

Determines whether this TextArea has focus.

### font

- Type: Font
- Platforms: Android, iPhone, iPad, macOS

Font to use for text.

### fullscreen

- Type: Boolean
- Platforms: Android
- Since: Titanium SDK 6.1.0
- Default: `true`

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.

### handleLinks

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.2.0
- Default: `false`

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](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#ATTRIBUTE_LINK),
this property controls if the system should handle that link automatically.

### hintText

- Type: String
- Platforms: Android
- Default: `No hint text.`

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](http://en.wikibooks.org/w/index.php?title=Unicode/List_of_useful_symbols)
section of wikipedia, to insert special characters and symbols.

### hintTextColor

- Type: String
- Platforms: Android
- Since: Titanium SDK 4.1.0
- Default: `Default Android theme's hint text color.`

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:

``` xml
<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.

### hinttextid

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 6.2.0

Key identifying a string from the locale file to use for the
[hintText](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextArea.md#hintText) property.

Only one of `hintText` or `hinttextid` should be specified.

### hintType

- Type: Number
- Platforms: Android
- Since: Titanium SDK 7.0.0
- Default: `<Titanium.UI.HINT_TYPE_STATIC>`

Hint type to display on the text field.

Setting this to [Titanium.UI.HINT_TYPE_ANIMATED](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#HINT_TYPE_ANIMATED) will use the animated TextInputLayout on Android.

Accepts: `Titanium.UI.HINT_TYPE_ANIMATED`, `Titanium.UI.HINT_TYPE_STATIC`

### html

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 12.7.0

Pass a HTML-based string and it will be formatted accordingly.

Note that complex HTML structures like images are not supported.
Use a [Titanium.UI.WebView](https://titaniumsdk.com/docs/sdk/Titanium.UI.WebView.md) for those cases.

### keyboardAppearance

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `<Titanium.UI.KEYBOARD_APPEARANCE_DEFAULT>`

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

Accepts: `Titanium.UI.KEYBOARD_APPEARANCE_DARK`, `Titanium.UI.KEYBOARD_APPEARANCE_DEFAULT`, `Titanium.UI.KEYBOARD_APPEARANCE_LIGHT`

### keyboardToolbar

- Type: Array<Titanium.UI.View> | Titanium.UI.Toolbar
- Platforms: iPhone, iPad, macOS

Array of toolbar button objects or a [toolbar](https://titaniumsdk.com/docs/sdk/Titanium.UI.Toolbar.md) 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 [textFields](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextField.md) to share a toolbar
can instead use a single [toolbar](https://titaniumsdk.com/docs/sdk/Titanium.UI.Toolbar.md) instead of having arrays sharing
toolbar buttons.

### keyboardToolbarColor

- Type: String | Titanium.UI.Color
- Platforms: iPhone, iPad, macOS

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](https://titaniumsdk.com/docs/sdk/Titanium.UI.md).

### keyboardToolbarHeight

- Type: Number
- Platforms: iPhone, iPad, macOS

Height of the keyboard toolbar if keyboardToolbar is an array.

### keyboardType

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Default: `<Titanium.UI.KEYBOARD_DEFAULT>`

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.

Accepts: `Titanium.UI.KEYBOARD_APPEARANCE_DARK`, `Titanium.UI.KEYBOARD_APPEARANCE_DEFAULT`, `Titanium.UI.KEYBOARD_APPEARANCE_LIGHT`, `Titanium.UI.KEYBOARD_TYPE_ASCII`, `Titanium.UI.KEYBOARD_TYPE_DECIMAL_PAD`, `Titanium.UI.KEYBOARD_TYPE_DEFAULT`, `Titanium.UI.KEYBOARD_TYPE_EMAIL`, `Titanium.UI.KEYBOARD_TYPE_NAMEPHONE_PAD`, `Titanium.UI.KEYBOARD_TYPE_NUMBERS_PUNCTUATION`, `Titanium.UI.KEYBOARD_TYPE_NUMBER_PAD`, `Titanium.UI.KEYBOARD_TYPE_PHONE_PAD`, `Titanium.UI.KEYBOARD_TYPE_TWITTER`, `Titanium.UI.KEYBOARD_TYPE_URL`, `Titanium.UI.KEYBOARD_TYPE_WEBSEARCH`

### lines

- Type: Number
- Platforms: Android
- Since: Titanium SDK 7.5.0
- Default: `1`

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.

### maxLength

- Type: Number
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.0.0
- Default: `-1`

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.

### maxLines

- Type: Number
- Platforms: Android
- Since: Titanium SDK 7.5.0
- Default: `-1`

Maximum line count of text field input.

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

### padding

- Type: Padding
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK Android 6.0.0, iPhone 6.1.0, iPad 6.1.0

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

### returnKeyType

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `<Titanium.UI.RETURNKEY_DEFAULT>`

Specifies the text to display on the keyboard `Return` key when this text area is focused.

Accepts: `Titanium.UI.RETURNKEY_CONTINUE`, `Titanium.UI.RETURNKEY_DEFAULT`, `Titanium.UI.RETURNKEY_DONE`, `Titanium.UI.RETURNKEY_EMERGENCY_CALL`, `Titanium.UI.RETURNKEY_GO`, `Titanium.UI.RETURNKEY_GOOGLE`, `Titanium.UI.RETURNKEY_JOIN`, `Titanium.UI.RETURNKEY_NEXT`, `Titanium.UI.RETURNKEY_ROUTE`, `Titanium.UI.RETURNKEY_SEARCH`, `Titanium.UI.RETURNKEY_SEND`, `Titanium.UI.RETURNKEY_YAHOO`

### scrollable

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Default: `true`

Determines whether this text area can be scrolled.

### scrollsToTop

- Type: Boolean
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 2.1.2
- Default: `true`

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.

### selection

- Type: textAreaSelectedParams
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.3.0
- Permission: read-only

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](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextArea.md#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

- Type: Boolean
- Platforms: iPad, macOS
- Since: Titanium SDK 5.0.0
- Default: `true`

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

### suppressReturn

- Type: Boolean
- Platforms: iPhone, iPad, macOS

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

### textAlign

- Type: String | Number
- Platforms: Android, iPhone, iPad, macOS
- Default: `<Titanium.UI.TEXT_ALIGNMENT_LEFT>`

Text alignment within this text area.

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

Accepts: `Titanium.UI.TEXT_ALIGNMENT_CENTER`, `Titanium.UI.TEXT_ALIGNMENT_JUSTIFY`, `Titanium.UI.TEXT_ALIGNMENT_LEFT`, `Titanium.UI.TEXT_ALIGNMENT_RIGHT`

### value

- Type: String
- Platforms: Android, iPhone, iPad, macOS

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](http://en.wikibooks.org/w/index.php?title=Unicode/List_of_useful_symbols)
section of wikipedia, to insert special characters and symbols.

### verticalAlign

- Type: Number | String
- Platforms: Android
- Default: `<Titanium.UI.TEXT_VERTICAL_ALIGNMENT_TOP>`

Vertical alignment within this text area.

Accepts: `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_BOTTOM`, `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_CENTER`, `Titanium.UI.TEXT_VERTICAL_ALIGNMENT_TOP`

## Methods

### blur

- Platforms: Android, iPhone, iPad, macOS

Forces this text area to lose focus.

### focus

- Platforms: Android, iPhone, iPad, macOS

Forces this text area to gain focus.

### hasText

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 2.1.0

Returns `true` if this text area contains text.

Returns: Boolean - True if this text area contains text.

### setSelection

- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK 3.0.0

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:

- `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.

## Events

### blur

- Platforms: Android, iPhone, iPad, macOS

Fired when this text area loses focus.

Event properties:

- `value` (String): Value of this text area.

### change

- Platforms: Android, iPhone, iPad, macOS

Fired when this text area value changes.

Event properties:

- `value` (String): New value of this text area.
- `contentHeight` (Number): Content height value of this text area

### focus

- Platforms: Android, iPhone, iPad, macOS

Fired when this text area gains focus.

Event properties:

- `value` (String): Value of this text area.

### link

- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 3.2.0

Fired when user interacts with a URL in the text area. See [handleLinks](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextArea.md#handleLinks).

The URL is set using the [ATTRIBUTE_LINK](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#ATTRIBUTE_LINK) property on the [attributedString](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextArea.md#attributedString).
This event is fired even in handleLinks is set to false. Only valid on iOS 7 and above.

Event properties:

- `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.

### return

- Platforms: Android, iPhone, iPad, macOS

Fired when the return key is pressed on the keyboard.

Event properties:

- `value` (String): Value of this text area.

### selected

- Platforms: iPhone, iPad, macOS

Fired when text in this text area is selected.

Event properties:

- `range` (textAreaSelectedParams): Dictionary that describes the position and length of the selected text.

## Inherited members

100 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.2.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`
- [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/13.2.0/Titanium.UI.View.md): `accessibilityDisableLongPress`, `accessibilityHidden`, `accessibilityHint`, `accessibilityLabel`, `accessibilityValue`, `anchorPoint`, `animate`, `animatedCenter`, `backgroundColor`, `backgroundDisabledColor`, `backgroundDisabledImage`, `backgroundFocusedColor`, `backgroundFocusedImage`, `backgroundGradient`, `backgroundImage`, `backgroundLeftCap`, `backgroundRepeat`, `backgroundSelectedColor`, `backgroundSelectedImage`, `backgroundTopCap`, `borderColor`, `borderRadius`, `borderWidth`, `bottom`, `center`, `clearMotionEffects`, `click`, `clipMode`, `convertPointToView`, `dblclick`, `doubletap`, `elevation`, `filterTouchesWhenObscured`, `focusable`, `getViewById`, `height`, `hiddenBehavior`, `hide`, `horizontalMotionEffect`, `horizontalWrap`, `id`, `insertAt`, `keepHardwareMode`, `keepScreenOn`, `keypressed`, `layout`, `left`, `longclick`, `longpress`, `opacity`, `overrideCurrentAnimation`, `pinch`, `postlayout`, `previewContext`, `pullBackgroundColor`, `rect`, `right`, `rotate`, `rotation`, `rotationX`, `rotationY`, `scaleX`, `scaleY`, `show`, `singletap`, `size`, `softKeyboardOnFocus`, `stopAnimation`, `swipe`, `tintColor`, `toImage`, `tooltip`, `top`, `touchEnabled`, `touchFeedback`, `touchFeedbackColor`, `touchcancel`, `touchend`, `touchmove`, `touchstart`, `transform`, `transitionName`, `translationX`, `translationY`, `translationZ`, `twofingertap`, `verticalMotionEffect`, `viewShadowColor`, `viewShadowOffset`, `viewShadowRadius`, `visible`, `width`, `zIndex`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.

