UITextField Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/UIKit.framework
Availability
Available in iOS 2.0 and later.
Declared in
UITextField.h
Companion guides
Related sample code

Overview

A UITextField object is a control that displays editable text and sends an action message to a target object when the user presses the return button. You typically use this class to gather small amounts of text from the user and perform some immediate action, such as a search operation, based on that text.

In addition to its basic text-editing behavior, the UITextField class supports the use of overlay views to display additional information (and provide additional command targets) inside the text field boundaries. You can use custom overlay views to display features such as a bookmarks button or search icon. The UITextField class also provides a built-in button for clearing the current text.

A text field object supports the use of a delegate object to handle editing-related notifications. You can use this delegate to customize the editing behavior of the control and provide guidance for when certain actions should occur. For more information on the methods supported by the delegate, see the UITextFieldDelegate protocol.

For information about basic view behaviors, see View Programming Guide for iOS.

Managing the Keyboard

When the user taps in a text field, that text field becomes the first responder and automatically asks the system to display the associated keyboard. Because the appearance of the keyboard has the potential to obscure portions of your user interface, it is up to you to make sure that does not happen by repositioning any views that might be obscured. Some system views, like table views, help you by scrolling the first responder into view automatically. If the first responder is at the bottom of the scrolling region, however, you may still need to resize or reposition the scroll view itself to ensure the first responder is visible.

It is your application’s responsibility to dismiss the keyboard at the time of your choosing. You might dismiss the keyboard in response to a specific user action, such as the user tapping a particular button in your user interface. You might also configure your text field delegate to dismiss the keyboard when the user presses the “return” key on the keyboard itself. To dismiss the keyboard, send the resignFirstResponder message to the text field that is currently the first responder. Doing so causes the text field object to end the current editing session (with the delegate object’s consent) and hide the keyboard.

The appearance of the keyboard itself can be customized using the properties provided by the UITextInputTraits protocol. Text field objects implement this protocol and support the properties it defines. You can use these properties to specify the type of keyboard (ASCII, Numbers, URL, Email, and others) to display. You can also configure the basic text entry behavior of the keyboard, such as whether it supports automatic capitalization and correction of the text.

Keyboard Notifications

When the system shows or hides the keyboard, it posts several keyboard notifications. These notifications contain information about the keyboard, including its size, which you can use for calculations that involve moving views. Registering for these notifications is the only way to get some types of information about the keyboard. The system delivers the following notifications for keyboard-related events:

For more information about these notifications, see their descriptions in UIWindow Class Reference. For information about how to show and hide the keyboard, see Text Programming Guide for iOS.

State Preservation

In iOS 6 and later, if you assign a value to this view’s restorationIdentifier property, it preserves the selected range of text, if any. During the next launch cycle, the view attempts to restore that selection. If the selection range cannot be applied to the text in the restored view, no selection is made. For more information about how state preservation and restoration works, see iOS App Programming Guide.

For more information about appearance and behavior configuration, see “Text Fields”.

Tasks

Accessing the Text Attributes

Sizing the Text Field’s Text

Managing the Editing Behavior

Setting the View’s Background Appearance

Managing Overlay Views

Accessing the Delegate

Drawing and Positioning Overrides

Replacing the System Input Views

Properties

adjustsFontSizeToFitWidth

A Boolean value indicating whether the font size should be reduced in order to fit the text string into the text field’s bounding rectangle.

@property(nonatomic) BOOL adjustsFontSizeToFitWidth
Discussion

Normally, the text field’s content is drawn with the font you specify in the font property. If this property is set to YES, however, and the contents in the text property exceed the text field’s bounding rectangle, the receiver starts reducing the font size until the string fits or the minimum font size is reached. The text is shrunk along the baseline.

The default value for this property is NO. If you change it to YES, you should also set an appropriate minimum font size by modifying the minimumFontSize property.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

allowsEditingTextAttributes

A Boolean value indicating whether the user may edit the attributes of the text in the text field.

