Carplay

CarPlay

Build apps that display on the vehicle's CarPlay screen using the CarPlay framework's template-based UI system. Covers scene lifecycle, template types, navigation guidance, audio playback, communication, point-of-interest categories, entitlement setup, and simulator testing. Targets Swift 6.3 / iOS 26+.

See references/carplay-patterns.md for extended patterns including full navigation sessions, dashboard scenes, and advanced template composition.

Scope boundary: full CarPlay framework apps use category entitlements, CPTemplateApplicationScene, CPTemplateApplicationSceneDelegate, CPInterfaceController, and system CPTemplate navigation. CarPlay-visible WidgetKit widgets and ActivityKit Live Activities are separate system experiences; route their implementation to those domains while keeping CarPlay-specific validation here.

Contents

• Entitlements and Setup
• Scene Configuration
• Templates Overview
• Navigation Apps
• Audio Apps
• Communication Apps
• Point of Interest Apps
• Testing with CarPlay Simulator
• Common Mistakes
• Review Checklist
• References

Entitlements and Setup

CarPlay requires a category-specific entitlement granted by Apple. Request it at developer.apple.com/contact/carplay and agree to the CarPlay Entitlement Addendum.

Entitlement Keys by Category

Project Configuration

1. Update the App ID in the developer portal under Additional Capabilities. 2. Generate a new provisioning profile for the updated App ID. 3. In Xcode, disable automatic signing and import the CarPlay provisioning profile. 4. Add an Entitlements.plist with the entitlement key set to true. 5. Set Code Signing Entitlements build setting to the Entitlements.plist path.

Key Types

Scene Configuration

Declare the CarPlay scene in Info.plist and implement CPTemplateApplicationSceneDelegate to respond when CarPlay connects.

Info.plist Scene Manifest

<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <true/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>CPTemplateApplicationSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneClassName</key>
                <string>CPTemplateApplicationScene</string>
                <key>UISceneConfigurationName</key>
                <string>CarPlaySceneConfiguration</string>
                <key>UISceneDelegateClassName</key>
                <string>$(PRODUCT_MODULE_NAME).CarPlaySceneDelegate</string>
            </dict>
        </array>
    </dict>
</dict>

Scene Delegate (Non-Navigation)

Non-navigation apps receive an interface controller only. No window.

import CarPlay

final class CarPlaySceneDelegate: UIResponder,
    CPTemplateApplicationSceneDelegate {

    var interfaceController: CPInterfaceController?

    func templateApplicationScene(
        _ templateApplicationScene: CPTemplateApplicationScene,
        didConnect interfaceController: CPInterfaceController
    ) {
        self.interfaceController = interfaceController
        interfaceController.setRootTemplate(buildRootTemplate(),
                                            animated: true, completion: nil)
    }

    func templateApplicationScene(
        _ templateApplicationScene: CPTemplateApplicationScene,
        didDisconnectInterfaceController interfaceController: CPInterfaceController
    ) {
        self.interfaceController = nil
    }
}

Scene Delegate (Navigation)

Navigation apps receive both an interface controller and a CPWindow. Set the window's root view controller to draw map content.

func templateApplicationScene(
    _ templateApplicationScene: CPTemplateApplicationScene,
    didConnect interfaceController: CPInterfaceController,
    to window: CPWindow
) {
    self.interfaceController = interfaceController
    self.carWindow = window
    window.rootViewController = MapViewController()

    let mapTemplate = CPMapTemplate()
    mapTemplate.mapDelegate = self
    interfaceController.setRootTemplate(mapTemplate, animated: true,
                                        completion: nil)
}

Templates Overview

CarPlay provides a fixed set of template types. The app supplies content; the system renders it on the vehicle display.

General Purpose Templates

Category-Specific Templates

Navigation Hierarchy

Use pushTemplate(_:animated:completion:) to add templates to the stack. Use presentTemplate(_:animated:completion:) for modal display. Use popTemplate(animated:completion:) to go back. CPTabBarTemplate must be set as root -- it cannot be pushed or presented.

