NavController

NavController is the base class for navigation controller components like
Nav and Tab. You use navigation controllers
to navigate to pages in your app. At a basic level, a
navigation controller is an array of pages representing a particular history
(of a Tab for example). This array can be manipulated to navigate throughout
an app by pushing and popping pages or inserting and removing them at
arbitrary locations in history.

The current page is the last one in the array, or the top of the stack if we
think of it that way. Pushing a new page onto the top of the
navigation stack causes the new page to be animated in, while popping
the current page will navigate to the previous page in the stack.

Unless you are using a directive like NavPush, or need a
specific NavController, most times you will inject and use a reference to the
nearest NavController to manipulate the navigation stack.

Basic usage

The simplest way to navigate through an app is to create and initialize a new
nav controller using the <ion-nav> component. ion-nav extends the NavController
class.

Injecting NavController will always get you an instance of the nearest
NavController, regardless of whether it is a Tab or a Nav.

Behind the scenes, when Ionic instantiates a new NavController, it creates an
injector with NavController bound to that instance (usually either a Nav or
Tab) and adds the injector to its own providers. For more information on
providers and dependency injection, see Dependency Injection.

Instead, you can inject NavController and know that it is the correct
navigation controller for most situations (for more advanced situations, see
Menu and Tab).

What if you want to control navigation from your root app component?
You can't inject NavController because any components that are navigation
controllers are children of the root component so they aren't available
to be injected.

By adding a reference variable to the ion-nav, you can use @ViewChild to
get an instance of the Nav component, which is a navigation controller
(it extends NavController):

What if you wanted to navigate from an overlay component (popover, modal, alert, etc)?
In this example, we've displayed a popover in our app. From the popover, we'll get a
reference of the root NavController in our app, using the getRootNav() method.

View creation

Views are created when they are added to the navigation stack. For methods
like push(), the NavController takes any component class that is
decorated with @Component as its first argument. The NavController then
compiles that component, adds it to the app and animates it into view.

By default, pages are cached and left in the DOM if they are navigated away
from but still in the navigation stack (the exiting page on a push() for
example). They are destroyed when removed from the navigation stack (on
pop() or setRoot()).

Pushing a View

To push a new view onto the navigation stack, use the push method.
If the page has an <ion-navbar>,
a back button will automatically be added to the pushed view.

Data can also be passed to a view by passing an object to the push method.
The pushed view can then receive the data by accessing it via the NavParams
class.

Runs when the page has loaded. This event only happens once per page being created. If a page leaves but is cached, then this event will not fire again on a subsequent viewing. The ionViewDidLoad event is good place to put your setup code for the page.

ionViewWillEnter

void

Runs when the page is about to enter and become the active page.

ionViewDidEnter

void

Runs when the page has fully entered and is now the active page. This event will fire, whether it was the first load or a cached page.

ionViewWillLeave

void

Runs when the page is about to leave and no longer be the active page.

ionViewDidLeave

void

Runs when the page has finished leaving and is no longer the active page.

ionViewWillUnload

void

Runs when the page is about to be destroyed and have its elements removed.

ionViewCanEnter

boolean/Promise<void>

Runs before the view can enter. This can be used as a sort of "guard" in authenticated views where you need to check permissions before the view can enter

ionViewCanLeave

boolean/Promise<void>

Runs before the view can leave. This can be used as a sort of "guard" in authenticated views where you need to check permissions before the view can leave

Nav Guards

In some cases, a developer should be able to control views leaving and entering. To allow for this, NavController has the ionViewCanEnter and ionViewCanLeave methods.
Similar to Angular route guards, but are more integrated with NavController. For example, if you wanted to prevent a user from leaving a view:

Similar to ionViewCanLeave we still need a catch on the original navCtrl.push in order to handle it properly.
When handling the back button in the ion-navbar, the catch is already taken care of for you by the framework.

NavOptions

Some methods on NavController allow for customizing the current transition.
To do this, we can pass an object with the modified properites.

Property

Value

Description

animate

boolean

Whether or not the transition should animate.

animation

string

What kind of animation should be used.

direction

string

The conceptual direction the user is navigating. For example, is the user navigating forward, or back?

duration

number

The length in milliseconds the animation should take.

easing

string

The easing for the animation.

The property 'animation' understands the following values: md-transition, ios-transition and wp-transition.

If it’s possible to use swipe back or not. If it’s not possible
to go back, or swipe back is not enabled, then this will return false.
If it is possible to go back, and swipe back is enabled, then this
will return true.

Set the views of the current navigation stack and navigate to the
last view. By default animations are disabled, but they can be enabled
by passing options to the navigation controller.You can also pass any
navigation params to the individual pages in the array.

Param

Type

Details

pages

Array<{page:any, params: any}>

An array of objects, each with a page and optionally params property to load in the stack.

opts

Object

Nav options to go with this transition.Optional

Returns:Promise

Returns a promise which is resolved when the transition has completed.