UITextField
UITextField represents a single-line text field. When the user taps it, the system keyboard slides up from the bottom of the screen and the typed text appears in the field. The app reads the field's content from text, reads the cursor position and the selected range from selectedRange, and learns through events when the content changes, the cursor moves, editing begins and ends, and the user presses Return.
A text field has only one line; pressing Return does not insert a line break. For multiline input, use UITextView.
A new text field has no border, no content, and no placeholder, so on screen there is no visible hint of where to tap. Set a border with borderStyle. A text field has no built-in length limit, format validation, or read-only mode: keyboardType only decides which keyboard appears and does not validate the content; to stop a change before it happens, listen for beforeinput.
When the keyboard appears, it covers the view controller's content; the size and position of the view controller's view do not change. To keep content clear of the keyboard, use the view's keyboardLayoutGuide, which is a UIKeyboardLayoutGuide.
A text field is a control: disabling it and the focus, input, return, and blur events come from UIControl. A control is in turn a view: position, size, and background color come from UIView.
Inheritance: EventTarget → NSObject → UIResponder → UIView → UIControl → UITextField
For how to build a usable text field, dismiss the keyboard, avoid being covered by the keyboard, and build forms, see the guide Building a text field.
Constructor
Creates a text field. It has no border, no content, and a size of 0.
Instance properties
Also inherits properties from UIControl and UIView. Commonly used inherited properties on a text field are isEnabled, isFirstResponder, tintColor, and keyboardLayoutGuide.
Content:
| Property | Description |
|---|---|
text | The content of the field |
placeholder | The hint shown when the field is empty |
attributedText | Styled content |
attributedPlaceholder | Styled placeholder |
isEditing read-only | Whether the user is editing |
hasText read-only | Whether there is content |
clearsOnBeginEditing | Whether existing content is cleared each time editing begins |
clearsOnInsertion | Whether inserting text replaces all the content |
allowsEditingTextAttributes | Whether the user can change the style of the text |
Selection:
| Property | Description |
|---|---|
selectedRange | The selected range, or the cursor position |
markedTextRange read-only | The stretch an input method is still composing, or null when not composing |
Keyboard:
| Property | Description |
|---|---|
keyboardType | Which keyboard appears |
returnKeyType | The label on the Return key |
keyboardAppearance | Whether the keyboard is light or dark |
enablesReturnKeyAutomatically | Whether the Return key is grayed out when the field is empty |
inputAccessoryView | A view attached above the keyboard while it is shown |
inputView | A view shown in place of the system keyboard |
allowsNumberPadPopover | Whether the number pad popover is allowed |
Input behavior:
| Property | Description |
|---|---|
isSecureTextEntry | Shows the content as dots, for passwords |
autocapitalizationType | The automatic capitalization rule |
autocorrectionType | Whether autocorrection is on |
spellCheckingType | Whether spelling is checked |
textContentType | What kind of content the field holds, which the system uses for AutoFill |
smartQuotesType | Whether straight quotes are replaced with curly quotes |
smartDashesType | Whether consecutive hyphens are replaced with a dash |
smartInsertDeleteType | Whether spaces are adjusted automatically on paste and delete |
inlinePredictionType | Whether predicted text appears after the cursor |
mathExpressionCompletionType | Whether the result of a math expression is computed automatically |
writingToolsBehavior | How far Writing Tools can go |
allowedWritingToolsResultOptions | Which kinds of content Writing Tools can write back |
Appearance:
| Property | Description |
|---|---|
borderStyle | The look of the border |
clearButtonMode | When the clear button on the right is shown |
textAlignment | Horizontal alignment of the text |
font | Font and size of the text |
textColor | Color of the text |
adjustsFontSizeToFitWidth | Whether the font size shrinks when the content is wider than the field |
minimumFontSize | The smallest size the font can shrink to |
background | Background image |
disabledBackground | Background image when disabled |
leftView | A view at the left end of the field |
leftViewMode | When the left view is shown |
rightView | A view at the right end of the field |
rightViewMode | When the right view is shown |
Instance methods
Also inherits methods from UIControl and UIView. Commonly used inherited methods on a text field are becomeFirstResponder(), resignFirstResponder(), and addEventListener(); see Focus.
Changing the content:
| Method | Description |
|---|---|
insertText() | Inserts text at the cursor the way the user types |
deleteBackward() | Deletes the way the user presses the Delete key |
Computing the position of each part. These methods return the rectangle the text field uses to lay out a given part within the given bounds:
| Method | Description |
|---|---|
borderRectForBounds() | Rectangle of the border |
textRectForBounds() | Rectangle where the text is displayed |
placeholderRectForBounds() | Rectangle where the placeholder is displayed |
editingRectForBounds() | Rectangle of the text while editing |
clearButtonRectForBounds() | Rectangle of the clear button |
leftViewRectForBounds() | Rectangle of the left view |
rightViewRectForBounds() | Rectangle of the right view |
Events
Listen with addEventListener(). A text field's events fall into three groups: control events tell the app what happened, selectionchange tells the app the cursor or selection moved, and cancelable events ask the app whether something should happen before it does.
Control events are inherited from UIControl. A text field uses these four:
| Event | When it fires |
|---|---|
focus | The text field becomes first responder and editing begins |
input | The user's input changed the content once |
return | The user pressed the Return key |
blur | The text field is no longer first responder and editing ends |
The text field's own events:
| Event | When it fires |
|---|---|
selectionchange | The selection or the cursor position changed |
beforefocus | Editing is about to begin. Cancelable |
beforeblur | Editing is about to end. Cancelable |
beforeinput | The user's input is about to change the content. Cancelable |
beforeclear | The user tapped the clear button and the field is about to be cleared. Cancelable |
beforereturn | The user pressed the Return key and it is about to be handled the default way. Cancelable |
The system fires the 16 control events listed under UIControl, traitchange, selectionchange, and the five cancelable events. Listening for any other name does not throw: it is treated as a custom event and fires only when you dispatch it yourself with dispatchEvent(); see the limits on event names.
Focus
The first responder is iOS's name for "the object currently receiving keyboard input", that is, the object that has focus. There is at most one at a time. The keyboard follows the first responder: it appears when a text field becomes first responder and goes away when the text field stops being first responder. There are no separate "show keyboard" or "hide keyboard" methods.
| What you want to do | How to write it |
|---|---|
| Focus the text field | field.becomeFirstResponder() |
| Remove focus from the text field | field.resignFirstResponder(), or page.view.endEditing(true) |
| Check whether the text field has focus | field.isFirstResponder |
| Learn that the text field gained or lost focus | The focus and blur events |
These members are defined on UIResponder and UIView, so every view has them:
becomeFirstResponder()returns a boolean.truemeans it is now first responder;falsemeans the system refused, nothing happened, and the keyboard does not appear.resignFirstResponder()returns a boolean.truemeans it is no longer first responder. The return value when the object was not first responder in the first place is not verified in the simulator.isFirstResponderis read-only. A new text field hasfalse.canBecomeFirstResponderis read-only. It istruefor a text field andfalsefor a plainUIView. Neither value has been verified in the simulator.endEditing(true)removes focus from whichever text field in a view hierarchy is being edited, without needing to know which one it is.
The result of becomeFirstResponder() in different situations:
| Situation | Result | Basis |
|---|---|---|
| The view controller is already shown and no transition is in progress | Returns true, then focus fires | Measured |
| The text field is already first responder | Returns true | The acceptance tests rely on this by calling it repeatedly; there is no separate assertion |
| A transition is in progress (during the animation of a modal view controller being presented or dismissed) | Returns false | Measured |
In the sceneconnect callback, before the view controller is shown | Returns true and isEditing is true, but focus does not fire | Measured |
| The text field has not been added to the view controller yet | Returns false | Not verified in the simulator |
Two more things:
- When the user taps a text field, focus happens the moment the finger touches down, without waiting for the finger to lift (measured).
- Tapping elsewhere does not remove focus automatically. The text field stays first responder and the keyboard stays on screen until code removes focus or the user taps another text field. Not verified in the simulator.
Which events one round of input fires
| User action | Fires |
|---|---|
| Tap the text field | focus. Measured to fire the moment the finger touches down |
| Type three characters | input three times. Not verified in the simulator |
| Press Return | return. Not verified in the simulator |
| The keyboard goes away | blur |
A cancelable event comes before its corresponding control event: focusing once was measured to fire beforefocus → focus.
Whether return or blur comes first is not verified in the simulator. Calling becomeFirstResponder() and endEditing() from code fires focus and blur in the same way; this is verified in the acceptance tests.
Rules for control events:
- The event object's
typeis the event name and itstargetis this text field. The event object does not carry the typed content, which key was pressed, or the touch location. Read the content fromfield.text. - They cannot be canceled;
preventDefault()has no effect. To stop something from happening, use a cancelable event. - Callbacks do not run synchronously at the moment the event occurs; they run a little later, see When callbacks run. The
field.textread in a callback is the content at the time the callback runs; when the user types fast, the content read in one callback may already include the next few keystrokes. Not verified in the simulator. - Changing
textfrom code does not fireinput; the event fires only when the user's input changes the content. Not verified in the simulator. - For "the user finished typing", use
blur. There is no separate "content committed" event. - With input methods such as Chinese Pinyin, the Pinyin letters the user has not yet converted count toward
text, andinputfires each time the Pinyin changes. ReadmarkedTextRangein the callback: if it is notnull, the user has not picked the characters yet. These two points were verified by simulating input-method composition in code and are not verified with a real input method. - An exception thrown in a callback does not affect the text field, and the other callbacks for the same event still run. The exception fires
erroronapplication; if no listener cancels it, the console prints a log line starting withUncaught.
Selection and cursor
The selection is the selected stretch of text in the text field. When no text is selected, the selection is a position of length 0, which is the cursor. selectedRange represents it as an NSRange: location is the start and length is the length, both in UTF-16 code units, the same as JS string indices, so field.text.slice(location, location + length) is the selected text.
A text field always has a selection; it can be read and written even when the user is not editing (measured). When the user is not editing, no cursor or selection highlight is shown on screen.
Emoji and some Chinese characters take two code units. Placing the cursor between those two code units does not throw and is not corrected: when the content is 'a😀b', writing (2, 0) reads back as (2, 0) (measured). On a text view, inserting text at such a position was measured to split the character in two. Avoid such positions when computing positions yourself.
Size
A text field is a view and is positioned like any other view; see Auto Layout. All sizes are in points (pt).
- With constraints, you can leave out the height but must supply the width. The text field computes its own height from the font. Without a width, it sizes its width to the content, which is very narrow when empty and grows as the user types. So constrain both the left and right edges, or give it a fixed width. Not verified in the simulator.
- With
frame, you must supply both width and height. Otherwise both are 0 and nothing appears on screen.
Examples
Entering a name
Starting from a blank app, place a text field near the top of the screen. Each time the user types a character, the text below updates. Pressing Return dismisses the keyboard.
application.addEventListener('sceneconnect', (e) => {
const win = new UIWindow(e.scene);
const page = new UIViewController();
page.view.backgroundColor = 'systemBackground';
win.rootViewController = page;
win.makeKeyAndVisible();
const field = new UITextField();
field.placeholder = 'Enter your name';
field.borderStyle = 'roundedRect';
field.returnKeyType = 'done';
const greeting = new UILabel();
greeting.text = 'Hello';
field.addEventListener('input', () => {
greeting.text = field.text === '' ? 'Hello' : `Hello, ${field.text}`;
});
field.addEventListener('return', () => {
field.resignFirstResponder();
console.log('You entered: ' + field.text);
});
field.translatesAutoresizingMaskIntoConstraints = false;
greeting.translatesAutoresizingMaskIntoConstraints = false;
page.view.addSubview(field);
page.view.addSubview(greeting);
const safe = page.view.safeAreaLayoutGuide;
NSLayoutConstraint.activateConstraints([
field.topAnchor.constraintEqualToAnchor(safe.topAnchor, { constant: 24 }),
field.leadingAnchor.constraintEqualToAnchor(safe.leadingAnchor, { constant: 16 }),
field.trailingAnchor.constraintEqualToAnchor(safe.trailingAnchor, { constant: -16 }),
greeting.topAnchor.constraintEqualToAnchor(field.bottomAnchor, { constant: 16 }),
greeting.leadingAnchor.constraintEqualToAnchor(field.leadingAnchor),
]);
});Effect
- A text field with a rounded border appears near the top of the screen, showing "Enter your name" in gray. The line below reads "Hello".
- Tap the text field: the keyboard slides up from the bottom of the screen and a cursor appears in the field.
- With each character typed, the line below changes to "Hello, " followed by the field's content. When the content is deleted entirely, it goes back to "Hello".
- Press the Return key at the bottom right of the keyboard: the keyboard goes away and the console prints
You entered:followed by the field's content.
This code has not been run as a whole in the simulator. Every API it uses has been run in the acceptance tests. The appearance (the border, the placeholder color, the label on the Return key) and "input fires once per typed character" are not verified in the simulator.
Note: When the simulator is connected to the computer's hardware keyboard, the on-screen software keyboard does not appear. This is simulator behavior. To see the software keyboard, turn off the hardware keyboard connection in the simulator's menu.
Password field
const secret = new UITextField();
secret.placeholder = 'Password';
secret.borderStyle = 'roundedRect';
secret.textContentType = 'password';
secret.isSecureTextEntry = true;
secret.returnKeyType = 'done';Effect: Each typed character is shown as a dot. When the user taps the field, the system may list saved accounts above the keyboard. Not verified in the simulator.
Corresponding iOS API
| ObjC | JS |
|---|---|
[[UITextField alloc] init] | new UITextField() |
field.text | field.text |
field.placeholder = @"Account" | field.placeholder = 'Account' |
field.secureTextEntry = YES | field.isSecureTextEntry = true |
field.keyboardType = UIKeyboardTypeNumberPad | field.keyboardType = 'numberPad' |
field.returnKeyType = UIReturnKeyDone | field.returnKeyType = 'done' |
field.textContentType = UITextContentTypeOneTimeCode | field.textContentType = 'oneTimeCode' |
field.autocapitalizationType = UITextAutocapitalizationTypeNone | field.autocapitalizationType = 'none' |
field.autocorrectionType = UITextAutocorrectionTypeNo | field.autocorrectionType = 'no' |
field.borderStyle = UITextBorderStyleRoundedRect | field.borderStyle = 'roundedRect' |
field.clearButtonMode = UITextFieldViewModeWhileEditing | field.clearButtonMode = 'whileEditing' |
field.textColor = UIColor.labelColor | field.textColor = 'label' |
field.editing | field.isEditing |
field.hasText | field.hasText |
[field insertText:@"Hello"] | field.insertText('Hello') |
[field deleteBackward] | field.deleteBackward() |
field.inputAccessoryView = toolbar | field.inputAccessoryView = toolbar |
Calling [field reloadInputViews] after changing inputAccessoryView | Not needed. Writing inputAccessoryView takes effect immediately |
field.selectedTextRange, then converting to offsets with offsetFromPosition:toPosition: | field.selectedRange |
field.selectedTextRange = [field textRangeFromPosition:start toPosition:end] | field.selectedRange = new NSRange(location, length) |
[field addTarget:self action:@selector(changed) forControlEvents:UIControlEventEditingChanged] | field.addEventListener('input', changed) |
[field becomeFirstResponder] | field.becomeFirstResponder() |
[field resignFirstResponder] | field.resignFirstResponder() |
field.isFirstResponder | field.isFirstResponder |
[view endEditing:YES] | view.endEditing(true) |
view.keyboardLayoutGuide.topAnchor | view.keyboardLayoutGuide.topAnchor |
Enum values drop the type prefix and start with a lowercase letter. UIKeyboardTypeEmailAddress is written 'emailAddress'. See Enums.
How UITextFieldDelegate methods map to JS:
| ObjC delegate method | JS |
|---|---|
textFieldDidBeginEditing: | The focus event |
textFieldDidChangeSelection: | The selectionchange event |
textFieldDidEndEditing: | The blur event |
Dismissing the keyboard in textFieldShouldReturn: | Calling resignFirstResponder() in the return event |
Returning NO from textFieldShouldBeginEditing: | Calling event.preventDefault() in the beforefocus event |
Returning NO from textFieldShouldEndEditing: | Calling event.preventDefault() in the beforeblur event |
Returning NO from textField:shouldChangeCharactersInRange:replacementString: | Calling event.preventDefault() in the beforeinput event. The two arguments are in event.range and event.replacementString |
Returning NO from textFieldShouldClear: | Calling event.preventDefault() in the beforeclear event |
Returning NO from textFieldShouldReturn: | Calling event.preventDefault() in the beforereturn event |
ObjC represents the two ends of a selection with UITextRange and UITextPosition; in JS the selection is an NSRange counted from the start of the content, read and written through selectedRange.
Mapping to the browser's <input>
This table is only for looking up correspondences, for people familiar with HTML forms.
| Browser | Nacre | Difference |
|---|---|---|
input.value | field.text | An empty string when there is no content, not null |
placeholder | placeholder | Reads null when not set |
type="password" | isSecureTextEntry = true | A boolean property, not a type |
inputmode | keyboardType | Only decides which keyboard appears; does not validate content |
autocomplete | textContentType | The values are a set of names defined by iOS |
enterkeyhint | returnKeyType | Only changes the label on the Return key, not its behavior |
input event | input event | The event object does not carry the content; read field.text |
focus / blur events | focus / blur events | — |
Checking for Enter in keydown | return event | — |
el.focus() / el.blur() | becomeFirstResponder() / resignFirstResponder() | Return a value indicating whether they succeeded |
document.activeElement === el | field.isFirstResponder | — |
selectionStart, selectionEnd, setSelectionRange() | selectedRange | A start plus a length, not a start plus an end |
selectionchange event | selectionchange event | The event object does not carry the selection; read field.selectedRange |
disabled | isEnabled = false | — |
maxlength, pattern, required, readonly | None | Check them yourself in the beforeinput or input callback |
| Form submission | None | Pressing Return fires return; the callback decides what to do |
See also
- Building a text field: reading the content, dismissing the keyboard, avoiding the keyboard, limiting input, form screens
UIControl: the text field's parent class, withisEnabledand all 16 eventsUIView:endEditing(),keyboardLayoutGuide, and the safe areaUIKeyboardLayoutGuide: keeping content clear of the keyboardNSRange: the type ofselectedRangeUITextView: multiline inputUISearchBar: a search bar, which contains a text field- Attributed strings: the type of
attributedTextandattributedPlaceholder