CPTabBarTemplate

let browseTab = CPListTemplate(title: "Browse",
                               sections: [CPListSection(items: listItems)])
browseTab.tabImage = UIImage(systemName: "list.bullet")

let tabBar = CPTabBarTemplate(templates: [browseTab, settingsTab])
tabBar.delegate = self
interfaceController.setRootTemplate(tabBar, animated: true, completion: nil)

CPListTemplate

let item = CPListItem(text: "Favorites", detailText: "12 items")
item.handler = { selectedItem, completion in
    self.interfaceController?.pushTemplate(detailTemplate, animated: true,
                                           completion: nil)
    completion()
}

let section = CPListSection(items: [item], header: "Library",
                            sectionIndexTitle: nil)
let listTemplate = CPListTemplate(title: "My App", sections: [section])

Navigation Apps

Navigation apps use com.apple.developer.carplay-maps. They are the only category that receives a CPWindow for drawing map content. The root template must be a CPMapTemplate.

Trip Preview and Route Selection

let routeChoice = CPRouteChoice(
    summaryVariants: ["Fastest Route", "Fast"],
    additionalInformationVariants: ["Via Highway 101"],
    selectionSummaryVariants: ["25 min"]
)
let trip = CPTrip(origin: origin, destination: destination,
                  routeChoices: [routeChoice])
mapTemplate.showTripPreviews([trip], textConfiguration: nil)

Starting a Navigation Session

extension CarPlaySceneDelegate: CPMapTemplateDelegate {
    func mapTemplate(_ mapTemplate: CPMapTemplate,
                     startedTrip trip: CPTrip,
                     using routeChoice: CPRouteChoice) {
        let session = mapTemplate.startNavigationSession(for: trip)
        session.pauseTrip(for: .loading, description: "Calculating route...")

        let maneuver = CPManeuver()
        maneuver.instructionVariants = ["Turn right onto Main St"]
        maneuver.symbolImage = UIImage(systemName: "arrow.turn.up.right")
        session.upcomingManeuvers = [maneuver]

        let estimates = CPTravelEstimates(
            distanceRemaining: Measurement(value: 5.2, unit: .miles),
            timeRemaining: 900)
        session.updateEstimates(estimates, for: maneuver)
    }
}

Map Buttons

let zoomIn = CPMapButton { _ in self.mapViewController.zoomIn() }
zoomIn.image = UIImage(systemName: "plus.magnifyingglass")
mapTemplate.mapButtons = [zoomIn, zoomOut]

CPSearchTemplate

extension CarPlaySceneDelegate: CPSearchTemplateDelegate {
    func searchTemplate(_ searchTemplate: CPSearchTemplate,
                        updatedSearchText searchText: String,
                        completionHandler: @escaping ([CPListItem]) -> Void) {
        performSearch(query: searchText) { results in
            completionHandler(results.map {
                CPListItem(text: $0.name, detailText: $0.address)
            })
        }
    }

    func searchTemplate(_ searchTemplate: CPSearchTemplate,
                        selectedResult item: CPListItem,
                        completionHandler: @escaping () -> Void) {
        // Navigate to selected destination
        completionHandler()
    }
}

Audio Apps

Audio apps use com.apple.developer.carplay-audio. They display browsable content in lists and use CPNowPlayingTemplate for playback controls. CPInformationTemplate is not available to audio-entitled apps.

Now Playing Template

CPNowPlayingTemplate is a shared singleton. It reads metadata from MPNowPlayingInfoCenter. Do not instantiate a new one.

let nowPlaying = CPNowPlayingTemplate.shared
nowPlaying.isUpNextButtonEnabled = true
nowPlaying.isAlbumArtistButtonEnabled = true
nowPlaying.updateNowPlayingButtons([
    CPNowPlayingShuffleButton { _ in self.toggleShuffle() },
    CPNowPlayingRepeatButton { _ in self.toggleRepeat() }
])
nowPlaying.add(self) // Register as CPNowPlayingTemplateObserver

