iOS Developer Library

Developer

UIKit Framework Reference UITabBarItem Class Reference

Options
Deployment Target:

On This Page
Language:

UITabBarItem

Inherits From


Conforms To


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later

The UITabBarItem class implements an item on a UITabBar object. A tab bar operates strictly in radio mode, where one item is selected at a time—tapping a tab bar item toggles the view above the tab bar. You can also specify a badge value on the tab bar item for adding additional visual information—for example, the Messages app uses a badge on the item to show the number of new messages. This class also provides a number of system defaults for creating items.

Use the initWithTabBarSystemItem:tag: method to create one of the system items. Use the initWithTitle:image:tag: method to create a custom item with the specified title and image, which is used as both the unselected and selected image. Use the initWithTitle:image:selectedImage: method to create a custom item with the specified title, unselected image, and selected image.

Customizing Appearance

In iOS v5.0 and later, you can customize the appearance of tab bars by setting item label text attributes using appearance selectors declared by UIBarItem. You can also use the methods listed in Customizing Appearance. You can customize the appearance of all tab bar items using the appearance proxy (for example, [UITabBarItem appearance]), or just of a single tab bar item.

By default, unselected and selected images are automatically created from the alpha values in the source images. To prevent system coloring, provide images with UIImageRenderingModeAlwaysOriginal.

For more information about appearance and behavior configuration, see Tab Bars.

  • Creates and returns a new item containing the specified system item.

    Declaration

    Swift

    init(tabBarSystemItem systemItem: UITabBarSystemItem, tag tag: Int)

    Objective-C

    - (instancetype)initWithTabBarSystemItem:(UITabBarSystemItem)systemItem tag:(NSInteger)tag

    Parameters

    systemItem

    The system item to use as the first item on the tab bar. One of the constants defined in UITabBarSystemItem.

    tag

    The receiver’s tag, an integer that you can use to identify bar item objects in your application.

    Return Value

    A newly initialized item containing the specified system item. The item’s target is nil.

    Discussion

    This method returns a system-supplied tab bar item. The title and image properties of the returned item cannot be changed later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

  • Creates and returns a new item using the specified properties.

    Declaration

    Swift

    init(title title: String?, image image: UIImage?, tag tag: Int)

    Objective-C

    - (instancetype)initWithTitle:(NSString *)title image:(UIImage *)image tag:(NSInteger)tag

    Parameters

    title

    The item’s title. If nil, a title is not displayed.

    image

    The item’s image. If nil, an image is not displayed.

    tag

    The receiver’s tag, an integer that you can use to identify bar item objects in your application.

    Return Value

    Newly initialized item with the specified properties.

    Discussion

    The images displayed on the tab bar item are derived from image. You can specify a different source image for the selected image using the selectedImage property.

    By default, the actual unselected and selected images are automatically created from the alpha values in the source images. To prevent system coloring, provide images with UIImageRenderingModeAlwaysOriginal.

    If the image is too large to fit on the tab bar, it is clipped to fit. The size of a tab bar image is typically 60 x 60 pixels. See Custom Icon and Image Creation Guidelines for more information about tab bar icons.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

  • Creates and returns a new item with the specified title, unselected image, and selected image.

    Declaration

    Swift

    init(title title: String?, image image: UIImage?, selectedImage selectedImage: UIImage?)

    Objective-C

    - (instancetype)initWithTitle:(NSString *)title image:(UIImage *)image selectedImage:(UIImage *)selectedImage

    Parameters

    title

    The item’s title. If nil, a title is not displayed.

    image

    The item’s unselected image. If nil, an image is not displayed.

    selectedImage

    The item’s selected image. If nil, uses the value of image.

    Return Value

    Newly initialized item with the specified title, unselected image, and selected image.

    Discussion

    If no selectedImage is provided, image is used as both the unselected and selected image.

    By default, the actual unselected and selected images are automatically created from the alpha values in the source images. To prevent system coloring, provide images with UIImageRenderingModeAlwaysOriginal.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later

  • Text that is displayed in the upper-right corner of the item with a surrounding red oval.

    Declaration

    Swift

    var badgeValue: String?

    Objective-C

    @property(nonatomic, copy) NSString *badgeValue

    Discussion

    The default value is nil.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later

  • The image displayed when the tab bar item is selected.

    Declaration

    Swift

    var selectedImage: UIImage!

    Objective-C

    @property(nonatomic, retain) UIImage *selectedImage

    Discussion

    If nil, the value from the image property on the superclass, UIBarItem, is used as both the unselected and selected image.

    By default, the actual selected image is automatically created from the alpha values in the source image. To prevent system coloring, provide images with UIImageRenderingModeAlwaysOriginal.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later

  • Returns the offset to use to adjust the title position.

    Declaration

    Swift

    func titlePositionAdjustment() -> UIOffset

    Objective-C

    - (UIOffset)titlePositionAdjustment

    Return Value

    The offset to use to adjust the title position.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later

  • Sets the offset to use to adjust the title position.

    Declaration

    Swift

    func setTitlePositionAdjustment(_ adjustment: UIOffset)

    Objective-C

    - (void)setTitlePositionAdjustment:(UIOffset)adjustment

    Parameters

    adjustment

    The offset to use to adjust the title position.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later

