A new way to manage the back button title in iOS 14 with backButtonDisplayMode

In iOS 14, long-press on the back button will bring up a history stack. We already discuss the problem and solution in the previous post of What should you know about a navigation history stack in iOS 14 . Even the solution in the article works well, it feels a bit like a hack, and I'm pleased that Apple introduces the new navigation item's property to tackle the problem in iOS 14 beta 3.

I suggest you check my previouspost for a better understanding of the problem, so you get an idea of why Apple introduce this new property.

Example of a history stack of Settings

backButtonDisplayMode

The new property is backButtonDisplayMode , which use to controls how the back button sources its title.

@available(iOS 14.0, *)
open var backButtonDisplayMode: UINavigationItem.BackButtonDisplayMode

This property is an enum of type UINavigationItem.BackButtonDisplayMode that have three values right now.

public enum BackButtonDisplayMode : Int {
    /// Default mode, uses an appropriate title, followed by a generic title (typically 'Back'), then no title.
    case `default` = 0

    /// Generic titles only. Ignores .title and .backButtonTitle (but *not* .backBarButtonItem.title).
    case generic = 1

    /// Don't use a title, just the back button indicator image.
    case minimal = 2
}

Sources of back button title

Since backButtonDisplayMode defines the back button title sources, let's see type the source we are having right now.

A view controller's title or navigationItem.title will use as back button title if backButtonTitle or backBarButtonItem is not specified.

class AViewController: UIViewController {
    override func viewDidLoad() {
        title = "Title A" 
        // or 
        navigationItem.title = "Title A"
    }
}

A view controller's title or navigationItem.title will use as back button title A view controller's title or navigationItem.title will use as back button title

Back button title

You can set the back button title directly with navigationItem.backButtonTitle . This will override what you define in title or navigationItem.title .

class AViewController: UIViewController {
    override func viewDidLoad() {
        title = "Title A" 
        navigationItem.backButtonTitle = "backButtonTitle A"
    }
}

Explicitly define back button title with navigationItem.backButtonTitle Explicitly define back button title with navigationItem.backButtonTitle

Back bar button item

The highest priority of all sources is navigationItem.backBarButtonItem . This will override any value specifiedin title , navigationItem.backButtonTitle , or navigationItem.backBarButtonItem .

class AViewController: UIViewController {
    override func viewDidLoad() {
        title = "Title A" 
        navigationItem.backButtonTitle = "backButtonTitle A"
        navigationItem.backBarButtonItem = UIBarButtonItem(title: "backBarButtonItem A", style: .plain, target: nil, action: nil)
    }
}

The highest priority source of the title is backBarButtonItem The highest priority source of the title is backBarButtonItem

BackButtonDisplayMode.default

This mode is what we have seen so far. The title shown on the back button will also use as the title in the history stack.

BackButtonDisplayMode.generic

This mode will use generic title (typically 'Back') for back button and use value in title , navigationItem.title , or navigationItem.backButtonTitle for history stack. But this mode won't effect setting title with backBarButtonItem.title .

class AViewController: UIViewController {
    override func viewDidLoad() {
        title = "Title A" 
        // or 
        navigationItem.title = "Title A"
        navigationItem.backButtonDisplayMode = .generic
    }
}

navigationItem.title still use in history stack

But the back button will use a generic title ('Back').

Generic title (Back) is used for BackButtonDisplayMode.generic

The same rule applies for navigationItem.backButtonTitle , but this won't effect setting back button title with navigationItem.backBarButtonItem .

class AViewController: UIViewController {
    override func viewDidLoad() {
        title = "Title A" 
        navigationItem.backButtonTitle = "backButtonTitle A"
        navigationItem.backBarButtonItem = UIBarButtonItem(title: "backBarButtonItem A", style: .plain, target: nil, action: nil)
        navigationItem.backButtonDisplayMode = .generic
    }
}

BackButtonDisplayMode.generic won't effect navigationItem.backBarButtonItem BackButtonDisplayMode.generic won't effect navigationItem.backBarButtonItem

BackButtonDisplayMode.minimal

This mode won't use a title for the back button, just the back button indicator image. The history stack still use a value in title , navigationItem.title , or navigationItem.backButtonTitle . Just like .generic , this mode won't affect setting title with navigationItem.backBarButtonItem .

class AViewController: UIViewController {
    override func viewDidLoad() {
        title = "Title A" 
        navigationItem.backButtonTitle = "backButtonTitle A"
        navigationItem.backButtonDisplayMode = .minimal
    }
}

navigationItem.title or navigationItem.backButtonTitle still use in history stack

But the back button will show as minimal form (just back button indicator).

Only the back button indicator image is used for BackButtonDisplayMode.minimal Source of title BackButtonDisplayMode Back button title History stack title title , navigationItem.title , or navigationItem.backButtonTitle default Value from source of title or 'Back' if space is limited Value from source of title title , navigationItem.title , or navigationItem.backButtonTitle generic 'Back' Value from source of title title , navigationItem.title , or navigationItem.backButtonTitle minimal Blank Value from source of title navigationItem.backBarButtonItem default Value from source of title or 'Back' if space is limited Value from source of title navigationItem.backBarButtonItem generic Value from source of title or 'Back' if space is limited Value from source of title navigationItem.backBarButtonItem minimal Value from source of title or 'Back' if space is limited Value from source of title

backButtonDisplayMode is a nice addition in iOS 14, we have finer control over what we want to show on the back button.

The following will show a title as "Title A", back button as blank, and history stack title as "Title in history stack A".

class AViewController: UIViewController {
    override func viewDidLoad() {
        title = "Title A"
        navigationItem.backButtonTitle = "Title in history stack A"
        navigationItem.backButtonDisplayMode = .minimal
    }
}

This is a lot cleaner than our hack in the previous post.