Siri Assistant Cell

Audio apps supporting INPlayMediaIntent can show an assistant cell. Communication apps use INStartCallIntent with .startCall.

let config = CPAssistantCellConfiguration(
    position: .top, visibility: .always, assistantAction: .playMedia)
let listTemplate = CPListTemplate(
    title: "Playlists",
    sections: [CPListSection(items: items)],
    assistantCellConfiguration: config)

Communication Apps

Communication apps use com.apple.developer.carplay-communication. They display message lists and contacts, and support INStartCallIntent for Siri-initiated calls. CPMessageListItem has no app-provided selection handler. When selected, CarPlay invokes Siri compose, read, or reply behavior based on the item's phone/email, unread state, or existing conversation configuration.

let leading = CPMessageListItemLeadingConfiguration(
    leadingItem: .star, leadingImage: nil, unread: true)
let trailing = CPMessageListItemTrailingConfiguration(
    trailingItem: .none, trailingImage: nil)

let message = CPMessageListItem(
    conversationIdentifier: "conv-123",
    text: "Jane",
    leadingConfiguration: leading,
    trailingConfiguration: trailing,
    detailText: "Meeting at 3pm",
    trailingText: "2:45 PM")

let messageList = CPListTemplate(title: "Messages",
                                 sections: [CPListSection(items: [message])])

Point of Interest Apps

EV charging, parking, and food ordering apps use CPPointOfInterestTemplate and CPInformationTemplate to display locations and details. CPPointOfInterestTemplate displays a maximum of 12 points of interest.

CPPointOfInterestTemplate

let poi = CPPointOfInterest(
    location: MKMapItem(placemark: MKPlacemark(
        coordinate: CLLocationCoordinate2D(latitude: 37.7749,
                                           longitude: -122.4194))),
    title: "SuperCharger Station", subtitle: "4 available",
    summary: "150 kW DC fast charging",
    detailTitle: "SuperCharger Station", detailSubtitle: "$0.28/kWh",
    detailSummary: "Open 24 hours",
    pinImage: UIImage(systemName: "bolt.fill"))

poi.primaryButton = CPTextButton(title: "Navigate",
                                 textStyle: .confirm) { _ in }

let poiTemplate = CPPointOfInterestTemplate(
    title: "Nearby Chargers", pointsOfInterest: [poi], selectedIndex: 0)
poiTemplate.pointOfInterestDelegate = self

CPInformationTemplate

let infoTemplate = CPInformationTemplate(
    title: "Order Summary", layout: .leading,
    items: [
        CPInformationItem(title: "Item", detail: "Burrito Bowl"),
        CPInformationItem(title: "Total", detail: "$12.50")],
    actions: [
        CPTextButton(title: "Place Order", textStyle: .confirm) { _ in
            self.placeOrder() },
        CPTextButton(title: "Cancel", textStyle: .cancel) { _ in
            self.interfaceController?.popTemplate(animated: true,
                                                  completion: nil) }])

Testing with CarPlay Simulator

1. Build and run in Xcode with the iOS simulator. 2. Choose I/O > External Displays > CarPlay.

Default window: 800x480 at @2x. Enable extra options for navigation apps:

defaults write com.apple.iphonesimulator CarPlayExtraOptions -bool YES

Recommended Test Configurations

Simulator cannot test locked-iPhone behavior, Siri, audio coexistence with car radio, or physical input hardware (knobs, touch pads). Test on a real CarPlay-capable vehicle or aftermarket head unit when possible. Design primary CarPlay flows so they do not require iPhone input while CarPlay is active.

Common Mistakes

DON'T: Use the wrong scene delegate method

Navigation apps must implement templateApplicationScene(_:didConnect:to:) (with CPWindow). Non-navigation apps use templateApplicationScene(_:didConnect:) (no window). Using the wrong variant produces no CarPlay UI.

