@capgo/capacitor-auto

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

Capacitor plugin for a small, template-safe bridge between your app and CarPlay / Android Auto.

Install

npm install @capgo/capacitor-auto
npx cap sync

What it does

• Sends a simple list template from the phone app to the car display.
• Emits carAction events when the driver selects a car UI row.
• Emits connection events when the car host connects or disconnects.
• Provides native entry points for CarPlay and Android Auto templated apps.

What it does not do

• It does not mirror a Capacitor WebView into the car display.
• It does not bypass Apple CarPlay entitlements, Google Play car app review, or driver-distraction template rules.
• It does not replace category-specific media, navigation, messaging, or calling APIs.

Usage

import { Auto } from '@capgo/capacitor-auto';

await Auto.setRootTemplate({
  title: 'Garage',
  sections: [
    {
      header: 'Doors',
      items: [
        {
          id: 'open-main-door',
          title: 'Open main door',
          subtitle: 'Tap to send the action to the phone app',
          payload: { doorId: 'main' },
        },
      ],
    },
  ],
});

await Auto.addListener('connectionChanged', (event) => {
  console.log('Car connected:', event.connected, event.platform);
});

await Auto.addListener('carAction', async (event) => {
  if (event.id === 'open-main-door') {
    await openGarageDoor(event.payload?.doorId);
  }
});

iOS setup

CarPlay apps require Apple approval for the matching CarPlay entitlement and must use Apple-approved CarPlay templates for the app category.

Add a CarPlay scene configuration to the app Info.plist and point its delegate to the plugin scene delegate. The exact module prefix depends on how the plugin is integrated:

• Swift Package Manager target: AutoPlugin.AutoCarPlaySceneDelegate
• CocoaPods module: CapgoCapacitorAuto.AutoCarPlaySceneDelegate

<key>UIApplicationSceneManifest</key>
<dict>
  <key>UIApplicationSupportsMultipleScenes</key>
  <true/>
  <key>UISceneConfigurations</key>
  <dict>
    <key>CPTemplateApplicationSceneSessionRoleApplication</key>
    <array>
      <dict>
        <key>UISceneClassName</key>
        <string>CPTemplateApplicationScene</string>
        <key>UISceneDelegateClassName</key>
        <string>AutoPlugin.AutoCarPlaySceneDelegate</string>
      </dict>
    </array>
  </dict>
</dict>

Android setup

The plugin includes an Android Auto CarAppService, declares the template capability, and defaults to the IOT car app category. Your app still has to qualify for the declared car category before publishing on Google Play.

If your app uses another category, override the service declaration in your app manifest and use the category Google requires for your use case.

Compatibility

Plugin version	Capacitor compatibility	Maintained
v8.*.*	v8.*.*	Yes

API

• isAvailable()
• setRootTemplate(...)
• sendMessage(...)
• getPluginVersion()
• addListener('connectionChanged', ...)
• addListener('carAction', ...)
• addListener('messageReceived', ...)
• removeAllListeners()
• Interfaces
• Type Aliases

isAvailable()

isAvailable() => Promise<AutoAvailability>

Returns whether the current platform supports this plugin and whether a car is connected.

Returns: Promise<AutoAvailability>

---

setRootTemplate(...)

setRootTemplate(options: AutoTemplateOptions) => Promise<void>

Sets the root car template. Use this to push phone app state to the car display.

Param	Type
options	AutoTemplateOptions

---

sendMessage(...)

sendMessage(options: AutoMessageOptions) => Promise<void>

Sends an application-defined message to the native car bridge.

Param	Type
options	AutoMessageOptions

---

getPluginVersion()

getPluginVersion() => Promise<PluginVersionResult>

Returns the platform implementation version marker.

Returns: Promise<PluginVersionResult>

---

addListener('connectionChanged', ...)

addListener(eventName: 'connectionChanged', listenerFunc: (event: AutoConnectionChangedEvent) => void) => Promise<PluginListenerHandle>

Fired when the car host connects or disconnects.

Param	Type
eventName	'connectionChanged'
listenerFunc	(event: AutoConnectionChangedEvent) => void

Returns: Promise<PluginListenerHandle>

---

addListener('carAction', ...)

addListener(eventName: 'carAction', listenerFunc: (event: AutoActionEvent) => void) => Promise<PluginListenerHandle>

Fired when the user selects an action row in the car UI.

Param	Type
eventName	'carAction'
listenerFunc	(event: AutoActionEvent) => void

Returns: Promise<PluginListenerHandle>

---

addListener('messageReceived', ...)

addListener(eventName: 'messageReceived', listenerFunc: (event: AutoMessageEvent) => void) => Promise<PluginListenerHandle>

Fired for application-defined native car bridge messages.

Param	Type
eventName	'messageReceived'
listenerFunc	(event: AutoMessageEvent) => void

Returns: Promise<PluginListenerHandle>

---

removeAllListeners()

removeAllListeners() => Promise<void>

---

Interfaces

AutoAvailability

Prop	Type	Description
available	boolean	Whether the current platform ships a native car integration.
connected	boolean	Whether a car host is currently connected to this app.
platform	AutoPlatform	Platform that answered the request.

AutoTemplateOptions

Prop	Type	Description
title	string	Title shown at the top of the car template.
sections	AutoTemplateSection[]	Sections and rows to show in the car UI.
emptyText	string	Text shown when there are no rows.

AutoTemplateSection

Prop	Type	Description
header	string	Optional section title. Supported by CarPlay; Android Auto currently flattens sections.
items	AutoTemplateItem[]	Rows to render in this section.

AutoTemplateItem

Prop	Type	Description	Default
id	string	Stable action id sent back in the carAction event when the row is selected.
title	string	Primary row text.
subtitle	string	Optional secondary row text.
payload	AutoPayload	Optional value returned with the carAction event.
enabled	boolean	Whether the row can be selected.	true

AutoPayload

AutoMessageOptions

Prop	Type	Description
type	string	Application-defined message type.
payload	AutoPayload	Optional application-defined payload.

PluginVersionResult

Prop	Type	Description
version	string	Version identifier returned by the platform implementation.

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

AutoConnectionChangedEvent

Prop	Type
connected	boolean
platform	AutoPlatform

AutoActionEvent

Prop	Type
id	string
title	string
payload	AutoPayload
platform	AutoPlatform

AutoMessageEvent

Prop	Type
type	string
payload	AutoPayload
platform	AutoPlatform

Type Aliases

AutoPlatform

'ios' | 'android' | 'web'