iOS Developer Library

Developer

UIKit Framework Reference UINavigationBar Class Reference

Options
Deployment Target:

On This Page
Language:

UINavigationBar

Inheritance


Import Statement


Swift

import UIKit

Objective-C

@import UIKit;

Availability


Available in iOS 2.0 and later.

The UINavigationBar class provides a control for navigating hierarchical content. It’s a bar, typically displayed at the top of the screen, containing buttons for navigating within a hierarchy of screens. The primary properties are a left (back) button, a center title, and an optional right button. You can use a navigation bar as a standalone object or in conjunction with a navigation controller object.

Using a Navigation Bar With a Navigation Controller

The most common way to use a navigation bar is in conjunction with a UINavigationController object. If you use a navigation controller to manage the navigation between different screens of content, the navigation controller creates the navigation bar automatically and pushes and pops navigation items when appropriate.

A navigation controller automatically assigns itself as the delegate of its navigation bar object. Therefore, when using a navigation controller, don’t assign a custom delegate object to the corresponding navigation bar.

For information about navigation controllers, see UINavigationController Class Reference.

Customizing the Appearance of a Navigation Bar

In iOS 5.0 and later, you can customize the appearance of the bar using the methods listed in Customizing the Bar Appearance. You can customize the appearance of all navigation bars using the appearance proxy ([UINavigationBar appearance]), or just of a single bar.

In iOS 7, a navigation bar’s tintColor affects the color of the back indicator image, button titles, and button images. The barTintColor property affects the color of the bar itself. Additionally, navigation bars are translucent by default. Turning the translucency off or on does not affect buttons, since they do not have backgrounds.