DON'T: Draw custom UI in the navigation window

CPWindow is exclusively for map content. All overlays, alerts, and controls must use CarPlay templates.

DON'T: Push or present CPTabBarTemplate

CPTabBarTemplate can only be set as root. Pushing or presenting it fails. Use setRootTemplate(_:animated:completion:).

DON'T: Instantiate CPNowPlayingTemplate

Use CPNowPlayingTemplate.shared. Creating a new instance causes issues.

DON'T: Add handlers to CPMessageListItem

CPMessageListItem is Siri-managed, unlike CPListItem. Do not set message.handler; use the item configuration and userInfo for context.

DON'T: Treat widgets as CarPlay template apps

CarPlay-visible widgets and Live Activities belong to WidgetKit and ActivityKit. Use this skill for category-entitled CarPlay template app scenes and for validating those surfaces in the car context.

DON'T: Ignore vehicle display limits

Check CPSessionConfiguration.limitedUserInterfaces and respect maximumItemCount / maximumSectionCount on list templates.

DON'T: Forget to call the completion handler

CPListItem.handler must call its completion handler in every code path. Failure leaves the list in a loading state.

Review Checklist

• [ ] Correct CarPlay entitlement key in Entitlements.plist
• [ ] UIApplicationSupportsMultipleScenes set to true
• [ ] CPTemplateApplicationSceneSessionRoleApplication scene in Info.plist
• [ ] Scene delegate class name matches UISceneDelegateClassName
• [ ] Correct delegate method used (with/without CPWindow)
• [ ] Root template set in didConnect before returning
• [ ] Interface controller and window references cleared on disconnect
• [ ] CPTabBarTemplate only used as root, never pushed
• [ ] CPNowPlayingTemplate.shared used, not a new instance
• [ ] Communication rows use CPMessageListItem without custom handlers
• [ ] WidgetKit/ActivityKit surfaces routed outside CarPlay template app code
• [ ] maximumItemCount/maximumSectionCount checked before populating lists
• [ ] CPListItem.handler calls completion in every path
• [ ] Map-only content in CPWindow root view controller (navigation apps)
• [ ] App functions while iPhone is locked
• [ ] Tested at minimum, standard, and high-resolution simulator sizes
• [ ] Audio session deactivated when not actively playing

References

• Extended patterns (dashboard, instrument cluster, full nav flow, tab composition): references/carplay-patterns.md
• CarPlay framework
• CPTemplateApplicationSceneDelegate
• CPInterfaceController
• CPMapTemplate
• CPListTemplate
• CPNowPlayingTemplate
• CPPointOfInterestTemplate
• CPNavigationSession
• Requesting CarPlay Entitlements
• Displaying Content in CarPlay
• Using the CarPlay Simulator
• CarPlay HIG

CarPlay Extended Patterns

Overflow reference for the carplay skill. Contains advanced patterns that exceed the main skill file's scope.

Contents

• Dashboard Scene for Navigation Apps
• Instrument Cluster Scene
• Full Navigation Session Lifecycle
• Lane Guidance
• Navigation Alerts
• Map Panning Delegate
• Advanced List Patterns
• Audio App: Full Scene Delegate
• Communication App Patterns
• Quick Food Ordering Flow
• Session Configuration and Vehicle Limits
• Handling Multiple Scenes

Dashboard Scene for Navigation Apps

Navigation apps can present maps, upcoming maneuvers, and shortcut buttons in the CarPlay Dashboard. Add CPSupportsDashboardNavigationScene and a dashboard scene configuration to Info.plist alongside the main scene.

<key>UIApplicationSceneManifest</key>
<dict>
    <key>CPSupportsDashboardNavigationScene</key>
    <true/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>CPTemplateApplicationDashboardSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneClassName</key>
                <string>CPTemplateApplicationDashboardScene</string>
                <key>UISceneConfigurationName</key>
                <string>CarPlayDashboardConfiguration</string>
                <key>UISceneDelegateClassName</key>
                <string>$(PRODUCT_MODULE_NAME).DashboardSceneDelegate</string>
            </dict>
        </array>
    </dict>
