# Titanium.UI.TextField

A single line text field.

Availability
0.8
0.8
9.2.0
4.1.0

# Overview

Android iOS Windows
Android iOS Windows

Use the Titanium.UI.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.

# Examples

# Basic Text Field

Create a simple text field with green text color.

var win = Ti.UI.createWindow({
  backgroundColor: 'white'
});

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

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

# 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 field with a toolbar:

var win = Ti.UI.createWindow({
    backgroundColor: 'white'
});

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

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();

# Alloy XML Markup

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

Alternatively, define the properties using the TSS file.

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

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

<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

# appearance DEPRECATED

Availability
0.8
appearance :Number

DEPRECATED SINCE 5.2.0

Use keyboardAppearance instead.

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

<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

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:

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

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

Availability
6.3.0
6.3.0
9.2.0
autofillType :String

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.

Default: undefined


Availability
3.0.0
autoLink :Number

Automatically convert text to clickable links.

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

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

The Android-specific LINKIFY legacy constants are defined in Titanium.UI.Android.

Default: undefined


# borderStyle

Availability
10.0.0
0.8
9.2.0
borderStyle :Number

Border style for the field.

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

Default: Titanium.UI.INPUT_BORDERSTYLE_NONE> (on iOS), <Titanium.UI.INPUT_BORDERSTYLE_FILLED> (on Android)


# clearButtonMode

Availability
0.8
9.2.0
clearButtonMode :Number

Determines when the clear button is displayed.

Default: Titanium.UI.INPUT_BUTTONMODE_NEVER


# clearOnEdit

Availability
0.8
0.8
9.2.0
clearOnEdit :Boolean

Determines whether the value of this text field 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 field, 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 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 passwordMask is set true, then copy support is always disabled, even if you set this property true.

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

Default: false


# focused READONLY

Availability
9.1.0
9.1.0
9.2.0
focused :Boolean

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


# hintText

Availability
0.8
0.8
9.2.0
hintText :String

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 section of wikipedia, to insert special characters and symbols.

Default: No hint text.


# hintTextColor

Availability
4.1.0
5.4.0
9.2.0
hintTextColor :String | Titanium.UI.Color

Hint text color to display when the field is empty.

Sets the color of the hintText. Please not that this can be overriden by the 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:

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

Default: The platform's default hint text color.


# hinttextid

Availability
6.2.0
6.2.0
9.2.0
hinttextid :String

Key identifying a string from the locale file to use for the hintText property.

Only one of hintText or hinttextid should be specified.


# 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


# inputType

Availability
5.2.0
inputType :Array<Number>

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

This API can be assigned the following constants:

Default: Empty array. If not defined, default is Keyboard type specified by <Titanium.UI.TextField.keyboardType>.


# keyboardAppearance

Availability
0.8
9.2.0
keyboardAppearance :Number

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

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

<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

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

Default: Titanium.UI.KEYBOARD_TYPE_DEFAULT


# leftButton

Availability
0.8
9.2.0
leftButton :Titanium.UI.View

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 Titanium.UI.Button may have unpredictable results.

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

<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

Availability
0.8
9.2.0
leftButtonMode :Number

Determines when to display the left button view.

Default: Titanium.UI.INPUT_BUTTONMODE_NEVER


# leftButtonPadding

Availability
0.8
9.2.0
leftButtonPadding :Number

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


# maxLength

Availability
3.0.0
0.8
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


# minimumFontSize

Availability
0.8
9.2.0
minimumFontSize :Number

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


# padding

Availability
6.0.0
6.0.0
9.2.0
padding :TextFieldPadding

Sets the padding of this text field.


# paddingLeft DEPRECATED

Availability
0.8
paddingLeft :Number

DEPRECATED SINCE 6.1.0

Use padding for parity instead.

Left padding of this text field.


# paddingRight DEPRECATED

Availability
0.8
paddingRight :Number

DEPRECATED SINCE 6.1.0

Use padding for parity instead.

Right padding of this text field.


# passwordMask

Availability
0.8
0.8
9.2.0
passwordMask :Boolean

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.

Default: false


# passwordRules

Availability
7.5.0
9.2.0
passwordRules :String

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


# rightButton

Availability
0.8
9.2.0
rightButton :Titanium.UI.View

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 Titanium.UI.Button may have unpredictable results. In Alloy you can use a <RightButton> element inside the <TextField> element.

<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

Availability
0.8
9.2.0
rightButtonMode :Number

Determines when to display the right button view.

Default: Titanium.UI.INPUT_BUTTONMODE_NEVER


# rightButtonPadding

Availability
0.8
9.2.0
rightButtonPadding :Number

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


# selection READONLY

Availability
3.3.0
3.3.0
9.2.0

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

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.

Default: true


# suppressReturn

Availability
0.8
9.2.0
suppressReturn :Boolean

Determines whether the return key should be suppressed during entry.


# textAlign

Availability
0.8
0.8
9.2.0
textAlign :String | Number

Text alignment within this text field.

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 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 section of wikipedia, to insert special characters and symbols.


# verticalAlign

Availability
0.8
0.8
9.2.0
verticalAlign :Number | String

Vertical alignment within this text field.

Default: Titanium.UI.TEXT_VERTICAL_ALIGNMENT_CENTER

# Methods

# blur

Availability
0.8
0.8
9.2.0
blur() void

Forces the field to lose focus.

Returns

Type
void

# focus

Availability
0.8
0.8
9.2.0
focus() void

Forces the field to gain focus.

Returns

Type
void

# hasText

Availability
2.1.0
2.1.0
9.2.0
hasText() Boolean

Returns true if this text field contains text.

Returns

True if this text field 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 the field gains focus.

This event only fires when using the trackball to navigate.

Properties

Name Type Description
value String

Value of the field.

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

Properties

Name Type Description
value String

Value of the field.

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 the field value changes.

Properties

Name Type Description
value String

New value of the field.

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.