@property(nonatomic) BOOL allowsEditingTextAttributes
Discussion

If this property is set to YES, the user may edit the style information of the text. In addition, pasting styled text into the text field retains any embedded style information. If NO, the text field prohibits the editing of style information and strips style information from any pasted text. However, you can still set the style information programmatically using the methods of this class.

The default value of this property is NO.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITextField.h

attributedPlaceholder

The styled string that is displayed when there is no other text in the text field.

@property(nonatomic, copy) NSAttributedString *attributedPlaceholder
Discussion

This property is nil by default. If set, the placeholder string is drawn using a 70% grey color and the remaining style information (except the text color) of the attributed string. Assigning a new value to this property also replaces the value of the placeholder property with the same string data, albeit without any formatting information. Assigning a new value to this property does not affect any other style-related properties of the text field.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITextField.h

attributedText

The styled text displayed by the text field.

@property(nonatomic, copy) NSAttributedString *attributedText
Discussion

This property is nil by default. Assigning a new value to this property also replaces the value of the text property with the same string data, albeit without any formatting information. In addition, assigning a new a value updates the values in the font, textColor, and other style-related properties so that they reflect the style information starting at location 0 in the attributed string.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITextField.h

background

The image that represents the background appearance of the text field when it is enabled.

@property(nonatomic, retain) UIImage *background
Discussion

When set, the image referred to by this property replaces the standard appearance controlled by the borderStyle property. Background images are drawn in the border rectangle portion of the text field. Images you use for the text field’s background should be able to stretch to fit.

This property is set to nil by default.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

borderStyle

The border style used by the text field.

@property(nonatomic) UITextBorderStyle borderStyle
Discussion

The default value for this property is UITextBorderStyleNone. If the value is set to the UITextBorderStyleRoundedRect style, the custom background image associated with the text field is ignored.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITextField.h

clearButtonMode

Controls when the standard clear button appears in the text field.

@property(nonatomic) UITextFieldViewMode clearButtonMode
Discussion

The standard clear button is displayed at the right side of the text field, when the text field has contents, as a way for the user to remove text quickly. This button appears automatically based on the value set for this property.

The default value for this property is UITextFieldViewModeNever.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

clearsOnBeginEditing

A Boolean value indicating whether the text field removes old text when editing begins.

@property(nonatomic) BOOL clearsOnBeginEditing
Discussion

If this property is set to YES, the text field’s previous text is cleared when the user selects the text field to begin editing. If NO, the text field places an insertion point at the place where the user tapped the field.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

clearsOnInsertion

A Boolean value indicating whether inserting text replaces the previous contents.

@property(nonatomic) BOOL clearsOnInsertion
Discussion

The default value of this property is NO. When the value of this property is YES and the text field is in editing mode, the selection UI is hidden and inserting new text clears the contents of the text field and sets the value of this property back to NO.

Availability
  • Available in iOS 6.0 and later.
Declared In
UITextField.h

defaultTextAttributes

The default attributes to apply to the text.

@property(nonatomic, copy) NSDictionary *defaultTextAttributes
Discussion

By default, this property returns a dictionary of text attributes with default values.

Setting this property applies the specified attributes to the entire text of the text field. Unset attributes maintain their default values.

Getting this property returns the previously set attributes, which may have been modified by setting properties such as font and textColor.

Availability
  • Available in iOS 7.0 and later.
Declared In
UITextField.h

delegate

The receiver’s delegate.

@property(nonatomic, assign) id<UITextFieldDelegate> delegate
Discussion

A text field delegate responds to editing-related messages from the text field. You can use the delegate to respond to the text entered by the user and to some special commands, such as when the return button is pressed.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITextField.h

disabledBackground

The image that represents the background appearance of the text field when it is disabled.

@property(nonatomic, retain) UIImage *disabledBackground
Discussion

Background images are drawn in the border rectangle portion of the text field. Images you use for the text field’s background should be able to stretch to fit. This property is ignored if the background property is not also set.

