iOS Developer Library

Developer

UIKit Framework Reference UITabBar Class Reference

Options
Deployment Target:

On This Page
Language:

UITabBar

A UITabBar object is a control for selecting between different subtasks, views, or modes in an app. Normally, you use tab bars in conjunction with a UITabBarController object, but you can also use them as standalone controls in your app. Tab bars always appear across the bottom edge of the screen and display the contents of one or more UITabBarItem objects. A tab bar’s appearance can be customized with a background image or tint color to suit the needs of your interface. Tapping an item selects and highlights that item, and you use the selection of the item to enable the corresponding mode for your app.

You can configure tab bars programmatically or in Interface Builder. A UITabBarController object provides its own tab bar object and you must configure the object provided to you. When creating a tab bar programmatically, use the initWithFrame: method or another view initializer method to set its initial configuration. Use the methods of this class to configure the appearance of the tab bar. For tab bars you create yourself, you also use the methods of this class to specify the items displayed by the tab bar.

A tab bar reports selections and user customizations to its delegate object. For tab bars you create yourself, use the delegate to respond to selections or to the addition, removal, or reordering of items in the tab bar. (A UITabBarController object acts as the delegate for the tab bar it manages.) For more information on implementing a tab bar delegate, see UITabBarDelegate Protocol Reference.

Configuring the Items of a Tab Bar

You can configure tab bar items using Interface Builder or create and configure them programmatically in your code. Tab bars in Interface Builder come preconfigured with some initial items and you can add, remove, or reorder items as needed. How you configure items at design time depends on whether your tab bar is associated with a UITabBarController object:

  • Configuring your tab bar in Interface Builder:

    • When a UITabBarController object is present, add or remove view controllers to your scene and create relationship segues between the tab bar controller and each new view controller. Creating a relationship segue automatically adds a new item to the tab bar, and deleting an existing relationship segue removes the corresponding tab bar item.

    • When a tab bar controller is not present, drag tab bar items from the library onto your tab bar.

  • Configuring your tab bar programmatically:

    • To configure the tab bar associated with a UITabBarController object, configure the view controllers associated with the tab bar controller. The tab bar automatically obtains its items from the tabBarItem property of each view controller associated with the tab bar controller.

    • To configure tab bar items directly, use the setItems:animated: method of the tab bar itself.

A tab bar displays all of its tabs onscreen at once, using the itemPositioning property to determine how to position items in the available space. If you have more items than can fit in the available space, display only a subset of them and let the user select which tabs are displayed. The beginCustomizingItems: method displays an interface for selecting which tab bar items to display.

The contents of each item are stored in a UITabBarItem object. Each item contains a title and an image to display in the tab. You can also use tab bar items to add a badge to the corresponding tab. For more information about creating and configuring items, see UITabBarItem Class Reference.

Responding to Tab Selections

For tab bars with an associated tab bar controller, the tab bar controller automatically manages selections and displays the appropriate view controller. The only time you have to manage selections yourself is when you create the tab bar without a tab bar controller. The tab bar reports selections to the tabBar:didSelectItem: method of its delegate object, which you can use to respond to selection changes. For more information about implementing the delegate object, see UITabBarDelegate Protocol Reference.

Interface Builder Attributes

Table 1 lists the attributes that you configure for tab bars in Interface Builder.

Table 1Tab bar attributes

Attribute

Discussion

Background

The background image to display for the bar. If you specify a stretchable image, the image is stretched to fit the available space; otherwise, the image is tiled. When you configure a background image, the tab bar ignores the tint color information. To set this attribute programmatically, use the backgroundImage property.

Shadow

The custom shadow image for the tab bar. This attribute is ignored if the tab bar does not also have a custom background image. To set this attribute programmatically, use the shadowImage property.

Selection

The image to use for the selected tab. To set this attribute programmatically, use the selectionIndicatorImage property.

Image Tint

The tint color to apply to the selected item. To set this attribute programmatically, use the tintColor property.

Style

The basic style to apply to the bar. You can configure a tab bar with a dark or light style and the bar can be opaque or translucent. To set the style programmatically, use the barStyle and translucent properties.

Bar Tint

The tint color to apply to the bar. To set this attribute programmatically, use the barTintColor property.

Item Positioning

The positioning scheme to apply to items. Use this attribute to configure how items are spaced across the length of the tab bar. To set this attribute programmatically, use the itemPositioning property.

