<!--
{
  "availability" : [
    "iOS: 12.0.0 -",
    "iPadOS: 12.0.0 -",
    "macCatalyst: 13.1.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "CarPlay",
  "identifier" : "/documentation/CarPlay/CPMapTemplate",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "CarPlay"
    ],
    "preciseIdentifier" : "c:objc(cs)CPMapTemplate"
  },
  "title" : "CPMapTemplate"
}
-->

# CPMapTemplate

A template that displays a navigation overlay that your app draws on the map.

```
@MainActor class CPMapTemplate
```

## Overview

After CarPlay calls your scene delegate’s [`templateApplicationScene(_:didConnect:to:)`](/documentation/CarPlay/CPTemplateApplicationSceneDelegate/templateApplicationScene(_:didConnect:to:)) method, create a map template and set it as the root template by calling [`setRootTemplate(_:animated:completion:)`](/documentation/CarPlay/CPInterfaceController/setRootTemplate(_:animated:completion:)) on the interface controller the method provides.

The map template appears as an overlay on top of the base view. The template is the control layer, providing a navigation bar and map buttons that users interact with through the CarPlay screen.

> Note:
> The base view is where your app draws its map. CarPlay doesn’t support direct user interactions in this view. Instead, your app uses templates, which overlay the base view, to allow users to interact with your app through the CarPlay screen.

When the user begins to interact with your app through the CarPlay screen, the system displays the navigation bar, hiding it after a brief period of inactivity. You can change this behavior by setting the [`automaticallyHidesNavigationBar`](/documentation/CarPlay/CPMapTemplate/automaticallyHidesNavigationBar) and [`hidesButtonsWithNavigationBar`](/documentation/CarPlay/CPMapTemplate/hidesButtonsWithNavigationBar) properties.

The navigation bar includes up to two leading and two trailing buttons. You can change the buttons, including their titles and icon images, by setting the [`leadingNavigationBarButtons`](/documentation/CarPlay/CPBarButtonProviding/leadingNavigationBarButtons) and [`trailingNavigationBarButtons`](/documentation/CarPlay/CPBarButtonProviding/trailingNavigationBarButtons) properties on your template.

You can display additional map buttons by providing an array of [`CPMapButton`](/documentation/CarPlay/CPMapButton) objects to [`mapButtons`](/documentation/CarPlay/CPMapTemplate/mapButtons). Use these buttons to provide users access to actions, such as entering panning mode or zooming in and out on the map.

## Topics

### Configuring Map Templates

[`automaticallyHidesNavigationBar`](/documentation/CarPlay/CPMapTemplate/automaticallyHidesNavigationBar)

A Boolean value that indicates whether the template should automatically hide the navigation bar.

[`hidesButtonsWithNavigationBar`](/documentation/CarPlay/CPMapTemplate/hidesButtonsWithNavigationBar)

A Boolean value that tells the system to hide the map buttons when hiding the navigation bar.

[`guidanceBackgroundColor`](/documentation/CarPlay/CPMapTemplate/guidanceBackgroundColor)

The background color the map template uses when displaying guidance.

### Handling Map Template Events

[`mapDelegate`](/documentation/CarPlay/CPMapTemplate/mapDelegate)

The object that serves as the delegate of the map template.

[`CPMapTemplateDelegate`](/documentation/CarPlay/CPMapTemplateDelegate)

The protocol an object implements to handle events from a map template.

### Managing Map Buttons

[`mapButtons`](/documentation/CarPlay/CPMapTemplate/mapButtons)

An array of map buttons on the trailing bottom corner of the map template.

[`CPMapButton`](/documentation/CarPlay/CPMapButton)

A button that represents an action that a map template displays on the CarPlay screen.

### Displaying Trip Previews

[`showTripPreviews(_:textConfiguration:)`](/documentation/CarPlay/CPMapTemplate/showTripPreviews(_:textConfiguration:))

Displays the preview for one or more trips, and allows route selection.

[`showTripPreviews(_:selectedTrip:textConfiguration:)`](/documentation/CarPlay/CPMapTemplate/showTripPreviews(_:selectedTrip:textConfiguration:))

Displays the previews for a collection of trips, with a single selected trip.

[`hideTripPreviews()`](/documentation/CarPlay/CPMapTemplate/hideTripPreviews())

Hides the display of trip previews.

[`showRouteChoicesPreview(for:textConfiguration:)`](/documentation/CarPlay/CPMapTemplate/showRouteChoicesPreview(for:textConfiguration:))

Displays the route choices for a single trip.

[`CPTripPreviewTextConfiguration`](/documentation/CarPlay/CPTripPreviewTextConfiguration)

A configuration object for changing the button titles on a trip preview.

### Navigating a Trip

[`startNavigationSession(for:)`](/documentation/CarPlay/CPMapTemplate/startNavigationSession(for:))

Begins navigational guidance for a trip.

[`CPNavigationSession`](/documentation/CarPlay/CPNavigationSession)

An object that represents an active route guidance session.

### Providing Trip Estimates

[`updateEstimates(_:for:)`](/documentation/CarPlay/CPMapTemplate/updateEstimates(_:for:))

Updates travel estimates, such as arrival time and the remaining time and distance for a trip.

[`update(_:for:with:)`](/documentation/CarPlay/CPMapTemplate/update(_:for:with:))

Updates travel estimates, such as arrival time and the remaining time and distance for a trip, with the specified time-remaining color.

[`CPTimeRemainingColor`](/documentation/CarPlay/CPTimeRemainingColor)

The color the system uses when displaying the time remaining for a trip.

[`tripEstimateStyle`](/documentation/CarPlay/CPMapTemplate/tripEstimateStyle)

The style that the map template uses when displaying trip estimates during active nagivation.

[`CPTripEstimateStyle`](/documentation/CarPlay/CPTripEstimateStyle)

The set of display styles for trip estimates.

### Displaying a Navigation Alert

[`present(navigationAlert:animated:)`](/documentation/CarPlay/CPMapTemplate/present(navigationAlert:animated:))

Displays a navigation alert on the map template.

[`dismissNavigationAlert(animated:completion:)`](/documentation/CarPlay/CPMapTemplate/dismissNavigationAlert(animated:completion:))

Tells the map template to dismiss the visable navigation alert.

[`currentNavigationAlert`](/documentation/CarPlay/CPMapTemplate/currentNavigationAlert)

The visible navigation alert.

[`CPNavigationAlert`](/documentation/CarPlay/CPNavigationAlert)

An alert that displays map- or navigation-related information to the user.

### Panning the Map

[`showPanningInterface(animated:)`](/documentation/CarPlay/CPMapTemplate/showPanningInterface(animated:))

Shows the panning interface on the map.

[`dismissPanningInterface(animated:)`](/documentation/CarPlay/CPMapTemplate/dismissPanningInterface(animated:))

Dismisses the panning interface.

[`isPanningInterfaceVisible`](/documentation/CarPlay/CPMapTemplate/isPanningInterfaceVisible)

A Boolean value that indicates whether the map template is displaying the panning interface.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)