Data Types

  • System items that can be used on a tab bar.

    Declaration

    Swift

    enum UITabBarSystemItem : Int { case More case Favorites case Featured case TopRated case Recents case Contacts case History case Bookmarks case Search case Downloads case MostRecent case MostViewed }

    Objective-C

    typedef enum { UITabBarSystemItemMore, UITabBarSystemItemFavorites, UITabBarSystemItemFeatured, UITabBarSystemItemTopRated, UITabBarSystemItemRecents, UITabBarSystemItemContacts, UITabBarSystemItemHistory, UITabBarSystemItemBookmarks, UITabBarSystemItemSearch, UITabBarSystemItemDownloads, UITabBarSystemItemMostRecent, UITabBarSystemItemMostViewed, } UITabBarSystemItem;

    Constants

    • More

      UITabBarSystemItemMore

      The more system item. image: ../Art/UITabBarMore.png

      Available in iOS 2.0 and later

    • Favorites

      UITabBarSystemItemFavorites

      The favorites system item. image: ../Art/UITabBarFavorites.png

      Available in iOS 2.0 and later

    • Featured

      UITabBarSystemItemFeatured

      The featured system item. image: ../Art/UITabBarFeatured.png

      Available in iOS 2.0 and later

    • TopRated

      UITabBarSystemItemTopRated

      The top rated system item. image: ../Art/UITabBarTopRated.png

      Available in iOS 2.0 and later

    • Recents

      UITabBarSystemItemRecents

      The recents system item. image: ../Art/UITabBarRecents.png

      Available in iOS 2.0 and later

    • Contacts

      UITabBarSystemItemContacts

      The contacts system item. image: ../Art/UITabBarContacts.png

      Available in iOS 2.0 and later

    • History

      UITabBarSystemItemHistory

      The history system item. image: ../Art/UITabBarHistory.png

      Available in iOS 2.0 and later

    • Bookmarks

      UITabBarSystemItemBookmarks

      The bookmarks system item. image: ../Art/UITabBarBookmarks.png

      Available in iOS 2.0 and later

    • Search

      UITabBarSystemItemSearch

      The search system item. image: ../Art/UITabBarSearch.png

      Available in iOS 2.0 and later

    • Downloads

      UITabBarSystemItemDownloads

      The downloads system item. image: ../Art/UITabBarDownloads.png

      Available in iOS 2.0 and later

    • MostRecent

      UITabBarSystemItemMostRecent

      The most recent system item. image: ../Art/UITabBarMostRecent.png

      Available in iOS 2.0 and later

    • MostViewed

      UITabBarSystemItemMostViewed

      The most viewed system item. image: ../Art/UITabBarMostViewed.png

      Available in iOS 2.0 and later

    Discussion

    The title and image of system tab bar items cannot be changed.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later