iOS Developer Library

Developer

UIKit Framework Reference UITextField Class Reference

Options
Deployment Target:

On This Page
Language:

UITextField

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

Import Statement


import UIKit @import UIKit;

Availability


Available in iOS 2.0 and later.
  • text text Property

    The text displayed by the text field.

    Declaration

    Swift

    var text: String!

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The styled text displayed by the text field.

    Declaration

    Swift

    @NSCopying var attributedText: NSAttributedString?

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    var placeholder: String?

    Objective-C

    @property(nonatomic, copy) NSString *placeholder

    Discussion

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    @NSCopying var attributedPlaceholder: NSAttributedString?

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • The default attributes to apply to the text.

    Declaration

    Swift

    var defaultTextAttributes: [NSObject : AnyObject]!

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • font font Property

    The font of the text.

    Declaration

    Swift

    var font: UIFont!

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • textColor textColor Property

    The color of the text.

    Declaration

    Swift

    var textColor: UIColor!

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The technique to use for aligning the text.

    Declaration

    Swift

    var textAlignment: NSTextAlignment

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var typingAttributes: [NSObject : AnyObject]?

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 6.0 and later.

    See Also

    editing

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

    Declaration

    Swift

    var adjustsFontSizeToFitWidth: Bool

    Objective-C

    @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 YEStrue, 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 NOfalse. If you change it to YEStrue, you should also set an appropriate minimum font size by modifying the minimumFontSize property.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    minimumFontSize

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

    Declaration

    Swift

    var minimumFontSize: CGFloat

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • editing editing Property

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

    Declaration

    Swift

    var editing: Bool { get }

    Objective-C

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

    Discussion

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var clearsOnBeginEditing: Bool

    Objective-C

    @property(nonatomic) BOOL clearsOnBeginEditing

    Discussion

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var clearsOnInsertion: Bool

    Objective-C

    @property(nonatomic) BOOL clearsOnInsertion

    Discussion

    The default value of this property is NOfalse. When the value of this property is YEStrue 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 NOfalse.

    Import Statement

    import UIKit

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    var allowsEditingTextAttributes: Bool

    Objective-C

    @property(nonatomic) BOOL allowsEditingTextAttributes

    Discussion

    If this property is set to YEStrue, 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 NOfalse, 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 NOfalse.

    Import Statement

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • The border style used by the text field.

    Declaration

    Swift

    var borderStyle: UITextBorderStyle

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var background: UIImage?

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var disabledBackground: UIImage?

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    background

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

    Declaration

    Swift

    var clearButtonMode: UITextFieldViewMode

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • leftView leftView Property

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

    Declaration

    Swift

    var leftView: UIView?

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var leftViewMode: UITextFieldViewMode

    Objective-C

    @property(nonatomic) UITextFieldViewMode leftViewMode

    Discussion

    The default value for this property is UITextFieldViewModeNever.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • rightView rightView Property

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

    Declaration

    Swift

    var rightView: UIView?

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var rightViewMode: UITextFieldViewMode

    Objective-C

    @property(nonatomic) UITextFieldViewMode rightViewMode

    Discussion

    The default value for this property is UITextFieldViewModeNever.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • delegate delegate Property

    The receiver’s delegate.

    Declaration

    Swift

    unowned(unsafe) var delegate: UITextFieldDelegate?

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func textRectForBounds(_ bounds: CGRect) -> CGRect

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func drawTextInRect(_ rect: CGRect)

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func placeholderRectForBounds(_ bounds: CGRect) -> CGRect

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func drawPlaceholderInRect(_ rect: CGRect)

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Returns the receiver’s border rectangle.

    Declaration

    Swift

    func borderRectForBounds(_ bounds: CGRect) -> CGRect

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Returns the rectangle in which editable text can be displayed.

    Declaration

    Swift

    func editingRectForBounds(_ bounds: CGRect) -> CGRect

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func clearButtonRectForBounds(_ bounds: CGRect) -> CGRect

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func leftViewRectForBounds(_ bounds: CGRect) -> CGRect

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func rightViewRectForBounds(_ bounds: CGRect) -> CGRect

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • inputView inputView Property

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

    Declaration

    Swift

    var inputView: UIView?

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.2 and later.

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

    Declaration

    Swift

    var inputAccessoryView: UIView?

    Objective-C

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

    Import Statement

    import UIKit

    Availability

    Available in iOS 3.2 and later.

  • The type of border drawn around the text field.

    Declaration

    Swift

    enum UITextBorderStyle : Int { case None case Line case Bezel case RoundedRect }

    Objective-C

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

    Constants

    • None

      UITextBorderStyleNone

      The text field does not display a border.

      Available in iOS 2.0 and later.

    • Line

      UITextBorderStyleLine

      Displays a thin rectangle around the text field.

      Available in iOS 2.0 and later.

    • Bezel

      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.

    • RoundedRect

      UITextBorderStyleRoundedRect

      Displays a rounded-style border for the text field.

      Available in iOS 2.0 and later.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    enum UITextFieldViewMode : Int { case Never case WhileEditing case UnlessEditing case Always }

    Objective-C

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

    Constants

    • Never

      UITextFieldViewModeNever

      The overlay view never appears.

      Available in iOS 2.0 and later.

    • WhileEditing

      UITextFieldViewModeWhileEditing

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

      Available in iOS 2.0 and later.

    • UnlessEditing

      UITextFieldViewModeUnlessEditing

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

      Available in iOS 2.0 and later.

    • Always

      UITextFieldViewModeAlways

      The overlay view is always displayed.

      Available in iOS 2.0 and later.

    Import Statement

    import UIKit

    Availability

    Available in iOS 2.0 and later.