UITabBarItem Class Reference

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

Overview

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

Tasks

Initializing an Item

Getting and Setting Properties

Customizing Appearance

Managing the Finished Selected Image

Properties

badgeValue

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

@property(nonatomic, copy) NSString *badgeValue
Discussion

The default value is nil.

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

selectedImage

The image displayed when the tab bar item is selected.

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

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

Instance Methods

initWithTabBarSystemItem:tag:

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

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

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

initWithTitle:image:selectedImage:

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

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

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

initWithTitle:image:tag:

Creates and returns a new item using the specified properties.

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

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

setTitlePositionAdjustment:

Sets the offset to use to adjust the title position.

- (void)setTitlePositionAdjustment:(UIOffset)adjustment
Parameters
adjustment

The offset to use to adjust the title position.

Availability
  • Available in iOS 5.0 and later.
Declared In
UITabBarItem.h

titlePositionAdjustment

Returns the offset to use to adjust the title position.

- (UIOffset)titlePositionAdjustment
Return Value

The offset to use to adjust the title position.

Availability
  • Available in iOS 5.0 and later.
Declared In
UITabBarItem.h

Constants

UITabBarSystemItem

System items that can be used on a tab bar.

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

The more system item. more item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

UITabBarSystemItemFavorites

The favorites system item. favorites item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

UITabBarSystemItemFeatured

The featured system item. featured item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

UITabBarSystemItemTopRated

The top rated system item. top-rated item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

UITabBarSystemItemRecents

The recents system item. recents item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

UITabBarSystemItemContacts

The contacts system item. contacts item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

UITabBarSystemItemHistory

The history system item. history item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

UITabBarSystemItemBookmarks

The bookmarks system item. bookmarks item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

UITabBarSystemItemSearch

The search system item. search item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

UITabBarSystemItemDownloads

The downloads system item. downloads item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

UITabBarSystemItemMostRecent

The most recent system item. most recent item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

UITabBarSystemItemMostViewed

The most viewed system item. most viewed item

Available in iOS 2.0 and later.

Declared in UITabBarItem.h.

Discussion

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

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