Internationalization

To internationalize a tab bar, you must provide localized strings for the tab bar item titles.

For more information, see Internationalization and Localization Guide.

Accessibility

Tab bars are accessible by default.

With VoiceOver enabled on an iOS device, when a user touches a tab in a tab bar, VoiceOver reads the title of the tab, its position in the bar, and whether it is selected. For example in the iTunes app on iPad, you might hear “Selected, Audiobooks, four of seven” or “Genius, six of seven.”

For general information about making your interface accessible, see Accessibility Programming Guide for iOS.

  • The items displayed by the tab bar.

    Declaration

    Swift

    var items: [UITabBarItem]?

    Objective-C

    @property(nonatomic, copy) NSArray <UITabBarItem *> *items

    Discussion

    This property contains an array of UITabBarItem objects, each of which corresponds to a tab displayed by the tab bar. The order of the items in this property corresponds to the order of the items onscreen. You can use this property to access the items as needed.

    For tab bars you create, you can assign a new set of items to this property to change the displayed items. Changing the items replaces them immediately without animations. You must not modify this property if the tab bar is managed by a UITabBarController object, and doing so raises an exception. When the tab bar is owned by a tab bar controller, use the tab bar controller’s methods to make changes.

    The default value of this property is nil.

    Availability

    Available in iOS 2.0 and later.

  • Sets the items on the tab bar, optionally animating any changes into position.

    Declaration

    Swift

    func setItems(_ items: [UITabBarItem]?, animated animated: Bool)

    Objective-C

    - (void)setItems:(NSArray<UITabBarItem *> *)items animated:(BOOL)animated

    Parameters

    items

    The array of UITabBarItem objects to display.

    animated

    A Boolean indicating whether changes should be animated. Specify YEStrue to animate changes or NOfalse to display the new items without animations. When animations are enabled, the tab bar fades out removed items and fades in new items, adjusting the spacing between items as needed.

    Discussion

    Use this method to make changes to the currently visible items at runtime. Calling this method on a tab bar that is managed by a UITabBarController object raises an exception. When the tab bar is owned by a tab bar controller, use the tab bar controller’s methods to make changes to items.

    Availability

    Available in iOS 2.0 and later.

  • The currently selected item on the tab bar.

    Declaration

    Swift

    unowned(unsafe) var selectedItem: UITabBarItem?

    Objective-C

    @property(nonatomic, assign) UITabBarItem *selectedItem

    Discussion

    Use this property to get the currently selected item. If you change the value of this property, the tab bar selects the corresponding item and updates the tab bar’s appearance accordingly. Set the property to nil to clear the selection.

    When an item is selected, the tab bar displays the image in the tab bar item’s selectedImage property. If the selectedImageTintColor property is set, the tab bar also applies the color in that property to the selected image. 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.

  • The tab bar style that specifies its appearance.

    Declaration

    Swift

    var barStyle: UIBarStyle

    Objective-C

    @property(nonatomic) UIBarStyle barStyle

    Discussion

    This property determines whether the tab bar uses a dark or light visual style when no background image or tint color is specified. Together with the translucent property, this property defines the default visual style of the tab bar. Set this property to the value that best matches the style of your interface. For a list of possible values, see UIBarStyle. The default value of this property is UIBarStyleDefault.

    Availability

    Available in iOS 7.0 and later.

  • A Boolean value that indicates whether the tab bar is translucent.

    Declaration

    Swift

    var translucent: Bool

    Objective-C

    @property(nonatomic, getter=isTranslucent) BOOL translucent

    Discussion

    When the value of this property is YEStrue, the tab bar adds a translucent effect to its background image or tint color. When translucency is enabled, part of the tab bar’s underlying content is able to show through, although the amount that shows through depends on the rest of the tab bar configuration. For example, a background image can wholly or partially obscure the background content. Setting this property to NOfalse causes the tab bar to render its bar tint color or background image on top of an opaque backdrop.

    The default value of this property is dependent on the configuration of the tab bar:

    • The default value is YEStrue when the tab bar does not have a custom background image.

    • The default value is YEStrue when a custom background image contains any transparency—that is, at least one pixel has an alpha value of less than 1.0.

    • The default value is NOfalse when the custom background image is completely opaque—that is, all pixels have an alpha value of 1.0.

    Availability

    Available in iOS 7.0 and later.

  • The tint color to apply to the tab bar background.

    Declaration

    Swift

    var barTintColor: UIColor?

    Objective-C

    @property(nonatomic, strong) UIColor *barTintColor

    Discussion

    Use this property to specify a custom color for the tab bar’s background. The color you specify replaces the appearance provided by the barStyle property.

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    var itemPositioning: UITabBarItemPositioning

    Objective-C

    @property(nonatomic) UITabBarItemPositioning itemPositioning

    Discussion

    The default value for this property, UITabBarItemPositioningAutomatic, results in the default tab bar item positioning according to the current environment:

    • In a horizontally compact environment, the tab bar spreads items across the entire space, adjusting inter-item spacing as needed.

    • In a horizontally regular environment, the tab bar uses the itemWidth and itemSpacing properties to set the width of items and the spacing between items, positioning those items in the center of the available space. This configuration has the potential to leave space along the left and right edges of the tab bar.

    You can force a specific positioning scheme by changing the value of this property to a different value. For a list of possible values, see the constant descriptions for the UITabBarItemPositioning type.

    Availability

    Available in iOS 7.0 and later.

  • The amount of space (in points) to use between tab bar items.

    Declaration

    Swift

    var itemSpacing: CGFloat

    Objective-C

    @property(nonatomic) CGFloat itemSpacing

    Discussion

    When the tab bar positions items using the UITabBarItemPositioningCentered option, it checks the value of this property to see if a custom spacing value has been supplied. The default value of this property is 0, which causes the tab bar to use a system-defined default spacing value. Specifying a value greater than 0 causes the tab bar to use your custom value instead. If you try to set this property to a negative value, the tab bar sets the value to 0 instead.

    Availability

    Available in iOS 7.0 and later.

  • The width (in points) of tab bar items.

    Declaration

    Swift

    var itemWidth: CGFloat

    Objective-C

    @property(nonatomic) CGFloat itemWidth

    Discussion

    When the tab bar positions items using the UITabBarItemPositioningCentered option, it checks the value of this property to see if a custom width value has been supplied. The default value of this property is 0, which causes the tab bar to use a system-defined default width for each item. Specifying a value greater than 0 causes the tab bar to use your custom value instead. If you try to set this property to a negative value, the tab bar sets the value to 0 instead.

    Availability

    Available in iOS 7.0 and later.

  • The tint color to apply to the tab bar items.

    Declaration

    Swift

    var tintColor: UIColor!

    Objective-C

    @property(nonatomic, strong) UIColor *tintColor

    Discussion

    Assigning a value to this property applies the specified color only to the tab bar’s items. Even if you do not specify a color, the tab bar may tint items using the tint color of one of its ancestor views. For information on how tinting colors are applied to views in a view hierarchy, see the description of the tintColor property in UIView Class Reference.

    Availability

    Available in iOS 5.0 and later.

  • The custom background image for the tab bar.

    Declaration

    Swift

    var backgroundImage: UIImage?

    Objective-C

    @property(nonatomic, strong) UIImage *backgroundImage

    Discussion

    If you specify a stretchable background image, the tab bar stretches your image to fill the available space. If your image is not stretchable and not large enough to fill the available space, the tab bar tiles the image. For information about how stretching works, see the UIImageResizingMode type in UIImage Class Reference.

    When a custom background image is present, the tab bar does not draw any blur effects behind itself, even when the translucent property is YEStrue.

    Availability

    Available in iOS 5.0 and later.

  • The shadow image to use for the tab bar.

    Declaration

    Swift

    var shadowImage: UIImage?

    Objective-C

    @property(nonatomic, strong) UIImage *shadowImage

    Discussion

    For tab bars with custom backgrounds, you can use this property to specify a custom shadow image for your bar. The shadow image is positioned outside the bounds of the tab bar itself, usually above or below the tab bar’s frame rectangle. The exact position depends on the current platform. For example, shadow images are positioned above the tab bar on iPhone and iPad.

    You must use this property in conjunction with a custom background image. If the backgroundImage property is nil, the tab bar ignores the value in this property and uses a default shadow.

    Availability

    Available in iOS 6.0 and later.

  • The image to use for the selection indicator.

    Declaration

    Swift

    var selectionIndicatorImage: UIImage?

    Objective-C

    @property(nonatomic, strong) UIImage *selectionIndicatorImage

    Discussion

    Use this property to specify a custom selection image. Your image is rendered on top of the tab bar but behind the contents of the tab bar item itself. The default value of this property is nil, which causes the tab bar to apply a default highlight to the selected item.

    Availability

    Available in iOS 5.0 and later.

  • The tab bar’s delegate object.

    Declaration

    Swift

    unowned(unsafe) var delegate: UITabBarDelegate?

    Objective-C

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

    Discussion

    Use the delegate to track the selection of tab bar items and to respond to the user customization of the tab bar. The default value of this property is nil.

    For more information on how to implement the methods of this protocol, see UITabBarDelegate Protocol Reference.

    Availability

    Available in iOS 2.0 and later.

  • Presents a standard interface that lets the user customize the contents of the tab bar.

    Declaration

    Swift

    func beginCustomizingItems(_ items: [UITabBarItem])

    Objective-C

    - (void)beginCustomizingItems:(NSArray<UITabBarItem *> *)items

    Parameters

    items

    An array of UITabBarItem objects representing all of the items that can possibly be displayed on the tab bar. Always include at least one visible item in the tab bar. This parameter must not be nil or contain an empty array.

    Discussion

    This method presents a custom interface that lets the user replace existing tab bar items with items in the specified array. The interface also lets the user rearrange items on the tab bar, but it does not let the user change the total number of items. The interface includes a Done button that automatically dismisses the interface. You can also dismiss the interface programmatically using the endCustomizingAnimated: method.

    The items parameter should include all items currently visible in the tab bar that you allow to be replaced. Any currently visible items that are not included in this array remain fixed in place on the tab bar and cannot be repositioned or replaced by the user. If the user removes the currently selected item from the tab bar, the selectedItem property is set to nil.

    The tab bar notifies its delegate about the pending customizations at various points during the presentation and dismissal of the interface. If you want to track when customizations begin and end, provide a delegate and assign it to the tab bar’s delegate property. For more information about the methods you can implement, see UITabBarDelegate Protocol Reference.

    Availability

    Available in iOS 2.0 and later.

  • Dismisses the standard interface used to customize the tab bar.

    Declaration

    Swift

    func endCustomizingAnimated(_ animated: Bool) -> Bool

    Objective-C

    - (BOOL)endCustomizingAnimated:(BOOL)animated

    Parameters

    animated

    If YEStrue, animate the dismissal of the interface.

    Return Value

    YEStrue if items on the tab bar changed or NOfalse if they did not.

    Discussion

    You rarely need to call this method. Typically, the user dismisses the modal view by tapping the built-in Done button in the interface. However, you might call this method to cancel the customization process because of changes to other parts of your interface.

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func isCustomizing() -> Bool

    Objective-C

    - (BOOL)isCustomizing

    Return Value

    YEStrue if the user is currently customizing the tab bar or NOfalse if they are not.

    Availability

    Available in iOS 2.0 and later.

  • The tint color applied to the selected tab bar item.

    Deprecation Statement

    Use the tintColor property instead.

    Declaration

    Swift

    var selectedImageTintColor: UIColor?

    Objective-C

    @property(nonatomic, strong) 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.

    Deprecated in iOS 8.0.

  • Constants that specify tab bar item positioning.

    Declaration

    Swift

    enum UITabBarItemPositioning : Int { case Automatic case Fill case Centered }

    Objective-C

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

    Constants

    • automatic

      UITabBarItemPositioningAutomatic

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

      • In a horizontally compact environment, the tab bar spreads items across the entire space, adjusting inter-item spacing as needed.

      • In a horizontally regular environment, the tab bar uses the itemWidth and itemSpacing properties to set the width of items and the spacing between items, positioning those items in the center of the available space. This configuration has the potential to leave space along the left and right edges of the tab bar.

      Available in iOS 7.0 and later.

    • fill

      UITabBarItemPositioningFill

      Distribute items across the entire width of the tab bar. When the UITabBarItemPositioningAutomatic option is selected, the tab bar uses this behavior in horizontally compact environments.

      Available in iOS 7.0 and later.

    • centered

      UITabBarItemPositioningCentered

      Center items in the available space. With this option, the tab bar uses the itemWidth and itemSpacing properties to set the width of items and the spacing between items, positioning those items in the center of the available space When the UITabBarItemPositioningAutomatic option is selected, the tab bar uses this behavior in horizontally regular environments.

      Available in iOS 7.0 and later.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.