</dict>

Dashboard Scene Delegate

import CarPlay

final class DashboardSceneDelegate: UIResponder,
    CPTemplateApplicationDashboardSceneDelegate {

    var dashboardWindow: UIWindow?
    var dashboardController: CPDashboardController?

    func templateApplicationDashboardScene(
        _ scene: CPTemplateApplicationDashboardScene,
        didConnect dashboardController: CPDashboardController,
        to window: UIWindow
    ) {
        self.dashboardController = dashboardController
        self.dashboardWindow = window
        window.rootViewController = DashboardMapViewController()

        dashboardController.shortcutButtons = [
            CPDashboardButton(
                titleVariants: ["Home"], subtitleVariants: ["25 min"],
                image: UIImage(systemName: "house.fill")!) { _ in },
            CPDashboardButton(
                titleVariants: ["Work"], subtitleVariants: ["35 min"],
                image: UIImage(systemName: "building.2.fill")!) { _ in }
        ]
    }

    func templateApplicationDashboardScene(
        _ scene: CPTemplateApplicationDashboardScene,
        didDisconnect dashboardController: CPDashboardController,
        from window: UIWindow
    ) {
        self.dashboardController = nil
        self.dashboardWindow = nil
    }
}

Instrument Cluster Scene

Navigation apps can display turn-by-turn guidance in the vehicle's instrument cluster using CPTemplateApplicationInstrumentClusterScene.

final class InstrumentClusterDelegate: UIResponder,
    CPTemplateApplicationInstrumentClusterSceneDelegate {

    var instrumentClusterController: CPInstrumentClusterController?

    func templateApplicationInstrumentClusterScene(
        _ scene: CPTemplateApplicationInstrumentClusterScene,
        didConnect instrumentClusterController: CPInstrumentClusterController
    ) {
        self.instrumentClusterController = instrumentClusterController
        instrumentClusterController.delegate = self
    }
}

extension InstrumentClusterDelegate: CPInstrumentClusterControllerDelegate {
    func instrumentClusterControllerDidConnect(
        _ controller: CPInstrumentClusterController) { }

    func instrumentClusterController(
        _ controller: CPInstrumentClusterController,
        didChangeCompassSetting setting: CPInstrumentClusterSetting) { }

    func instrumentClusterController(
        _ controller: CPInstrumentClusterController,
        didChangeSpeedLimitSetting setting: CPInstrumentClusterSetting) { }
}

Full Navigation Session Lifecycle

A complete navigation session flow from trip creation through completion.

import CarPlay
import MapKit

final class NavigationManager: @unchecked Sendable {
    var navigationSession: CPNavigationSession?
    var mapTemplate: CPMapTemplate?

    func createTrip(to destination: CLLocationCoordinate2D,
                    name: String) -> CPTrip {
        let origin = MKMapItem.forCurrentLocation()
        let destItem = MKMapItem(placemark: MKPlacemark(coordinate: destination))
        destItem.name = name

        return CPTrip(origin: origin, destination: destItem, routeChoices: [
            CPRouteChoice(summaryVariants: ["Fastest"],
                          additionalInformationVariants: ["Via Highway"],
                          selectionSummaryVariants: ["25 min"]),
            CPRouteChoice(summaryVariants: ["Shortest"],
                          additionalInformationVariants: ["Local Roads"],
                          selectionSummaryVariants: ["30 min"])
        ])
    }

    func startNavigation(for trip: CPTrip, routeChoice: CPRouteChoice) {
        guard let mapTemplate else { return }
        let session = mapTemplate.startNavigationSession(for: trip)
        navigationSession = session
        session.pauseTrip(for: .loading, description: "Calculating route...")

        Task {
            let maneuvers = await calculateManeuvers()
            session.upcomingManeuvers = maneuvers
            if let first = maneuvers.first {
                session.updateEstimates(
                    CPTravelEstimates(
                        distanceRemaining: Measurement(value: 12.5, unit: .miles),
                        timeRemaining: 1500),
                    for: first)
            }
        }
    }

