# Titanium.UI.TextField

> A single line text field.

- Source: https://titaniumsdk.com/docs/sdk/13.1.0/Titanium.UI.TextField
- Titanium SDK version: 13.1.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](./textfield_android.png) | ![iOS](./textfield_ios.png) |

Use the [Titanium.UI.createTextField](https://titaniumsdk.com/docs/sdk/Titanium.UI.md#createTextField) method or **`<TextField>`** Alloy element to create a text field.

#### `click` event in iOS

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

## Example: Basic Text Field

Create a simple text field with green text color.

``` js
var win = Ti.UI.createWindow();

var textField = Ti.UI.createTextField({
  backgroundColor: '#fafafa',
  color: 'green',
  width: 250,
  height: 40
});

win.add(textField);
win.open();
```

## Example: 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.Toolbar>
for more information.

This code excerpt creates a text field with a toolbar:

``` js
var win = Ti.UI.createWindow();

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

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 textfield = Ti.UI.createTextField({
    borderStyle: Ti.UI.INPUT_BORDERSTYLE_BEZEL,
    hintText: 'Focus to see keyboard with toolbar',
    keyboardToolbar : [cancel, flexSpace, camera, flexSpace, send],
    keyboardToolbarColor: '#999',
    keyboardToolbarHeight: 40,
    top: 10,
    width: 300,
    height: 35
});

win.add(textField);
win.open();
```

## Example: Alloy XML Markup

Previous basic text field with green text color example using Alloy.

Alternatively, define the properties using the TSS file.

``` xml
<Alloy>
    <Window id="win" backgroundColor="white">
        <TextField class="myTextField" color="green" width="250" height="45" />
    </Window>
</Alloy>
```

## Example: Alloy Custom Keyboard Toolbar (iOS)

Previous custom keyboard toolbar example as an Alloy view.  Use the `<KeyboardToolbar>` XML
element to set the `keyboardToolbar` property.

You can also declare the `leftButton` and `rightButton` properties in XML markup as the
`<LeftButton>` and `<RightButton>` XML elements.

``` xml
<Alloy>
    <Window fullscreen="true" backgroundColor="white">
        <TextField
            platform="ios"
            borderStyle="Ti.UI.INPUT_BORDERSTYLE_BEZEL"
            keyboardToolbarColor="#999"
            keyboardToolbarHeight="40"
            top="10"
            height="35"
            width="300"
            value="Focus to see keyboard with toolbar">

            <!-- Sets the keyboardToolbar property -->
            <KeyboardToolbar>
                <Toolbar>
                    <Items>
                        <Button systemButton="CANCEL" />
                        <FlexSpace/>
                        <Button systemButton="CAMERA" />
                        <FlexSpace/>
                        <Button style="DONE">Send</Button>
                    </Items>
                </Toolbar>
            </KeyboardToolbar>
        </TextField>
    </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 textField. If set, avoid setting common attributes
in textField, 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:

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

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

TextField attributed string.

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

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

``` xml
<Alloy>
  <Window>
      <TextField>
        <AttributedString>
            Alloy is great!
        </AttributedString>
      </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]
    }
  ]
}
```

### 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 field.

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 iOS, the returned default value is `false`, and on Android, the returned
default value is undefined, but all behave as if the value is `true`.

### autofillType

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

Sets the autofill type for the text field.

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
- Since: Titanium SDK 3.0.0
- Default: `undefined`

Automatically convert text to clickable links.

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

``` js
textField.autoLink = Ti.UI.AUTOLINK_MAP_ADDRESSES | Ti.UI.AUTOLINK_PHONE_NUMBERS;
```

The Android-specific `LINKIFY` legacy constants are defined in [Titanium.UI.Android](https://titaniumsdk.com/docs/sdk/Titanium.UI.Android.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, iPhone, iPad, macOS
- Since: Titanium SDK Android 10.0.0, iPhone 0.8.0, iPad 0.8.0, macOS 9.2.0
- Default: `<Titanium.UI.INPUT_BORDERSTYLE_NONE> (on iOS),
<Titanium.UI.INPUT_BORDERSTYLE_FILLED> (on Android)
`

Border style for the field.

On Android, this is a creation-only property and cannot be changed dynamically.

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`