This property is set to nil by default.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

editing

A Boolean value indicating whether the text field is currently in edit mode. (read-only)

@property(nonatomic, readonly, getter=isEditing) BOOL editing
Discussion

This property is set to YES when the user begins editing text in this text field, and it is set to NO again when editing ends. Notifications about when editing begins and ends are sent to the text field delegate.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

font

The font of the text.

@property(nonatomic, retain) UIFont *font
Discussion

This property applies to the entire text of the text field. It also applies to the placeholder text. The default font is a 12-point Helvetica plain font.

If you are using styled text in iOS 6 or later, assigning a new value to this property causes the font to be applied to the entirety of the string in the attributedText property. If you want to apply the font to only a portion of the text, create a new attributed string with the desired style information and associate it with the text field.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITextField.h

inputAccessoryView

The custom accessory view to display when the text field becomes the first responder

@property(readwrite, retain) UIView *inputAccessoryView
Discussion

The default value of this property is nil. Assigning a view to this property causes that view to be displayed above the standard system keyboard (or above the custom input view if one is provided) when the text field becomes the first responder. For example, you could use this property to attach a custom toolbar to the keyboard.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextField.h

inputView

The custom input view to display when the text field becomes the first responder.

@property(readwrite, retain) UIView *inputView
Discussion

If the value in this property is nil, the text field displays the standard system keyboard when it becomes first responder. Assigning a custom view to this property causes that view to be presented instead.

The default value of this property is nil.

Availability
  • Available in iOS 3.2 and later.
Declared In
UITextField.h

leftView

The overlay view displayed on the left side of the text field.

@property(nonatomic, retain) UIView *leftView
Discussion

You can use the left overlay view to indicate the intended behavior of the text field. For example, you might display a magnifying glass in this location to indicate that the text field is a search field.

The left overlay view is placed in the rectangle returned by the leftViewRectForBounds: method of the receiver. The image associated with this property should fit the given rectangle. If it does not fit, it is scaled to fit. If you specify a control for your view, the control tracks and sends actions as usual.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

leftViewMode

Controls when the left overlay view appears in the text field.

@property(nonatomic) UITextFieldViewMode leftViewMode
Discussion

The default value for this property is UITextFieldViewModeNever.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

minimumFontSize

The size of the smallest permissible font with which to draw the text field’s text.

@property(nonatomic) CGFloat minimumFontSize
Discussion

When drawing text that might not fit within the bounding rectangle of the text field, you can use this property to prevent the receiver from reducing the font size to the point where it is no longer legible.

The default value for this property is 0.0. If you enable font adjustment for the text field, you should always increase this value.

If you are using styled text in iOS 6 or later, assigning a new value to this property causes the minimum font size to be applied to the entirety of the string in the attributedText property. If you want to apply different minimum font sizes to different parts of your string, create a new attributed string with the desired style information and associate it with the text field.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

placeholder

The string that is displayed when there is no other text in the text field.

@property(nonatomic, copy) NSString *placeholder
Discussion

This value is nil by default. The placeholder string is drawn using a 70% grey color.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

rightView

The overlay view displayed on the right side of the text field.

@property(nonatomic, retain) UIView *rightView
Discussion

You can use the right overlay view to provide indicate additional features available for the text field. For example, you might display a bookmarks button in this location to allow the user to select from a set of predefined items.

The right overlay view is placed in the rectangle returned by the rightViewRectForBounds: method of the receiver. The image associated with this property should fit the given rectangle. If it does not fit, it is scaled to fit. If you specify a control for your view, that control tracks and sends actions as usual.

If your right overlay view overlaps a sibling view, such as the clear button, you must use the UITextFieldViewMode to implement proper behavior. For example, if clearButtonMode is set to display the clear button, you can set the right overlay view’s rightViewMode to UITextFieldViewModeUnlessEditing to reveal the clear button during editing when the text field has contents.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

rightViewMode

Controls when the right overlay view appears in the text field.

