> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ios/navigation/llms.txt)

# Migrate UI

The following article outlines the main API changes for the UI components and aims to help with the migration to the `MapboxNavigationUIKit` (former `MapboxNavigation`) library.

> **Related content (example): [UIKitExample](https://github.com/mapbox/mapbox-navigation-ios/tree/main/Examples/UIKitExample)**
> 
> The `mapbox-navigation-ios` repository provides `UIKitExample` showing how to use the UI components.

## Requirements

`MapboxNavigationUIKit` requires an iOS target to be iOS 14 or higher.

## MapboxCoreNavigation migration

`MapboxNavigationUIKit` builds on `MapboxNavigationCore`. Visit the [MapboxCoreNavigation migration guide](https://docs.mapbox.com/ios/navigation/guides/migration/migrate-core/) to find out how to migrate to `MapboxNavigationCore`.

## MapboxNavigation migration

A library that provides a suite of UI components has been renamed from `MapboxNavigation` into `MapboxNavigationUIKit`. `MapboxNavigationUIKit` contains the same UI components that were included into `MapboxNavigation` from Navigation SDK v2. The UI components included into `MapboxNavigationUIKit` have adopted a new generation of navigation core functionality that is provided by `MapboxNavigationCore` library (former `MapboxCoreNavigation`).

### `NavigationViewController`

Replace the old `NavigationViewController` initializer with a new `NavigationViewController.init(navigationRoutes: NavigationRoutes, navigationOptions: NavigationOptions)`:

-   `navigationRoutes` parameter contains the main and alternative routes and can be obtained via [`RoutingProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/routingprovider/).
    
-   `navigationOptions` parameter contains customization options for the turn-by-turn navigation user experience and can be constructed using a new [`MapboxNavigation`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/) protocol.
    

An example of instantiating `NavigationViewController` using a routes response from [`RoutingProvider`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/routingprovider/):

```swift
let navigationProvider = MapboxNavigationProvider(coreConfig: CoreConfig())
do  {
  let navigationRouteOptions = NavigationRouteOptions(coordinates: coordinates)
  let routesResponse = try await navigationProvider.routingProvider().calculateRoutes(options: navigationRouteOptions).value
  NavigationViewController(
    navigationRoutes: routesResponse,
    navigationOptions: NavigationOptions(
      mapboxNavigation: navigationProvider.mapboxNavigation,
      voiceController: navigationProvider.routeVoiceController,
      eventsManager: navigationProvider.eventsManager(),
      styles: [NightStyle()],
      predictiveCacheManager: navigationProvider.predictiveCacheManager
    )
  )
} catch {
  print("Error occured while requesting routes: \(error.localizedDescription)")
}
```

### `NavigationView`

Replace the old `NavigationView` initializer with a new `NavigationView.init(frame: CGRect, mapViewConfiguration: MapViewConfiguration)`. `MapViewConfiguration` allows you to re-use existing [`NavigationMapView`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationmapview/) or create a new one. If you choose to create a new [`NavigationMapView`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationmapview/) you need to provide a list of dependencies that can be obtained from [`MapboxNavigation`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/) protocol.

An example of instantiating `NavigationView` that creates a new [`NavigationMapView`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationmapview/):

```swift
let navigationProvider = MapboxNavigationProvider(coreConfig: CoreConfig())

NavigationView(
  frame: .zero,
  mapViewConfiguration: .createNew(
    location: navigationProvider.navigation().locationMatching
      .map(\.mapMatchingResult.enhancedLocation)
      .eraseToAnyPublisher(),
    routeProgress: navigationProvider.navigation().routeProgress
      .map(\.?.routeProgress)
      .eraseToAnyPublisher(),
    predictiveCacheManager: navigationProvider.predictiveCacheManager
  )
)
```

### `NavigationMapView`

**Note:** [`NavigationMapView`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationmapview/) has been moved into the `MapboxNavigationCore` library.

Initialize `NavigationMapView` using [`NavigationMapView.init(location: AnyPublisher<CLLocation, Never>, routeProgress: AnyPublisher<RouteProgress?, Never>, navigationCameraType: NavigationCameraType, heading: AnyPublisher<CLHeading, Never>?, predictiveCacheManager: PredictiveCacheManager?)`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/navigationmapview/init(location:routeprogress:navigationcameratype:heading:predictivecachemanager:)/). Those dependencies can be obtained from [`MapboxNavigation`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/) protocol.

An example of instantiating `NavigationMapView`:

```swift
let navigationProvider = MapboxNavigationProvider(coreConfig: CoreConfig())

NavigationMapView(
  location: navigationProvider.navigation().locationMatching
    .map(\.mapMatchingResult.enhancedLocation)
    .eraseToAnyPublisher(),
  routeProgress: navigationProvider.navigation().routeProgress
    .map(\.?.routeProgress)
    .eraseToAnyPublisher(),
  heading: navigationProvider.navigation().heading,
  predictiveCacheManager: navigationProvider.predictiveCacheManager
)
```

### `PreviewViewController`

Initialize `PreviewViewController` using `PreviewViewController.init(_: PreviewOptions)`. `PreviewOptions` requires you to provide dependencies that can be obtained from [`MapboxNavigation`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/mapboxnavigation/) protocol.

An example of instantiating `PreviewViewController`:

```swift
let navigationProvider = MapboxNavigationProvider(coreConfig: CoreConfig())

PreviewViewController(
  PreviewOptions(
    locationMatching: navigationProvider.navigation().locationMatching,
    routeProgress: navigationProvider.navigation().routeProgress
      .map(\.?.routeProgress)
      .eraseToAnyPublisher(),
    predictiveCacheManager: navigationProvider.predictiveCacheManager
  )
)
```

**Note:** You need to start a free drive session by invoking [`SessionController.startFreeDrive()`](https://docs.mapbox.com/ios/navigation/api/3.28.2/navigation/documentation/mapboxnavigationcore/sessioncontroller/startfreedrive()/) to receive map matching updates.