    func updateManeuver(instruction: String, symbolName: String,
                        distanceMiles: Double, timeSeconds: TimeInterval) {
        guard let session = navigationSession else { return }
        let maneuver = CPManeuver()
        maneuver.instructionVariants = [instruction]
        maneuver.symbolImage = UIImage(systemName: symbolName)
        session.upcomingManeuvers = [maneuver]
        session.updateEstimates(
            CPTravelEstimates(
                distanceRemaining: Measurement(value: distanceMiles, unit: .miles),
                timeRemaining: timeSeconds),
            for: maneuver)
    }

    func updateCurrentRoad(_ roadName: String) {
        navigationSession?.currentRoadNameVariants = [roadName]
    }

    func reroute() {
        navigationSession?.pauseTrip(for: .rerouting, description: "Rerouting...")
        Task {
            let maneuvers = await calculateManeuvers()
            navigationSession?.upcomingManeuvers = maneuvers
        }
    }

    func finishNavigation() {
        navigationSession?.finishTrip()
        navigationSession = nil
        mapTemplate?.hideTripPreviews()
    }

    func cancelNavigation() {
        navigationSession?.cancelTrip()
        navigationSession = nil
    }

    private func calculateManeuvers() async -> [CPManeuver] {
        let turn = CPManeuver()
        turn.instructionVariants = ["Turn right onto Main St", "Right on Main"]
        turn.symbolImage = UIImage(systemName: "arrow.turn.up.right")

        let arrive = CPManeuver()
        arrive.instructionVariants = ["Arrive at destination", "Arrive"]
        arrive.symbolImage = UIImage(systemName: "mappin.circle.fill")

        return [turn, arrive]
    }
}

Lane Guidance

Provide lane guidance during active navigation to display lane arrows.

func provideLaneGuidance(for session: CPNavigationSession) {
    let guidance = CPLaneGuidance()
    guidance.instructionVariants = ["Use left two lanes"]

    let left = CPLane(); left.status = .preferred
    let middle = CPLane(); middle.status = .good
    let right = CPLane(); right.status = .notGood
    guidance.lanes = [left, middle, right]

    session.add([guidance])
    session.currentLaneGuidance = guidance
}

Navigation Alerts

Display time-sensitive alerts on the map template for incidents or closures.

func showNavigationAlert(on mapTemplate: CPMapTemplate) {
    let alert = CPNavigationAlert(
        titleVariants: ["Road Closure Ahead", "Road Closed"],
        subtitleVariants: ["Main St closed at 5th Ave"],
        image: UIImage(systemName: "exclamationmark.triangle.fill"),
        primaryAction: CPAlertAction(title: "Reroute", style: .default) { _ in
            mapTemplate.dismissNavigationAlert(animated: true, completion: nil)
        },
        secondaryAction: CPAlertAction(title: "Dismiss", style: .cancel) { _ in
            mapTemplate.dismissNavigationAlert(animated: true, completion: nil)
        },
        duration: 10.0)

    mapTemplate.present(navigationAlert: alert, animated: true)
}

Map Panning Delegate

Handle user-initiated map panning via touchscreen or rotary controller.

extension CarPlaySceneDelegate: CPMapTemplateDelegate {
    func mapTemplateDidShowPanningInterface(_ mapTemplate: CPMapTemplate) {
        // User entered panning mode
    }

    func mapTemplateDidDismissPanningInterface(_ mapTemplate: CPMapTemplate) {
        // User exited panning mode
    }

    func mapTemplate(_ mapTemplate: CPMapTemplate,
                     panWith direction: CPMapTemplate.PanDirection) {
        switch direction {
        case .up:    mapViewController.panUp()
        case .down:  mapViewController.panDown()
        case .left:  mapViewController.panLeft()
        case .right: mapViewController.panRight()
        @unknown default: break
        }
    }
}

