<!--
{
  "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

[`var automaticallyHidesNavigationBar: Bool`](/documentation/CarPlay/CPMapTemplate/automaticallyHidesNavigationBar)

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

[`var hidesButtonsWithNavigationBar: Bool`](/documentation/CarPlay/CPMapTemplate/hidesButtonsWithNavigationBar)

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

[`var guidanceBackgroundColor: UIColor`](/documentation/CarPlay/CPMapTemplate/guidanceBackgroundColor)

The background color the map template uses when displaying guidance.

### Handling Map Template Events

[`var mapDelegate: (any CPMapTemplateDelegate)?`](/documentation/CarPlay/CPMapTemplate/mapDelegate)

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

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

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

### Managing Map Buttons

[`var mapButtons: [CPMapButton]`](/documentation/CarPlay/CPMapTemplate/mapButtons)

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

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

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

### Displaying Trip Previews

[`func showTripPreviews([CPTrip], textConfiguration: CPTripPreviewTextConfiguration?)`](/documentation/CarPlay/CPMapTemplate/showTripPreviews(_:textConfiguration:))

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

[`func showTripPreviews([CPTrip], selectedTrip: CPTrip?, textConfiguration: CPTripPreviewTextConfiguration?)`](/documentation/CarPlay/CPMapTemplate/showTripPreviews(_:selectedTrip:textConfiguration:))

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

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

Hides the display of trip previews.

[`func showRouteChoicesPreview(for: CPTrip, textConfiguration: CPTripPreviewTextConfiguration?)`](/documentation/CarPlay/CPMapTemplate/showRouteChoicesPreview(for:textConfiguration:))

Displays the route choices for a single trip.

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

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

### Navigating a Trip

[`func startNavigationSession(for: CPTrip) -> CPNavigationSession`](/documentation/CarPlay/CPMapTemplate/startNavigationSession(for:))

Begins navigational guidance for a trip.

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

An object that represents an active route guidance session.

### Providing Trip Estimates

[`func updateEstimates(CPTravelEstimates, for: CPTrip)`](/documentation/CarPlay/CPMapTemplate/updateEstimates(_:for:))

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

[`func update(CPTravelEstimates, for: CPTrip, with: CPTimeRemainingColor)`](/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.

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

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

[`var tripEstimateStyle: CPTripEstimateStyle`](/documentation/CarPlay/CPMapTemplate/tripEstimateStyle)

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

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

The set of display styles for trip estimates.

### Displaying a Navigation Alert

[`func present(navigationAlert: CPNavigationAlert, animated: Bool)`](/documentation/CarPlay/CPMapTemplate/present(navigationAlert:animated:))

Displays a navigation alert on the map template.

[`func dismissNavigationAlert(animated: Bool, completion: (Bool) -> Void)`](/documentation/CarPlay/CPMapTemplate/dismissNavigationAlert(animated:completion:))

Tells the map template to dismiss the visable navigation alert.

[`var currentNavigationAlert: CPNavigationAlert?`](/documentation/CarPlay/CPMapTemplate/currentNavigationAlert)

The visible navigation alert.

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

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

### Panning the Map

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

Shows the panning interface on the map.

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

Dismisses the panning interface.

[`var isPanningInterfaceVisible: Bool`](/documentation/CarPlay/CPMapTemplate/isPanningInterfaceVisible)

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

### Instance Methods

[`func hidePanel(completion: ((Bool, (any Error)?) -> Void)?)`](/documentation/CarPlay/CPMapTemplate/hidePanel(completion:))

Hides the overlay.

[`func popPanel(completion: ((Bool, (any Error)?) -> Void)?)`](/documentation/CarPlay/CPMapTemplate/popPanel(completion:))

Pops the top panel from the overlay’s panel stack.

[`func pushPanel(CPMapPanel, completion: ((Bool, (any Error)?) -> Void)?)`](/documentation/CarPlay/CPMapTemplate/pushPanel(_:completion:))

Pushes a new panel.

[`func showPanel(CPMapPanel, completion: ((Bool, (any Error)?) -> Void)?)`](/documentation/CarPlay/CPMapTemplate/showPanel(_:completion:))

Shows an overlay with the specified panel.

## Relationships

### Conforms To

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`CVarArg`](/documentation/Swift/CVarArg)

[`Equatable`](/documentation/Swift/Equatable)

[`Sendable`](/documentation/Swift/Sendable)

[`NSSecureCoding`](/documentation/Foundation/NSSecureCoding)

[`Hashable`](/documentation/Swift/Hashable)

[`NSCoding`](/documentation/Foundation/NSCoding)

[`SendableMetatype`](/documentation/Swift/SendableMetatype)

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

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

### Inherits From

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

---

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)