UITabBar Class Reference

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

Overview

A tab bar is a control, usually appearing across the bottom of the screen in the context of a tab bar controller, for giving the user one-tap, modal access to a set of views in an app. Each button in a tab bar is called a tab bar item and is an instance of the UITabBarItem class. If you instead want to give the user a bar of buttons that each perform an action, use a UIToolbar object.

The UITabBar class supports user customization of a tab bar by reordering, removing, and adding items to the bar. You can use a tab bar delegate to augment this behavior.

Use the UITabBarItem class to create items and the setItems:animated: method to add them to a tab bar. All methods with an animated: argument allow you to optionally animate changes to the display. Use the selectedItem property to access the current item.

Customizing Appearance

You can customize the appearance of tab bars using the methods listed in “Customizing Tab Bar Appearance.” You can customize the appearance of all tab bars in your app by using the appearance proxy (for example, [UITabBar appearance]), or of just a single tab bar.

For more on configuring appearance and behavior, see “Tab Bars”.

Tasks

Setting the Delegate

Configuring Tab Bar Items

Supporting User Customization of Tab Bars

Customizing Tab Bar Appearance

Properties

backgroundImage

The background image for the tab bar.

@property(nonatomic, retain) UIImage *backgroundImage
Discussion

A stretchable background image is stretched; a non-stretchable background image is tiled (refer to the UIImageResizingMode enum in UIImage Class Reference).

A tab bar with a custom background image, even when translucent, does not draw a blur behind itself.

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

barStyle

The tab bar style that specifies its appearance.

@property(nonatomic) UIBarStyle barStyle
Discussion

See UIBarStyle for possible values. The default value is UIBarStyleDefault.

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

barTintColor

The tint color to apply to the tab bar background.

@property(nonatomic, retain) UIColor *barTintColor
Discussion

This color is made translucent by default unless you set the translucent property to NO.

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

delegate

The tab bar’s delegate object.

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

The delegate should conform to the UITabBarDelegate protocol. Set this property to further modify the customizing behavior. The default value is nil.

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

itemPositioning

The positioning scheme for the tab bar items in the tab bar.

@property(nonatomic) UITabBarItemPositioning itemPositioning
Discussion

The default value for this property, UITabBarItemPositioningAutomatic, results in the default tab bar item positioning according to the device user interface idiom, as follows:

  • For the iPhone user interface idiom, tab bar items fill the tab bar horizontally, adjusting inter-item spacing as needed

  • For the iPad user interface item, tab bar items are positioned closely adjacent to each other with a default width and inter-item spacing (customizable with the itemWidth and itemSpacing properties), potentially leaving space in the tab bar at its left and right edges

If you don’t want to use automatic item positioning, you can force a positioning scheme by using this property, as follows:

  • To force tab bar items to fill all space horizontally, specify the UITabBarItemPositioningFill constant for this property

  • To force tab bar items to use a default inter-item width, potentially leaving empty space in the tab bar at its left and right sides, specify the UITabBarItemPositioningCentered constant for this property.

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

items

The items displayed on the tab bar.

@property(nonatomic, copy) NSArray *items
Discussion

The items, instances of UITabBarItem, that are visible on the tab bar in the order they appear in this array. Any changes to this property are not animated. Use the setItems:animated: method to animate changes.

The default value is nil.

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

itemSpacing

The custom inter-item spacing for tab bar items, in points, when using centered-style positioning.

@property(nonatomic) CGFloat itemSpacing
Discussion

To specify custom spacing between tab bar items when using the UITabBarItemPositioningCentered positioning option, set this property to a positive value, which the tab bar then uses directly. To specify system-defined spacing, use a 0 value, which is the default value for this property. (If you specify a negative value, a tab bar interprets it as 0 and employs system-defined spacing.)

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

itemWidth

The custom item width for tab bar items, in points, when using centered-style positioning.

@property(nonatomic) CGFloat itemWidth
Discussion

To specify a custom width for tab bar items when using the UITabBarItemPositioningCentered positioning option, set this property to a positive value, which the tab bar then uses directly. To specify system-defined tab bar item width, use a 0 value, which is the default value for this property. (If you specify a negative value, a tab bar interprets it as 0 and employs a system-defined width.)

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

selectedImageTintColor

The tint color applied to the selected tab bar item.

@property(nonatomic, retain) UIColor *selectedImageTintColor
Discussion

The default value is nil, which results in use of the tab bar’s tintColor property.

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

selectedItem

The currently selected item on the tab bar.

@property(nonatomic, assign) UITabBarItem *selectedItem
Discussion

Changing this property’s value provides visual feedback in the user interface, including the running of any associated animations. The selected item displays the tab bar item’s selectedImage image, using the tab bar’s selectedImageTintColor value. To prevent system coloring of an item, provide images using the UIImageRenderingModeAlwaysOriginal rendering mode.

The default value for this property is nil.

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

selectionIndicatorImage

The image used for the selection indicator.

@property(nonatomic, retain) UIImage *selectionIndicatorImage
Discussion

The selection indicator image is drawn on top of the tab bar, behind the bar item icon.

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

shadowImage

The shadow image to be used for the tab bar.

@property(nonatomic, retain) UIImage *shadowImage
Discussion