@property(nonatomic) UITextFieldViewMode rightViewMode
Discussion

The default value for this property is UITextFieldViewModeNever.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

text

The text displayed by the text field.

@property(nonatomic, copy) NSString *text
Discussion

This string is @"" by default.

In iOS 6 and later, assigning a new value to this property also replaces the value of the attributedText property with the same text, albeit without any inherent style attributes. Instead the text view styles the new string using the font, textColor, and other style-related properties of the class.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

textAlignment

The technique to use for aligning the text.

@property(nonatomic) NSTextAlignment textAlignment
Discussion

This property applies to the both the main text string and the placeholder string. The default value of this property is NSLeftTextAlignment.

If you are using styled text in iOS 6 or later, assigning a new value to this property causes the text alignment to be applied to the entirety of the string in the attributedText property. If you want to apply the alignment to only a portion of the text, create a new attributed string with the desired style information and associate it with the text field.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

textColor

The color of the text.

@property(nonatomic, retain) UIColor *textColor
Discussion

This property applies to the entire text string. The default value for this property is a black color. The value for the property can only be set to a non-nil value; setting this property to nil raises an exception.

If you are using styled text in iOS 6 or later, assigning a new value to this property causes the text color to be applied to the entirety of the string in the attributedText property. If you want to apply the color to only a portion of the text, create a new attributed string with the desired style information and associate it with the text field.

Availability
  • Available in iOS 2.0 and later.
Related Sample Code
Declared In
UITextField.h

typingAttributes

The attributes to apply to new text being entered by the user.

@property(nonatomic, copy) NSDictionary *typingAttributes
Discussion

This dictionary contains the attribute keys (and corresponding values) to apply to newly typed text. When the text field’s selection changes, the contents of the dictionary are cleared automatically.

If the text field is not in editing mode, this property contains the value nil. Similarly, you cannot assign a value to this property unless the text field is currently in editing mode.

Availability
  • Available in iOS 6.0 and later.
See Also
Declared In
UITextField.h

Instance Methods

borderRectForBounds:

Returns the receiver’s border rectangle.

- (CGRect)borderRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The border rectangle for the receiver.

Discussion

You should not call this method directly. If you want to provide a different border rectangle for drawing, you can override this method and return that rectangle.

The default implementation of this method returns the original bounds rectangle.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

clearButtonRectForBounds:

Returns the drawing rectangle for the built-in clear button.

- (CGRect)clearButtonRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The rectangle in which to draw the clear button.

Discussion

You should not call this method directly. If you want to place the clear button in a different location, you can override this method and return the new rectangle. Your method should call the super implementation and modify the returned rectangle’s origin only. Changing the size of the clear button may cause unnecessary distortion of the button image.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

drawPlaceholderInRect:

Draws the receiver’s placeholder text in the specified rectangle.

- (void)drawPlaceholderInRect:(CGRect)rect
Parameters
rect

The rectangle in which to draw the placeholder text.

Discussion

You should not call this method directly. If you want to customize the drawing behavior for the placeholder text, you can override this method to do your drawing.

By the time this method is called, the current graphics context is already configured with the default environment and text color for drawing. In your overridden method, you can configure the current context further and then invoke super to do the actual drawing or do the drawing yourself. If you do render the text yourself, you should not invoke super.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

drawTextInRect:

Draws the receiver’s text in the specified rectangle.

- (void)drawTextInRect:(CGRect)rect
Parameters
rect

The rectangle in which to draw the text.

Discussion

You should not call this method directly. If you want to customize the drawing behavior for the text, you can override this method to do your drawing.

By the time this method is called, the current graphics context is already configured with the default environment and text color for drawing. In your overridden method, you can configure the current context further and then invoke super to do the actual drawing or you can do the drawing yourself. If you do render the text yourself, you should not invoke super.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

editingRectForBounds:

Returns the rectangle in which editable text can be displayed.

- (CGRect)editingRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The computed editing rectangle for the text.

Discussion