Advanced List Patterns

Header Grid Buttons

let listTemplate = CPListTemplate(
    title: "Browse",
    sections: [CPListSection(items: items)],
    assistantCellConfiguration: nil,
    headerGridButtons: [
        CPGridButton(titleVariants: ["Favorites"],
                     image: UIImage(systemName: "heart.fill")!) { _ in },
        CPGridButton(titleVariants: ["Recents"],
                     image: UIImage(systemName: "clock.fill")!) { _ in }
    ])

Dynamic Updates

Use transactional APIs to update list content without rebuilding templates.

template.updateSections([
    CPListSection(items: newItems, header: "Results", sectionIndexTitle: nil)
])

Empty State and Loading Spinner

listTemplate.emptyViewTitleVariants = ["No Results Found"]
listTemplate.emptyViewSubtitleVariants = ["Try a different search"]
listTemplate.showsSpinnerWhileEmpty = true

// After loading:
listTemplate.showsSpinnerWhileEmpty = false
listTemplate.updateSections([CPListSection(items: loadedItems)])

Tab Badge Updates

var templates = tabBar.templates
templates[0].showsTabBadge = true
tabBar.updateTemplates(templates)

Audio App: Full Scene Delegate

import CarPlay
import MediaPlayer

final class AudioCarPlaySceneDelegate: UIResponder,
    CPTemplateApplicationSceneDelegate, CPNowPlayingTemplateObserver {

    var interfaceController: CPInterfaceController?

    func templateApplicationScene(
        _ scene: CPTemplateApplicationScene,
        didConnect interfaceController: CPInterfaceController
    ) {
        self.interfaceController = interfaceController
        configureNowPlaying()
        interfaceController.setRootTemplate(buildRootTemplate(),
                                            animated: true, completion: nil)
    }

    func templateApplicationScene(
        _ scene: CPTemplateApplicationScene,
        didDisconnectInterfaceController ic: CPInterfaceController
    ) { self.interfaceController = nil }

    private func buildRootTemplate() -> CPTabBarTemplate {
        let items = MusicLibrary.shared.playlists.map { playlist in
            let item = CPListItem(text: playlist.name,
                                  detailText: "\(playlist.count) songs",
                                  image: playlist.artwork)
            item.handler = { [weak self] _, completion in
                MusicLibrary.shared.play(playlist)
                self?.interfaceController?.pushTemplate(
                    CPNowPlayingTemplate.shared, animated: true,
                    completion: nil)
                completion()
            }
            return item
        }
        let tab = CPListTemplate(title: "Library",
                                 sections: [CPListSection(items: items)])
        tab.tabImage = UIImage(systemName: "music.note.list")
        return CPTabBarTemplate(templates: [tab])
    }

    private func configureNowPlaying() {
        let np = CPNowPlayingTemplate.shared
        np.isAlbumArtistButtonEnabled = true
        np.isUpNextButtonEnabled = true
        np.updateNowPlayingButtons([
            CPNowPlayingShuffleButton { _ in MusicLibrary.shared.toggleShuffle() },
            CPNowPlayingRepeatButton { _ in MusicLibrary.shared.toggleRepeat() }
        ])
        np.add(self)
    }

    func nowPlayingTemplateUpNextButtonTapped(_ t: CPNowPlayingTemplate) {
        let items = MusicLibrary.shared.upNext.map {
            CPListItem(text: $0.title, detailText: $0.artist)
        }
        interfaceController?.pushTemplate(
            CPListTemplate(title: "Up Next",
                           sections: [CPListSection(items: items)]),
            animated: true, completion: nil)
    }

    func nowPlayingTemplateAlbumArtistButtonTapped(_ t: CPNowPlayingTemplate) { }
}

Communication App Patterns

Contact Template

let contact = CPContact(
    name: PersonNameComponents(givenName: "Jane", familyName: "Doe"),
    image: UIImage(systemName: "person.circle.fill")!)