The default value is nil, which corresponds to the default shadow image. When non-nil, this property represents a custom shadow image to show instead of the default. For a custom shadow image to be shown, a custom background image must also be set using the backgroundImage property. If the default background image is used, then the default shadow image will be used regardless of the value of this property.

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

tintColor

The tint color to apply to the tab bar’s tab bar items.

@property(nonatomic, retain) UIColor *tintColor
Discussion

Starting in iOS 7.0, the tint color that applies to a tab bar’s tab bar items is the first nondefault tint color in the view hierarchy, starting with the tab bar itself. See the description of tintColor in UIView Class Reference for more information.

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

translucent

A Boolean value that indicates whether the tab bar is translucent (YES) or not (NO).

@property(nonatomic, getter=isTranslucent) BOOL translucent
Discussion

If the tab bar does not have a custom background image, the default value is YES.

If the tab bar does have a custom background image for which any pixel has an alpha value of less than 1.0, the default value is also YES. The default value is NO if the custom background image is entirely opaque.

If you set this property to YES on a tab bar with an opaque custom background image, the tab bar applies translucency to the image.

If you set this property to NO on a tab bar with a translucent custom background image, the tab bar provides an opaque background for your image and applies a blurring backdrop. The provided opaque background is black if the tab bar has UIBarStyleBlack style, white if the tab bar has UIBarStyleDefault, or the tab bar’s tint color (barTintColor) if you have defined one. The situation is identical if you set this property to NO for a tab bar without a custom background image, except the tab bar does not apply a blurring backdrop.

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

Instance Methods

beginCustomizingItems:

Presents a modal view allowing the user to customize the tab bar by adding, removing, and rearranging items on the tab bar.

- (void)beginCustomizingItems:(NSArray *)items
Parameters
items

The items to display on the modal view that can be rearranged.

The items parameter should contain all items that can be added to the tab bar. Visible items not in items are fixed in place—they can not be removed or replaced by the user.

Discussion

Use this method to start customizing a tab bar. For example, create an Edit button that invokes this method when tapped. A modal view appears displaying all the items in items with a Done button at the top. Tapping the Done button dismisses the modal view. If the selected item is removed from the tab bar, the selectedItem property is set to nil. Set the delegate property to an object conforming to the UITabBarDelegate protocol to further modify this behavior.

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

endCustomizingAnimated:

Dismisses the modal view used to modify items on the tab bar.

- (BOOL)endCustomizingAnimated:(BOOL)animated
Parameters
animated

If YES, animates the transition; otherwise, does not.

Return Value

YES if items on the tab bar changed; otherwise, NO.

Discussion

Typically, you do not need to use this method because the user dismisses the modal view by tapping the Done button.

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

isCustomizing

Returns a Boolean value indicating whether the user is customizing the tab bar.

- (BOOL)isCustomizing
Return Value

YES if the user is currently customizing the items on the tab bar; otherwise, NO. For example, by tapping an Edit button, a modal view appears allowing users to change the items on a tab bar. This method returns YES if this modal view is visible.

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

setItems:animated:

Sets the items on the tab bar, with or without animation.

- (void)setItems:(NSArray *)items animated:(BOOL)animated
Parameters
items

The items to display on the tab bar.

animated

If YES, animates the transition to the items; otherwise, does not.

Discussion

If animated is YES, the changes are dissolved or the reordering is animated—for example, removed items fade out and new items fade in. This method also adjusts the spacing between items.

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

Constants

UITabBarItemPositioning

Constants that specify tab bar item positioning.

typedef enum : NSInteger {
   UITabBarItemPositioningAutomatic,
   UITabBarItemPositioningFill,
   UITabBarItemPositioningCentered,
} UITabBarItemPositioning;
Constants
UITabBarItemPositioningAutomatic

Specifies automatic tab bar item positioning according to the user interface idiom, as follows:

  • For the iPhone user interface idiom, tab bar items fill the tab bar horizontally, adjusting inter-item spacing as needed

  • For the iPad user interface item, tab bar items are positioned closely adjacent to each other with a default width and inter-item spacing (customizable with the itemWidth and itemSpacing properties), potentially leaving space in the tab bar at its left and right edges

Available in iOS 7.0 and later.

Declared in UITabBar.h.

UITabBarItemPositioningFill

Default tab bar item positioning on iPhone. Specifies that tab bar items should be distributed to fill the width of the tab bar.

Available in iOS 7.0 and later.

Declared in UITabBar.h.

UITabBarItemPositioningCentered

Default tab bar item positioning on iPad. Specifies that tab bar items should be positioned closely adjacent to each other with a default width and inter-item spacing (customizable with the itemWidth and itemSpacing properties). The group of tab bar items is centered in the tab bar, potentially leaving space in the tab bar at its left and right edges.

Available in iOS 7.0 and later.

Declared in UITabBar.h.

Discussion

Starting in iOS 7, you can use these constants to specify tab bar item positioning style with the itemPositioning property.

When running on any iOS device, you can customize positioning with the itemWidth and itemSpacing properties when using the UITabBarItemPositioningCentered option. On iPad you can also customize positioning with those properties when using the UITabBarItemPositioningAutomatic option.