CarPlay
Build category-entitled, template-based CarPlay apps for the vehicle display.
Scope: Swift 6.4, 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
Workflow
- Confirm the app category is eligible and obtain the exact CarPlay entitlement before building templates.
- Configure the CarPlay scene role and retain the interface controller supplied by the scene delegate.
- Build only category-allowed template hierarchies and respect tab, list, image, and interaction limits.
- Keep navigation, audio, communication, and point-of-interest behavior behind their specific templates and completion handlers.
- Verify reconnect, day/night appearance, multiple display sizes, driving restrictions, and physical vehicle behavior where required.
Route by Task
- Read core implementation details for entitlements, scenes, templates, navigation, audio, communication, POI, and Simulator testing.
- Read extended CarPlay patterns for dashboard/instrument-cluster scenes, complete navigation flows, and complex tab composition.
Core Decisions
- Do not draw arbitrary custom UI where CarPlay requires templates.
- Never push or present templates that Apple exposes only as shared/system surfaces.
- Use the correct scene delegate callback for the app category and display role.
- Call template completion handlers exactly once and keep handlers responsive.
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
References
1---2name: carplay3description: "Builds eligible CarPlay navigation, audio, communication, EV charging, parking, or ordering apps with template scenes. Use for entitlements, scene delegates, interface-controller hierarchies, lists, maps, Now Playing, dashboard displays, or CarPlay Simulator verification."4metadata:5 source: https://skillmd.com/skills/thiennc-tesoglobal/carplay6---78# CarPlay910Build category-entitled, template-based CarPlay apps for the vehicle display.11Scope: Swift 6.4, iOS 26+.1213See [references/carplay-patterns.md](references/carplay-patterns.md) for extended patterns including full14navigation sessions, dashboard scenes, and advanced template composition.1516Scope boundary: full CarPlay framework apps use category entitlements,17`CPTemplateApplicationScene`, `CPTemplateApplicationSceneDelegate`,18`CPInterfaceController`, and system `CPTemplate` navigation. CarPlay-visible19WidgetKit widgets and ActivityKit Live Activities are separate system20experiences; route their implementation to those domains while keeping21CarPlay-specific validation here.2223## Contents2425- [Workflow](#workflow)26- [Route by Task](#route-by-task)27- [Core Decisions](#core-decisions)28- [Common Mistakes](#common-mistakes)29- [Review Checklist](#review-checklist)30- [References](#references)3132## Workflow33341. Confirm the app category is eligible and obtain the exact CarPlay entitlement before building templates.352. Configure the CarPlay scene role and retain the interface controller supplied by the scene delegate.363. Build only category-allowed template hierarchies and respect tab, list, image, and interaction limits.374. Keep navigation, audio, communication, and point-of-interest behavior behind their specific templates and completion handlers.385. Verify reconnect, day/night appearance, multiple display sizes, driving restrictions, and physical vehicle behavior where required.3940## Route by Task4142- Read [core implementation details](references/core-implementation.md) for entitlements, scenes, templates, navigation, audio, communication, POI, and Simulator testing.43- Read [extended CarPlay patterns](references/carplay-patterns.md) for dashboard/instrument-cluster scenes, complete navigation flows, and complex tab composition.4445## Core Decisions4647- Do not draw arbitrary custom UI where CarPlay requires templates.48- Never push or present templates that Apple exposes only as shared/system surfaces.49- Use the correct scene delegate callback for the app category and display role.50- Call template completion handlers exactly once and keep handlers responsive.5152## Common Mistakes5354### DON'T: Use the wrong scene delegate method5556Navigation apps must implement `templateApplicationScene(_:didConnect:to:)`57(with `CPWindow`). Non-navigation apps use58`templateApplicationScene(_:didConnect:)` (no window). Using the wrong59variant produces no CarPlay UI.6061### DON'T: Draw custom UI in the navigation window6263`CPWindow` is exclusively for map content. All overlays, alerts, and64controls must use CarPlay templates.6566### DON'T: Push or present CPTabBarTemplate6768`CPTabBarTemplate` can only be set as root. Pushing or presenting it fails.69Use `setRootTemplate(_:animated:completion:)`.7071### DON'T: Instantiate CPNowPlayingTemplate7273Use `CPNowPlayingTemplate.shared`. Creating a new instance causes issues.7475### DON'T: Add handlers to CPMessageListItem7677`CPMessageListItem` is Siri-managed, unlike `CPListItem`. Do not set78`message.handler`; use the item configuration and `userInfo` for context.7980### DON'T: Treat widgets as CarPlay template apps8182CarPlay-visible widgets and Live Activities belong to WidgetKit and83ActivityKit. Use this skill for category-entitled CarPlay template app scenes84and for validating those surfaces in the car context.8586### DON'T: Ignore vehicle display limits8788Check `CPSessionConfiguration.limitedUserInterfaces` and respect89`maximumItemCount` / `maximumSectionCount` on list templates.9091### DON'T: Forget to call the completion handler9293`CPListItem.handler` must call its completion handler in every code path.94Failure leaves the list in a loading state.9596## Review Checklist9798- [ ] Correct CarPlay entitlement key in `Entitlements.plist`99- [ ] `UIApplicationSupportsMultipleScenes` set to `true`100- [ ] `CPTemplateApplicationSceneSessionRoleApplication` scene in Info.plist101- [ ] Scene delegate class name matches `UISceneDelegateClassName`102- [ ] Correct delegate method used (with/without `CPWindow`)103- [ ] Root template set in `didConnect` before returning104- [ ] Interface controller and window references cleared on disconnect105- [ ] `CPTabBarTemplate` only used as root, never pushed106- [ ] `CPNowPlayingTemplate.shared` used, not a new instance107- [ ] Communication rows use `CPMessageListItem` without custom handlers108- [ ] WidgetKit/ActivityKit surfaces routed outside CarPlay template app code109- [ ] `maximumItemCount`/`maximumSectionCount` checked before populating lists110- [ ] `CPListItem.handler` calls completion in every path111- [ ] Map-only content in `CPWindow` root view controller (navigation apps)112- [ ] App functions while iPhone is locked113- [ ] Tested at minimum, standard, and high-resolution simulator sizes114- [ ] Audio session deactivated when not actively playing115116## References117118- Extended patterns (dashboard, instrument cluster, full nav flow, tab composition): [references/carplay-patterns.md](references/carplay-patterns.md)119- [CarPlay framework](https://sosumi.ai/documentation/carplay)120- [CPTemplateApplicationSceneDelegate](https://sosumi.ai/documentation/carplay/cptemplateapplicationscenedelegate)121- [CPInterfaceController](https://sosumi.ai/documentation/carplay/cpinterfacecontroller)122- [CPMapTemplate](https://sosumi.ai/documentation/carplay/cpmaptemplate)123- [CPListTemplate](https://sosumi.ai/documentation/carplay/cplisttemplate)124- [CPNowPlayingTemplate](https://sosumi.ai/documentation/carplay/cpnowplayingtemplate)125- [CPPointOfInterestTemplate](https://sosumi.ai/documentation/carplay/cppointofinteresttemplate)126- [CPNavigationSession](https://sosumi.ai/documentation/carplay/cpnavigationsession)127- [Requesting CarPlay Entitlements](https://sosumi.ai/documentation/carplay/requesting-carplay-entitlements)128- [Displaying Content in CarPlay](https://sosumi.ai/documentation/carplay/displaying-content-in-carplay)129- [Using the CarPlay Simulator](https://sosumi.ai/documentation/carplay/using-the-carplay-simulator)130- [CarPlay HIG](https://sosumi.ai/design/human-interface-guidelines/carplay)131- [Core implementation details](references/core-implementation.md) -- setup, API wiring, and focused implementation recipes moved out of the entrypoint.