Skip to end of metadata
Go to start of metadata

Designing intuitive and consistent navigation experience in your application is very important as it determines the overall experience when user is using your application. By default, Crosslight provides several navigation patterns commonly found in Android applications, such as:

  • List navigation, which consists of push and modal navigation.
  • Nested modal navigation, typically used to capture a series of input in multiple screens.
  • Multi-screen navigation, also known as tabbed navigation.
  • Master-detail or split navigation, typically supported in device with larger screens such as tablets.

The following illustrates common navigation patterns supported in Android applications.

On this page:

To learn more how to build navigation apps that target Android and other platforms, see Understanding Crosslight Navigation Services.

Modal and Nested Modal Navigation Support

Crosslight Android fully supports modal navigation as well as more nested modal navigation. Through a unified navigation modelling using ViewModel navigation, Crosslight provides a consistent navigation experience across multiple platforms. Nested modal navigation allows you to build wizard-like interface to capture user input that spans across multiple screens. Crosslight Android conforms to the navigation specifications as described in the Designing Constant Navigation Interface – Part 3 section.

Since the navigation logic is triggered from the shared application layer – instead of the Android layer – you use the same way to perform navigation, i.e., calling this.NavigationService.Navigate method in your ViewModel. To learn more about triggering modal navigation and receive the callback, see Performing Modal Navigation.

Using List Navigation

Getting started with list navigation in Android is very simple, just create a new activity class that derive from ListActivity<TViewModel> with InteractionMode property set to Navigation. You can customize the appearance of the group header by overriding the GroupItemLayoutId as well as overriding the list item appearance by overriding ContentLayoutId with a provided layout xml. With the specified ViewModel, the ListActivity automatically reads the navigation source from the Items property of the ViewModel.

Assuming that you have a ViewModel with the following navigation items.


The next step is simply creating a new ListActivity that consumes the ViewModel.

At runtime, Crosslight will automatically discover the navigation source, configuring the list view to use grouping style and prepares the table item accordingly to indicate a navigation flow which will produce the following result:

As seen in the image above, the Android table group style can be used because the ViewModel supplies the navigation items in grouped object which is represented in the GroupItems property. In addition, make sure the related properties such as InteractionMode, ContentLayoutId, and GroupLayoutId are properly overridden in the ListActivity Class.

Using Tabbed Navigation

Another common scenario is using a tabbed navigation, which is a common pattern in Android development. Crosslight Android provides a specialized tab activity that supports ViewModel navigation using tabs. Similarly, the tab activity will read the navigation source from the Items property of the ViewModel. Selection-related properties are automatically synchronized in two-way mode, allowing you to change the selected tab from within the ViewModel.

The following code shows you how to define the navigation items in the ViewModel. Note that the class derives from MultiPageViewModelBase instead of ViewModelBase.


The TabActivity Class is as simple as


Often times, you want to control the selection from the content ViewModel. For instance, you would like to navigate the screen to the second tab when user tapped on a button. This can be easily done by implementing the IChildViewModel Interface in the content ViewModel, then set the SelectedIndex property to the desired value.

The following code shows how to change the selected tab in the content ViewModel.


Which will result as follows:

Customizing Navigation Parameter

Crosslight Android supports most of the parameter exposed in the NavigationParameter which can be optionally passed to the navigation service.

The following list describes the properties that affect the navigation behaviors in Android:

  • NavigationMode
    Specifies the navigation mode to apply to the navigation session. Supported values: Push and Modal. The default value is Push.
  • ModalTransitionStyle
    Specifies the transition style when performing modal navigation. Supported values: Default, Slide and Fade. By default, the value is chosen based on the mobile platform standard. For example, in iOS, the Default value refers to Slide while Android uses Fade as the default.
  • EnsureNavigationContext
    Specifies whether the navigation context should be always made available – whether in push or in modal navigation. When set to true, iOS translates this setting by wrapping the target content in a navigation controller. As such, code that access the navigation-related features – such as navigation bar or navigation item – can continue to work flawlessly.

In general, you create a new instance of NavigationParameter Class and set the properties that you desire, then pass it to the Navigate method overload that accepts navigation parameter. This is the easiest and standard way to perform navigation with customized behaviors. For more information about the fundamentals of Crosslight navigation, see Designing Consistent Navigation Interface – Part 3.