### clearButtonMode

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `Titanium.UI.INPUT_BUTTONMODE_NEVER`

Determines when the clear button is displayed.

Accepts: `Titanium.UI.INPUT_BUTTONMODE_ALWAYS`, `Titanium.UI.INPUT_BUTTONMODE_NEVER`, `Titanium.UI.INPUT_BUTTONMODE_ONBLUR`, `Titanium.UI.INPUT_BUTTONMODE_ONFOCUS`

### clearOnEdit

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

Determines whether the value of this text field 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 field, 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 field.

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.

If [Titanium.UI.TextField.passwordMask](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextField.md#passwordMask) is set `true`, then copy support is always disabled,
even if you set this property `true`.

### 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
field.

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

On Android, if `true`, `return` event will not fire. Clicking on the return key will do nothing, but
the key itself won't be **disabled**.

### focused

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

Determines whether this TextField 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.

### hintText

- Type: String
- Platforms: Android, iPhone, iPad, macOS
- 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 field.

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 | Titanium.UI.Color
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK iPhone 5.4.0, iPad 5.4.0, Android 4.1.0
- Default: `The platform's default hint text color.`

Hint text color to display when the field is empty.

Sets the color of the [Titanium.UI.TextField.hintText](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextField.md#hintText). Please not that this can be overridden
by the [Titanium.UI.TextField.attributedHintText](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextField.md#attributedHintText) which provides an advanced configuration to
style hint texts.

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.

**Android Note**:
The 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.

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

### inputType

- Type: Array<Number>
- Platforms: Android
- Since: Titanium SDK 5.2.0
- Default: `Empty array. If not defined, default is Keyboard type specified by <Titanium.UI.TextField.keyboardType>.`

Input type to accept in the text field. Also influences the Keyboard type to display.

When asking for a specific kind of user input, such as a phone number or email
address, you should always specify the input type that is accepted. This overrides
any changes to the keyboard done by the property [Titanium.UI.TextField.keyboardType](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextField.md#keyboardType).

Accepts: `Titanium.UI.INPUT_TYPE_CLASS_NUMBER`, `Titanium.UI.INPUT_TYPE_CLASS_TEXT`

### keyboardAppearance

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

Determines the appearance of the keyboard displayed when this field 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.

In Alloy, you can use a `<KeyboardToolbar>` element inside a `<TextField>` element to create
a `KeyboardToolbar`.

``` xml
<Alloy>
    <TextField id="textfield" platform="ios" hintText="Tap here...">
        <!-- Nested properties -->
        <KeyboardToolbar >
            <Toolbar >
                <Items >
                    <Button>button 1</Button>
                    <FlexSpace />
                    <Button>button 2</Button>
                </Items>
            </Toolbar>
        </KeyboardToolbar>
    </TextField>
</Alloy>
```

### 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_TYPE_DEFAULT>`

Keyboard type to display when this text field 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_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`

### leftButton

- Type: Titanium.UI.View
- Platforms: iPhone, iPad, macOS

Left button view to display in the `TextField`.

Set the `width` and `height` properties of the button or else it does not display in the
text field.

Using an object other than a [Button](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md) may have unpredictable results.

In Alloy you can use a `<LeftButton>` element inside the `<TextField>` element.

``` xml
<Alloy>
    <Window>
        <!-- iOS TextField properties -->
        <TextField id="textfield" platform="ios">
            <LeftButton>
                <Button onClick="sayHi">Say Hi</Button>
            </LeftButton>
            <RightButton>
                <Button onClick="doAlert">Do Alert</Button>
            </RightButton>
        </TextField>
    </Window>
</Alloy>
```

### leftButtonMode

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

Determines when to display the left button view.

Accepts: `Titanium.UI.INPUT_BUTTONMODE_ALWAYS`, `Titanium.UI.INPUT_BUTTONMODE_NEVER`, `Titanium.UI.INPUT_BUTTONMODE_ONBLUR`, `Titanium.UI.INPUT_BUTTONMODE_ONFOCUS`

### leftButtonPadding

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

Padding between the left button and the edge of the field.

### maxLength

- Type: Number
- Platforms: Android, iPhone
- 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.

### minimumFontSize

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

Minimum size of the font when the font is sized based on the contents.  Enables font
scaling to fit.

### padding

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

Sets the padding of this text field.

### passwordMask

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

Obscure the input text from the user.

Set to `true` to hide entered characters.

Note: on iOS, `passwordMask` *must* be specified when this text field is created.

### passwordRules

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

Set password rules that should be used for this text field.

This property is used to communicate requirements for passwords for your service
to ensure iOS can generate compatible passwords for users. It only works when [Titanium.UI.TextField.passwordMask](https://titaniumsdk.com/docs/sdk/Titanium.UI.TextField.md#passwordMask)
is `true`. You do not need to use this property if the passwords that iOS generates are already
compatible with your service. You can learn more about the purpose of and syntax for these rules
on the [Password Rules documentation guide](https://developer.apple.com/documentation/security/password_autofill/customizing_password_autofill_rules).

### returnKeyType

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

Specifies the text to display on the keyboard `Return` key when this field 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`

### rightButton

- Type: Titanium.UI.View
- Platforms: iPhone, iPad, macOS

Right button view.

Set the `width` and `height` properties of the button or else it does not display in the
text field.

Using an object other than a [Button](https://titaniumsdk.com/docs/sdk/Titanium.UI.Button.md) may have unpredictable results.
In Alloy you can use a `<RightButton>` element inside the `<TextField>` element.

``` xml
<Alloy>
    <Window>
        <!-- iOS TextField properties -->
        <TextField id="textfield" platform="ios">
            <LeftButton>
                <Button onClick="sayHi">Say Hi</Button>
            </LeftButton>
            <RightButton>
                <Button onClick="doAlert">Do Alert</Button>
            </RightButton>
        </TextField>
    </Window>
</Alloy>
```

The `sayHi` and `doAlert` methods are defined in the Alloy controller.

### rightButtonMode

- Type: Number
- Platforms: iPhone, iPad, macOS
- Default: `Titanium.UI.INPUT_BUTTONMODE_NEVER`

Determines when to display the right button view.

Accepts: `Titanium.UI.INPUT_BUTTONMODE_ALWAYS`, `Titanium.UI.INPUT_BUTTONMODE_NEVER`, `Titanium.UI.INPUT_BUTTONMODE_ONBLUR`, `Titanium.UI.INPUT_BUTTONMODE_ONFOCUS`

### rightButtonPadding

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

Padding between the right button and the edge of the field.

### selection

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

Returns the currently selected text of the text field.

This property is useful to track the current cursor position of the text field. On iOS this property
can only be used when the text field has focus. Accessing this property when text field does not have
focus will return an undefined value.

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.

### suppressReturn

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

Determines whether the return key should be suppressed during entry.

### textAlign

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

Text alignment within this text field.

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 field, 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, iPhone, iPad, macOS
- Default: `<Titanium.UI.TEXT_VERTICAL_ALIGNMENT_CENTER>`

Vertical alignment within this text field.

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 the field to lose focus.

### focus

- Platforms: Android, iPhone, iPad, macOS

Forces the field to gain focus.

### hasText

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

Returns `true` if this text field contains text.

Returns: Boolean - True if this text field 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 the field loses focus.

Event properties:

- `value` (String): Value of the field.

### change

- Platforms: Android, iPhone, iPad, macOS

Fired when the field value changes.

Event properties:

- `value` (String): New value of the field.

### empty

- Platforms: Android
- Since: Titanium SDK 12.4.0

Fired when the field is empty and you press backspace key again.

Event properties:

- `keyCode` (Number): Key code of the key.

### focus

- Platforms: Android, iPhone, iPad, macOS

Fired when the field gains focus.

Event properties:

- `value` (String): Value of the field.

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

## Inherited members

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

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/13.1.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`
- [Titanium.UI.View](https://titaniumsdk.com/docs/sdk/13.1.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`, `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`.