In general, when a property is dependent on the bar metrics (on the iPhone in landscape orientation, bars have a different height from standard), be sure to specify a value for UIBarMetricsDefault as well as for other metrics.

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

  • delegate delegate Property

    The navigation bar’s delegate object.

    Declaration

    Swift

    unowned(unsafe) var delegate: UINavigationBarDelegate?

    Objective-C

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

    Discussion

    The delegate should conform to the UINavigationBarDelegate protocol. The default value is nil.

    If the navigation bar was created by a navigation controller and is being managed by that object, you must not change the value of this property. Navigation controllers act as the delegate for any navigation bars they create.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Pushes the given navigation item onto the receiver’s stack and updates the navigation bar.

    Declaration

    Swift

    func pushNavigationItem(_ item: UINavigationItem, animated animated: Bool)

    Objective-C

    - (void)pushNavigationItem:(UINavigationItem *)item animated:(BOOL)animated

    Parameters

    item

    The navigation item to push on the stack.

    animated

    YEStrue if the navigation bar should be animated; otherwise, NOfalse.

    Discussion

    Pushing a navigation item displays the item’s title in the center on the navigation bar. The previous top navigation item (if it exists) is displayed as a back button on the left side of the navigation bar. If the new top item has a left custom view, it is displayed instead of the back button.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Pops the top item from the receiver’s stack and updates the navigation bar.

    Declaration

    Swift

    func popNavigationItemAnimated(_ animated: Bool) -> UINavigationItem?

    Objective-C

    - (UINavigationItem *)popNavigationItemAnimated:(BOOL)animated

    Parameters

    animated

    YEStrue if the navigation bar should be animated; otherwise, NOfalse.

    Return Value

    The top item that was popped.

    Discussion

    Popping a navigation item removes the top item from the stack and replaces it with the back item. The back item’s title is centered on the navigation bar and its other properties are displayed.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • Replaces the navigation items currently managed by the navigation bar with the specified items.

    Declaration

    Swift

    func setItems(_ items: [AnyObject]!, animated animated: Bool)

    Objective-C

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

    Parameters

    items

    The UINavigationItem objects to place in the stack. The front-to-back order of the items in this array represents the new bottom-to-top order of the items in the navigation stack. Thus, the last item added to the array becomes the top item of the navigation stack.

    animated

    If YEStrue, animate the pushing or popping of the top stack item. If NOfalse, replace the stack items without any animations.

    Discussion

    You can use this method to update or replace the navigation items in the stack without pushing or popping each item explicitly. In addition, this method lets you update the stack without animating the changes, which might be appropriate at launch time when you want to restore the state of the navigation stack to some previous state.

    If animations are enabled, this method decides which type of transition to perform based on whether the last item in the items array is already on the current navigation stack. If the item is currently on the stack, but is not the topmost item, this method uses a pop transition; if it is the topmost item, no transition is performed. If the item is not on the stack, this method uses a push transition. Only one transition is performed, but when that transition finishes, the entire contents of the stack are replaced with the new items. For example, if items A, B, and C are on the stack and you set items D, A, and B, this method uses a pop transition and the resulting stack contains the items D, A, and B.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • items items Property

    An array of navigation items managed by the navigation bar.

    Declaration

    Swift

    var items: [AnyObject]!

    Objective-C

    @property(nonatomic, copy) NSArray *items

    Discussion

    The bottom item is at index 0, the back item is at index n-2, and the top item is at index n-1, where n is the number of items in the array.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    backItem
    topItem

  • topItem topItem Property

    The navigation item at the top of the navigation bar’s stack. (read-only)

    Declaration

    Swift

    var topItem: UINavigationItem? { get }

    Objective-C

    @property(nonatomic, readonly, retain) UINavigationItem *topItem

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

    See Also

    backItem
    items

  • backItem backItem Property

    The navigation item that is immediately below the topmost item on navigation bar’s stack. (read-only)

    Declaration

    Swift

    var backItem: UINavigationItem? { get }

    Objective-C

    @property(nonatomic, readonly, retain) UINavigationItem *backItem

    Discussion

    If the leftBarButtonItem property of the topmost navigation item is nil, the navigation bar displays a back button whose title is derived from the item in this property.

    If there is only one item on the navigation bar’s stack, the 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

    topItem
    items

  • The image shown beside the back button.

    Declaration

    Swift

    var backIndicatorImage: UIImage?

    Objective-C

    @property(nonatomic, retain) UIImage *backIndicatorImage

    Discussion

    If you want to customize the back indicator image, you must also set backIndicatorTransitionMaskImage.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • The image used as a mask for content during push and pop transitions.

    Declaration

    Swift

    var backIndicatorTransitionMaskImage: UIImage?

    Objective-C

    @property(nonatomic, retain) UIImage *backIndicatorTransitionMaskImage

    Discussion

    If you want to customize the back indicator image, you must also set backIndicatorImage.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • barStyle barStyle Property

    The navigation bar style that specifies its appearance.

    Declaration

    Swift

    var barStyle: UIBarStyle

    Objective-C

    @property(nonatomic, assign) UIBarStyle barStyle

    Discussion

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

    It is permissible to set the value of this property when the navigation bar is being managed by a navigation controller object.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    var barTintColor: UIColor?

    Objective-C

    @property(nonatomic, retain) UIColor *barTintColor

    Discussion

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

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • The shadow image to be used for the navigation bar.

    Declaration

    Swift

    var shadowImage: UIImage?

    Objective-C

    @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 with the setBackgroundImage:forBarMetrics: method. If the default background image is used, then the default shadow image will be used regardless of the value of this property.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 6.0 and later.

  • tintColor tintColor Property

    The tint color to apply to the navigation items and bar button items.

    Declaration

    Swift

    var tintColor: UIColor!

    Objective-C

    @property(nonatomic, retain) UIColor *tintColor

    Discussion

    In iOS v7.0, all subclasses of UIView derive their behavior for tintColor from the base class. See the discussion of tintColor at the UIView level for more information.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 2.0 and later.

  • A Boolean value indicating whether the navigation bar is translucent (YEStrue) or not (NOfalse).

    Declaration

    Swift

    var translucent: Bool

    Objective-C

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

    Discussion

    The default value is YEStrue. If the navigation bar has a custom background image, the default is YEStrue if any pixel of the image has an alpha value of less than 1.0, and NOfalse otherwise.

    If you set this property to YEStrue on a navigation bar with an opaque custom background image, the navigation bar will apply a system opacity less than 1.0 to the image.

    If you set this property to NOfalse on a navigation bar with a translucent custom background image, the navigation bar provides an opaque background for the image using black if the navigation bar has UIBarStyleBlack style, white if the navigation bar has UIBarStyleDefault, or the navigation bar’s barTintColor if a custom value is defined.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 3.0 and later.

  • Returns the background image for given bar metrics.

    Declaration

    Swift

    func backgroundImageForBarMetrics(_ barMetrics: UIBarMetrics) -> UIImage?

    Objective-C

    - (UIImage *)backgroundImageForBarMetrics:(UIBarMetrics)barMetrics

    Parameters

    barMetrics

    A bar metrics constant.

    Return Value

    The background image for barMetrics.

    Discussion

    Same as backgroundImageForBarPosition:barMetrics: with a position of UIBarPositionAny.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Sets the background image for given bar metrics.

    Declaration

    Swift

    func setBackgroundImage(_ backgroundImage: UIImage!, forBarMetrics barMetrics: UIBarMetrics)

    Objective-C

    - (void)setBackgroundImage:(UIImage *)backgroundImage forBarMetrics:(UIBarMetrics)barMetrics

    Parameters

    backgroundImage

    The background image to use for barMetrics.

    barMetrics

    A bar metrics constant.

    Discussion

    Same as setBackgroundImage:forBarPosition:barMetrics: with a position of UIBarPositionAny.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Returns the background image to use for a given bar position and set of metrics.

    Declaration

    Swift

    func backgroundImageForBarPosition(_ barPosition: UIBarPosition, barMetrics barMetrics: UIBarMetrics) -> UIImage?

    Objective-C

    - (UIImage *)backgroundImageForBarPosition:(UIBarPosition)barPosition barMetrics:(UIBarMetrics)barMetrics

    Parameters

    barPosition

    The location of the navigation bar.

    barMetrics

    The metrics of the navigation bar.

    Return Value

    The image to use for the specified location and metrics.

    Discussion

    Resizable images will be stretched vertically if necessary for a position of UIBarPositionTopAttached.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Sets the background image to use for a given bar position and set of metrics.

    Declaration

    Swift

    func setBackgroundImage(_ backgroundImage: UIImage?, forBarPosition barPosition: UIBarPosition, barMetrics barMetrics: UIBarMetrics)

    Objective-C

    - (void)setBackgroundImage:(UIImage *)backgroundImage forBarPosition:(UIBarPosition)barPosition barMetrics:(UIBarMetrics)barMetrics

    Parameters

    backgroundImage

    The image to use for the specified location and metrics.

    barPosition

    The location of the navigation bar.

    barMetrics

    The metrics of the navigation bar.

    Discussion

    Resizable images will be stretched vertically if necessary for a position of UIBarPositionTopAttached.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 7.0 and later.

  • Returns the title’s vertical position adjustment for given bar metrics.

    Declaration

    Swift

    func titleVerticalPositionAdjustmentForBarMetrics(_ barMetrics: UIBarMetrics) -> CGFloat

    Objective-C

    - (CGFloat)titleVerticalPositionAdjustmentForBarMetrics:(UIBarMetrics)barMetrics

    Parameters

    barMetrics

    A bar metrics constant.

    Return Value

    The title’s vertical position adjustment for barMetrics.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Sets the title’s vertical position adjustment for given bar metrics.

    Declaration

    Swift

    func setTitleVerticalPositionAdjustment(_ adjustment: CGFloat, forBarMetrics barMetrics: UIBarMetrics)

    Objective-C

    - (void)setTitleVerticalPositionAdjustment:(CGFloat)adjustment forBarMetrics:(UIBarMetrics)barMetrics

    Parameters

    adjustment

    The title’s vertical position adjustment for barMetrics.

    barMetrics

    A bar metrics constant.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.

  • Display attributes for the bar’s title text.

    Declaration

    Swift

    var titleTextAttributes: [NSObject : AnyObject]?

    Objective-C

    @property(nonatomic, copy) NSDictionary *titleTextAttributes

    Discussion

    You can specify the font, text color, text shadow color, and text shadow offset for the title in the text attributes dictionary, using the text attribute keys described in NSString UIKit Additions Reference.

    Import Statement

    Objective-C

    @import UIKit;

    Swift

    import UIKit

    Availability

    Available in iOS 5.0 and later.