iOS Developer Library

Developer

UIKit Framework Reference UILabel Class Reference

Options
Deployment Target:

On This Page
Language:

UILabel

Inheritance


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later.

The UILabel class implements a read-only text view. You can use this class to draw one or multiple lines of static text, such as those you might use to identify other parts of your user interface. The base UILabel class provides support for both simple and complex styling of the label text. You can also control over aspects of appearance, such as whether the label uses a shadow or draws with a highlight. If needed, you can customize the appearance of your text further by subclassing.

The default content mode of the UILabel class is UIViewContentModeRedraw. This mode causes the view to redraw its contents every time its bounding rectangle changes. You can change this mode by modifying the inherited contentMode property of the class.

New label objects are configured to disregard user events and clip subviews by default. If you want to handle events in a custom subclass of UILabel, you must explicitly change the value of the userInteractionEnabled property to YEStrue after initializing the object. If you want to allow subviews to extend beyond the bounds of a label, you must explicitly change the value of the label’s clipsToBounds property to NOfalse.

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

For more information about appearance and behavior configuration, see Labels in UIKit User Interface Catalog.

  • text text Property

    The text displayed by the label.

    Declaration

    Swift

    var text: String?

    Objective-C

    @property(nonatomic, copy) NSString *text

    Discussion

    This string is nil 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 label styles the new string using the shadowColor, textAlignment, and other style-related properties of the class.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The styled text displayed by the label.

    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.

    To turn on auto-kerning in the label, set NSKernAttributeName of the string to [NSNull null].

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • font font Property

    The font of the text.

    Declaration

    Swift

    var font: UIFont!

    Objective-C

    @property(nonatomic, retain) UIFont *font

    Discussion

    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 label. If you are not using styled text, this property applies to the entire text string in the text property.

    The default value for this property is the system font at a size of 17 points (using the systemFontOfSize: class method of UIFont). The value for the property can only be set to a non-nil value; setting this property to nil raises an exception.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    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

    If you are using styled text in iOS 6 or later, assigning a new value to this property causes the 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 label. If you are not using styled text, this property applies to the entire text string in the text property.

    The default value for this property is a black color (set through the blackColor class method of UIColor). The value for the property can only be set to a non-nil value; setting this property to nil raises an exception.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    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

    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 label. If you are not using styled text, this property applies to the entire text string in the text property.

    The default value of this property is NSTextAlignmentLeft.

    Special Considerations

    In iOS 5 and earlier, the type of this property was UITextAlignment.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The technique to use for wrapping and truncating the label’s text.

    Declaration

    Swift

    var lineBreakMode: NSLineBreakMode

    Objective-C

    @property(nonatomic) NSLineBreakMode lineBreakMode

    Discussion

    If you are not using styled text, this property applies to the entire text string in the text property. If you are using styled text in iOS 6 or later, assigning a new value to this property causes the line break mode to be applied to the entirety of the string in the attributedText property. If you want to apply the line break mode to only a portion of the text, create a new attributed string with the desired style information and associate it with the label. However, NSParagraphStyle properties, such as those defined by NSLineBreakMode, apply to entire paragraphs (as defined for paragraphRangeForRange:), not words within paragraphs.

    This property is in effect both during normal drawing and in cases where the font size must be reduced to fit the label’s text in its bounding box. This property is set to NSLineBreakByTruncatingTail by default.

    Special Considerations

    In iOS 5 and earlier, the type of this property was UILineBreakMode.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • enabled enabled Property

    The enabled state to use when drawing the label’s text.

    Declaration

    Swift

    var enabled: Bool

    Objective-C

    @property(nonatomic, getter=isEnabled) BOOL enabled

    Discussion

    This property determines only how the label is drawn. Disabled text is dimmed somewhat to indicate it is not active. This property is set to YEStrue by default.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var adjustsFontSizeToFitWidth: Bool

    Objective-C

    @property(nonatomic) BOOL adjustsFontSizeToFitWidth

    Discussion

    Normally, the label text is drawn with the font you specify in the font property. If this property is set to YEStrue, however, and the text in the text property exceeds the label’s bounding rectangle, the receiver starts reducing the font size until the string fits or the minimum font size is reached. In iOS 6 and earlier, this property is effective only when the numberOfLines property is set to 1.

    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

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value indicating whether spacing between letters should be adjusted to fit the string within the label’s bounds rectangle.

    Deprecation Statement

    Hand tune instead by using NSKernAttributeName to affect tracking.

    Declaration

    Objective-C

    @property(nonatomic) BOOL adjustsLetterSpacingToFitWidth

    Discussion

    When this property is YEStrue, the label may alter the letter spacing of the label text to make that text fit better within the label’s bounds. This property is applied to the string regardless of the current line break mode. The default value of this property is NOfalse.

    If the value of this property to YEStrue, the label to ignore values value returned by the tighteningFactorForTruncation method of any NSParagraphStyle objects associated with the label text.

    Import Statement

    Objective-C

    @import UIKit;

    Availability

    Available in iOS 6.0 and later.

    Deprecated in iOS 7.0.

  • Controls how text baselines are adjusted when text needs to shrink to fit in the label.

    Declaration

    Swift

    var baselineAdjustment: UIBaselineAdjustment

    Objective-C

    @property(nonatomic) UIBaselineAdjustment baselineAdjustment

    Discussion

    If the adjustsFontSizeToFitWidth property is set to YEStrue, this property controls the behavior of the text baselines in situations where adjustment of the font size is required. The default value of this property is UIBaselineAdjustmentAlignBaselines. This property is effective only when the numberOfLines property is set to 1.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The minimum scale factor supported for the label’s text.

    Declaration

    Swift

    var minimumScaleFactor: CGFloat

    Objective-C

    @property(nonatomic) CGFloat minimumScaleFactor

    Discussion

    Use this property to specify the smallest multiplier for the current font size that yields an acceptable font size to use when displaying the label’s text. If you specify a value of 0 for this property, the current font size is used as the smallest font size.

    The default value of this property is 0.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • minimumFontSize minimumFontSize (iOS 6.0) Property

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

    Deprecation Statement

    Use minimumScaleFactor instead.

    Declaration

    Objective-C

    @property(nonatomic) CGFloat minimumFontSize

    Discussion

    When drawing text that might not fit within the bounding rectangle of the label, 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 label, you should always increase this value. This property is effective only when the numberOfLines property is set to 1.

    Import Statement

    Objective-C

    @import UIKit;

    Availability

    Available in iOS 2.0 and later.

    Deprecated in iOS 6.0.

  • The maximum number of lines to use for rendering text.

    Declaration

    Swift

    var numberOfLines: Int

    Objective-C

    @property(nonatomic) NSInteger numberOfLines

    Discussion

    This property controls the maximum number of lines to use in order to fit the label’s text into its bounding rectangle. The default value for this property is 1. To remove any maximum limit, and use as many lines as needed, set the value of this property to 0.

    If you constrain your text using this property, any text that does not fit within the maximum number of lines and inside the bounding rectangle of the label is truncated using the appropriate line break mode.

    When the receiver is resized using the sizeToFit method, resizing takes into account the value stored in this property. For example, if this property is set to 3, the sizeToFit method resizes the receiver so that it is big enough to display three lines of text.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The highlight color applied to the label’s text.

    Declaration

    Swift

    var highlightedTextColor: UIColor?

    Objective-C

    @property(nonatomic, retain) UIColor *highlightedTextColor

    Discussion

    Subclasses that use labels to implement a type of text button can use the value in this property when drawing the pressed state for the button. This color is applied to the label automatically whenever the highlighted property is set to YEStrue.

    The default value of this property is nil .

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    highlighted

  • A Boolean value indicating whether the receiver should be drawn with a highlight.

    Declaration

    Swift

    var highlighted: Bool

    Objective-C

    @property(nonatomic, getter=isHighlighted) BOOL highlighted

    Discussion

    Setting this property causes the receiver to redraw with the appropriate highlight state. A subclass implementing a text button might set this property to YEStrue when the user presses the button and set it to NOfalse at other times. In order for the highlight to be drawn, the highlightedTextColor property must contain a non-nil value.

    The default value of this property is NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The shadow color of the text.

    Declaration

    Swift

    var shadowColor: UIColor?

    Objective-C

    @property(nonatomic, retain) UIColor *shadowColor

    Discussion

    The default value for this property is nil, which indicates that no shadow is drawn. In addition to this property, you may also want to change the default shadow offset by modifying the shadowOffset property. Text shadows are drawn with the specified offset and color and no blurring.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    shadowOffset

  • The shadow offset (measured in points) for the text.

    Declaration

    Swift

    var shadowOffset: CGSize

    Objective-C

    @property(nonatomic) CGSize shadowOffset

    Discussion

    The shadow color must be non-nil for this property to have any effect. The default offset size is (0, -1), which indicates a shadow one point above the text. Text shadows are drawn with the specified offset and color and no blurring.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    shadowColor

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

    Declaration

    Swift

    func textRectForBounds(_ bounds: CGRect, limitedToNumberOfLines numberOfLines: Int) -> CGRect

    Objective-C

    - (CGRect)textRectForBounds:(CGRect)bounds limitedToNumberOfLines:(NSInteger)numberOfLines

    Parameters

    bounds

    The bounding rectangle of the receiver.

    numberOfLines

    The maximum number of lines to use for the label. The value 0 indicates there is no maximum number of lines and that the rectangle should encompass all of the text.

    Return Value

    The computed drawing rectangle for the label’s text.

    Discussion

    This method should only be overridden by subclasses that want to change the receiver’s bounding rectangle before performing any other computations. Use the value in the numberOfLines parameter to limit the height of the returned rectangle to the specified number of lines of text.

    This method may be called by the system if there was a prior call to the sizeToFit or sizeThatFits: method. Note that labels in UITableViewCell objects are sized based on the cell dimensions, and not a requested size.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Draws the receiver’s text (or its shadow) 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. This method should only be overridden by subclasses that want to modify the default drawing behavior for the label’s text.

    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

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • The preferred maximum width (in points) for a multiline label.

    Declaration

    Swift

    var preferredMaxLayoutWidth: CGFloat

    Objective-C

    @property(nonatomic) CGFloat preferredMaxLayoutWidth

    Discussion

    This property affects the size of the label when layout constraints are applied to it. During layout, if the text extends beyond the width specified by this property, the additional text is flowed to one or more new lines, thereby increasing the height of the label.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • A Boolean value that determines whether user events are ignored and removed from the event queue.

    Declaration

    Swift

    var userInteractionEnabled: Bool

    Objective-C

    @property(nonatomic, getter=isUserInteractionEnabled) BOOL userInteractionEnabled

    Discussion

    This property is inherited from the UIView parent class. This class changes the default value of this property to NOfalse.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    userInteractionEnabled (UIView)

  • A Boolean value that determines whether subviews are confined to the bounds of the view.

    Declaration

    Objective-C

    @property(nonatomic) BOOL clipsToBounds

    Discussion

    This property is inherited from the UIView parent class. This class changes the default value of this property to YEStrue.

    See Also

    clipsToBounds (UIView)