contact.actions = [
    CPButton(image: UIImage(systemName: "phone.fill")!) { _ in },
    CPButton(image: UIImage(systemName: "message.fill")!) { _ in }
]

let contactTemplate = CPContactTemplate(contact: contact)
interfaceController?.pushTemplate(contactTemplate, animated: true,
                                  completion: nil)

Assistant Cell for Calls

let config = CPAssistantCellConfiguration(
    position: .top, visibility: .always, assistantAction: .startCall)
let messageList = CPListTemplate(
    title: "Messages",
    sections: [CPListSection(items: messageItems)],
    assistantCellConfiguration: config)

Quick Food Ordering Flow

Food ordering apps must not exceed two levels of list hierarchy.

// Step 1: POI template showing nearby restaurants
func showRestaurants(interfaceController: CPInterfaceController) {
    let pois = fetchNearbyRestaurants().map { r -> CPPointOfInterest in
        let poi = CPPointOfInterest(
            location: r.mapItem, title: r.name, subtitle: r.cuisine,
            summary: r.rating, detailTitle: r.name,
            detailSubtitle: r.priceRange,
            detailSummary: "Open until \(r.closingTime)",
            pinImage: UIImage(systemName: "fork.knife"))
        poi.primaryButton = CPTextButton(title: "Order",
                                         textStyle: .confirm) { _ in
            self.showMenu(for: r, interfaceController: interfaceController)
        }
        return poi
    }
    let template = CPPointOfInterestTemplate(
        title: "Restaurants", pointsOfInterest: pois, selectedIndex: 0)
    template.pointOfInterestDelegate = self
    interfaceController.pushTemplate(template, animated: true, completion: nil)
}

// Step 2: Menu list
func showMenu(for restaurant: Restaurant,
              interfaceController: CPInterfaceController) {
    let items = restaurant.menuItems.map { item in
        let li = CPListItem(text: item.name, detailText: item.formattedPrice)
        li.handler = { _, completion in
            self.addToOrder(item)
            self.showOrderSummary(interfaceController: interfaceController)
            completion()
        }
        return li
    }
    interfaceController.pushTemplate(
        CPListTemplate(title: restaurant.name,
                       sections: [CPListSection(items: items)]),
        animated: true, completion: nil)
}

// Step 3: Order confirmation via CPInformationTemplate
func showOrderSummary(interfaceController: CPInterfaceController) {
    let info = CPInformationTemplate(
        title: "Order Summary", layout: .leading,
        items: currentOrder.items.map {
            CPInformationItem(title: $0.name, detail: $0.formattedPrice)
        },
        actions: [
            CPTextButton(title: "Place Order", textStyle: .confirm) { _ in
                self.placeOrder() },
            CPTextButton(title: "Cancel", textStyle: .cancel) { _ in
                interfaceController.popToRootTemplate(animated: true,
                                                      completion: nil) }
        ])
    interfaceController.pushTemplate(info, animated: true, completion: nil)
}

Session Configuration and Vehicle Limits

Query CPSessionConfiguration to adapt content to vehicle constraints.

func configureForVehicle(sessionConfig: CPSessionConfiguration) {
    let limits = sessionConfig.limitedUserInterfaces
    if limits.contains(.keyboard) {
        // Vehicle is limiting keyboard display -- adapt text entry/search.
    }

    // Always respect template maximums
    let maxItems = CPListTemplate.maximumItemCount
    let maxSections = CPListTemplate.maximumSectionCount
}

Handling Multiple Scenes

An app can have both a phone scene and a CarPlay scene active at the same time. Share state via an @Observable singleton or similar pattern.

@Observable
final class AppState {
    static let shared = AppState()
    var currentPlaylist: Playlist?
    var isPlaying = false
}

// Both PhoneSceneDelegate and CarPlaySceneDelegate read/write AppState.shared.
// CPTemplate subclasses are @MainActor -- ensure template mutations happen
// on the main actor when updating from background threads.