You should not call this method directly. If you want to provide a different editing rectangle for the text, you can override this method and return that rectangle. By default, this method returns a region in the text field that is not occupied by any overlay views.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

leftViewRectForBounds:

Returns the drawing rectangle of the receiver’s left overlay view.

- (CGRect)leftViewRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The rectangle in which to draw the left overlay view.

Discussion

You should not call this method directly. If you want to place the left overlay view in a different location, you can override this method and return the new rectangle.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

placeholderRectForBounds:

Returns the drawing rectangle for the text field’s placeholder text

- (CGRect)placeholderRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The computed drawing rectangle for the placeholder text.

Discussion

You should not call this method directly. If you want to customize the drawing rectangle for the placeholder text, you can override this method and return a different rectangle.

If the placeholder string is empty or nil, this method is not called.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

rightViewRectForBounds:

Returns the drawing location of the receiver’s right overlay view.

- (CGRect)rightViewRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The rectangle in which to draw the right overlay view.

Discussion

You should not call this method directly. If you want to place the right overlay view in a different location, you can override this method and return the new rectangle.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

textRectForBounds:

Returns the drawing rectangle for the text field’s text.

- (CGRect)textRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The computed drawing rectangle for the label’s text.

Discussion

You should not call this method directly. If you want to customize the drawing rectangle for the text, you can override this method and return a different rectangle.

The default implementation of this method returns a rectangle that is derived from the control’s original bounds, but which does not include the area occupied by the receiver’s border or overlay views.

Availability
  • Available in iOS 2.0 and later.
Declared In
UITextField.h

Constants

UITextFieldBorderStyle

The type of border drawn around the text field.

typedef enum {
   UITextBorderStyleNone,
   UITextBorderStyleLine,
   UITextBorderStyleBezel,
   UITextBorderStyleRoundedRect
} UITextBorderStyle;
Constants
UITextBorderStyleNone

The text field does not display a border.

Available in iOS 2.0 and later.

Declared in UITextField.h.

UITextBorderStyleLine

Displays a thin rectangle around the text field.

Available in iOS 2.0 and later.

Declared in UITextField.h.

UITextBorderStyleBezel

Displays a bezel-style border for the text field. This style is typically used for standard data-entry fields.

Available in iOS 2.0 and later.

Declared in UITextField.h.

UITextBorderStyleRoundedRect

Displays a rounded-style border for the text field.

Available in iOS 2.0 and later.

Declared in UITextField.h.

UITextFieldViewMode

Defines the times at which overlay views appear in a text field.

typedef enum {
   UITextFieldViewModeNever,
   UITextFieldViewModeWhileEditing,
   UITextFieldViewModeUnlessEditing,
   UITextFieldViewModeAlways
} UITextFieldViewMode;
Constants
UITextFieldViewModeNever

The overlay view never appears.

Available in iOS 2.0 and later.

Declared in UITextField.h.

UITextFieldViewModeWhileEditing

The overlay view is displayed only while text is being edited in the text field.

Available in iOS 2.0 and later.

Declared in UITextField.h.

UITextFieldViewModeUnlessEditing

The overlay view is displayed only when text is not being edited.

Available in iOS 2.0 and later.

Declared in UITextField.h.

UITextFieldViewModeAlways

The overlay view is always displayed.

Available in iOS 2.0 and later.

Declared in UITextField.h.

Notifications

UITextFieldTextDidBeginEditingNotification

Notifies observers that an editing session began in a text field. The affected text field is stored in the object parameter of the notification. The userInfo dictionary is not used.
Availability
Declared In
UITextField.h

UITextFieldTextDidChangeNotification

Notifies observers that the text in a text field changed. The affected text field is stored in the object parameter of the notification.
Availability
Declared In
UITextField.h

UITextFieldTextDidEndEditingNotification

Notifies observers that the editing session ended for a text field. The affected text field is stored in the object parameter of the notification. The userInfo dictionary is not used.
Availability
Declared In
UITextField.h