---
description: Capacitor plugin to read the device compass heading on Android and iOS. Get the current heading, listen for live updates, and read true north on iOS.
title: Capacitor Compass Plugin for Android & iOS - Capawesome
image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/compass.png
---
[Skip to content ](#capacitor-compass-plugin)
[π Introducing the **Capacitor Vault** plugin β store secrets behind biometrics or a device passcode. ](/blog/announcing-the-capacitor-vault-plugin/)
* [ SDKs ](/docs/sdks/)
* [ Configuration ](#configuration)
* [ Usage ](#usage)
* [ API ](#api)
* [ Type Aliases ](#type-aliases)
* [ Changelog ](#changelog)
* [ License ](#license)
* [ Contacts ](/docs/sdks/capacitor/contacts/)
* [ Datetime Picker ](/docs/sdks/capacitor/datetime-picker/)
* [ Facebook Sign-In ](/docs/sdks/capacitor/facebook-sign-in/)
* [ File Compressor ](/docs/sdks/capacitor/file-compressor/)
* [ File Opener ](/docs/sdks/capacitor/file-opener/)
* [ File Picker ](/docs/sdks/capacitor/file-picker/)
* [ Firebase ](/docs/sdks/capacitor/firebase/)
* [ Formbricks ](/docs/sdks/capacitor/formbricks/)
* [ Geocoder ](/docs/sdks/capacitor/geocoder/)
* [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/)
* [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/)
* [ Gyroscope ](/docs/sdks/capacitor/gyroscope/)
* [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/)
* [ Install Referrer ](/docs/sdks/capacitor/install-referrer/)
* [ Keep Awake ](/docs/sdks/capacitor/keep-awake/)
* [ libSQL ](/docs/sdks/capacitor/libsql/)
* [ Live Update ](/docs/sdks/capacitor/live-update/)
* [ Localization ](/docs/sdks/capacitor/localization/)
* [ Mail Composer ](/docs/sdks/capacitor/mail-composer/)
* [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/)
* [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/)
* [ Media Session ](/docs/sdks/capacitor/media-session/)
* [ ML Kit ](/docs/sdks/capacitor/mlkit/)
* [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/)
* [ NFC ](/docs/sdks/capacitor/nfc/)
* [ Node.js ](/docs/sdks/capacitor/nodejs/)
* [ OAuth ](/docs/sdks/capacitor/oauth/)
* [ Passkeys ](/docs/sdks/capacitor/passkeys/)
* [ Password Autofill ](/docs/sdks/capacitor/password-autofill/)
* [ Pedometer ](/docs/sdks/capacitor/pedometer/)
* [ Photo Editor ](/docs/sdks/capacitor/photo-editor/)
* [ PixLive ](/docs/sdks/capacitor/pixlive/)
* [ PostHog ](/docs/sdks/capacitor/posthog/)
* [ Printer ](/docs/sdks/capacitor/printer/)
* [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/)
* [ Purchases ](/docs/sdks/capacitor/purchases/)
* [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/)
* [ Root Detection ](/docs/sdks/capacitor/root-detection/)
* [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/)
* [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/)
* [ Screenshot ](/docs/sdks/capacitor/screenshot/)
* [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/)
* [ Shake ](/docs/sdks/capacitor/shake/)
* [ Silent Mode ](/docs/sdks/capacitor/silent-mode/)
* [ SIM ](/docs/sdks/capacitor/sim/)
* [ SMS Composer ](/docs/sdks/capacitor/sms-composer/)
* [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/)
* [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/)
* [ Share Target ](/docs/sdks/capacitor/share-target/)
* [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/)
* [ SQLite ](/docs/sdks/capacitor/sqlite/)
* [ Superwall ](/docs/sdks/capacitor/superwall/)
* [ Thermal State ](/docs/sdks/capacitor/thermal-state/)
* [ Torch ](/docs/sdks/capacitor/torch/)
* [ Vault ](/docs/sdks/capacitor/vault/)
* [ Volume ](/docs/sdks/capacitor/volume/)
* [ Wallet ](/docs/sdks/capacitor/wallet/)
* [ Wifi ](/docs/sdks/capacitor/wifi/)
* [ Zip ](/docs/sdks/capacitor/zip/)
* [ Cordova ](/docs/sdks/cordova/)
* [ Cloud ](/docs/cloud/)
* [ Integrations ](/docs/cloud/live-updates/integrations/)
* Concepts
* Reference
* [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/)
* [ FAQ ](/docs/cloud/live-updates/faq/)
* [ Native Builds ](/docs/cloud/native-builds/)
* [ Set Up Environments ](/docs/cloud/native-builds/environments/)
* [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/)
* [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/)
* [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/)
* [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/)
* [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/)
* [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/)
* [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/)
* [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/)
* [ Build without Git ](/docs/cloud/native-builds/build-without-git/)
* [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/)
* [ Integrations ](/docs/cloud/native-builds/integrations/)
* Reference
* [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/)
* [ FAQ ](/docs/cloud/native-builds/faq/)
* [ App Store Publishing ](/docs/cloud/app-store-publishing/)
* [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/)
* [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/)
* [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/)
* [ FAQ ](/docs/cloud/app-store-publishing/faq/)
* [ Automations ](/docs/cloud/automations/)
* [ Reference ](/docs/cloud/automations/reference/)
* [ Troubleshooting ](/docs/cloud/automations/troubleshooting/)
* [ FAQ ](/docs/cloud/automations/faq/)
* [ Assist ](/docs/cloud/assist/)
* [ CLI ](/docs/cloud/cli/)
* APIs and SDKs
* [ Webhooks ](/docs/cloud/webhooks/)
* [ Integrations ](/docs/cloud/integrations/)
* Account
* [ Organization ](/docs/cloud/organizations/)
* [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/)
* [ Audit Logs ](/docs/cloud/organizations/audit-logs/)
* [ Billing ](/docs/cloud/organizations/billing/)
* [ License Keys ](/docs/cloud/license-keys/)
* [ AI ](/docs/ai/)
* [ Insiders ](/docs/insiders/)
* [ Billing & Plans ](/docs/insiders/billing-and-plans/)
* [ FAQ ](/docs/insiders/faq/)
* [ License ](https://capawesome.io/legal/eula/)
* [ Support ](/docs/support/)
* [ Contributing ](/docs/contributing/)
* Contributing code
* [ Code of Conduct ](/docs/contributing/code-of-conduct/)
* [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion)
* [ Blog ](/blog/)
* Categories
* [ Configuration ](#configuration)
* [ Usage ](#usage)
* [ API ](#api)
* [ Type Aliases ](#type-aliases)
* [ Changelog ](#changelog)
* [ License ](#license)
# Capacitor Compass Plugin[ΒΆ](#capacitor-compass-plugin "Permanent link")
Capacitor plugin for reading the device compass heading.
[  ](https://cloud.capawesome.io/)
## Features[ΒΆ](#features "Permanent link")
* π§ **Heading**: Read the current compass heading on demand.
* π **Live updates**: Listen for continuous heading changes.
* π **True north**: Read the true (geographic) north heading on iOS.
* π¦ **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS.
* π **Up-to-date**: Always supports the latest Capacitor version.
Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look!
## Newsletter[ΒΆ](#newsletter "Permanent link")
Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/).
## Compatibility[ΒΆ](#compatibility "Permanent link")
| Plugin Version | Capacitor Version | Status |
| -------------- | ----------------- | -------------- |
| 0.x.x | \>=8.x.x | Active support |
## Installation[ΒΆ](#installation "Permanent link")
You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command:
`[](#%5F%5Fcodelineno-0-1)npx skills add capawesome-team/skills --skill capacitor-plugins
`
Then use the following prompt:
`` [](#%5F%5Fcodelineno-1-1) Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-compass` plugin in my project.
``
If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below:
`[](#%5F%5Fcodelineno-2-1)npm install @capawesome/capacitor-compass
[](#%5F%5Fcodelineno-2-2)npx cap sync
`
This plugin is only available on **Android** and **iOS**. On the Web, all methods reject as unimplemented.
### iOS[ΒΆ](#ios "Permanent link")
#### Privacy Descriptions[ΒΆ](#privacy-descriptions "Permanent link")
The magnetic heading is available without any permission. To also read the true (geographic) north heading, location services must be enabled and the `NSLocationWhenInUseUsageDescription` key must be added to the `Info.plist` file of your app.
`[](#%5F%5Fcodelineno-3-1)NSLocationWhenInUseUsageDescription
[](#%5F%5Fcodelineno-3-2)Your location is used to determine the true (geographic) north heading.
`
If the key is missing or location permission is not granted, the `trueHeading` value is `null`.
## Configuration[ΒΆ](#configuration "Permanent link")
No configuration required for this plugin.
## Usage[ΒΆ](#usage "Permanent link")
`[](#%5F%5Fcodelineno-4-1)import { Compass } from '@capawesome/capacitor-compass';
[](#%5F%5Fcodelineno-4-2)
[](#%5F%5Fcodelineno-4-3)const getHeading = async () => {
[](#%5F%5Fcodelineno-4-4) const heading = await Compass.getHeading();
[](#%5F%5Fcodelineno-4-5) return heading;
[](#%5F%5Fcodelineno-4-6)};
[](#%5F%5Fcodelineno-4-7)
[](#%5F%5Fcodelineno-4-8)const isAvailable = async () => {
[](#%5F%5Fcodelineno-4-9) const { available } = await Compass.isAvailable();
[](#%5F%5Fcodelineno-4-10) return available;
[](#%5F%5Fcodelineno-4-11)};
[](#%5F%5Fcodelineno-4-12)
[](#%5F%5Fcodelineno-4-13)const startHeadingUpdates = async () => {
[](#%5F%5Fcodelineno-4-14) await Compass.startHeadingUpdates();
[](#%5F%5Fcodelineno-4-15)};
[](#%5F%5Fcodelineno-4-16)
[](#%5F%5Fcodelineno-4-17)const stopHeadingUpdates = async () => {
[](#%5F%5Fcodelineno-4-18) await Compass.stopHeadingUpdates();
[](#%5F%5Fcodelineno-4-19)};
[](#%5F%5Fcodelineno-4-20)
[](#%5F%5Fcodelineno-4-21)const addHeadingChangeListener = async () => {
[](#%5F%5Fcodelineno-4-22) await Compass.addListener('headingChange', heading => {
[](#%5F%5Fcodelineno-4-23) console.log(heading);
[](#%5F%5Fcodelineno-4-24) });
[](#%5F%5Fcodelineno-4-25)};
[](#%5F%5Fcodelineno-4-26)
[](#%5F%5Fcodelineno-4-27)const removeAllListeners = async () => {
[](#%5F%5Fcodelineno-4-28) await Compass.removeAllListeners();
[](#%5F%5Fcodelineno-4-29)};
`
## API[ΒΆ](#api "Permanent link")
* [addListener('headingChange', ...)](#addlistenerheadingchange-)
* [getHeading()](#getheading)
* [isAvailable()](#isavailable)
* [removeAllListeners()](#removealllisteners)
* [startHeadingUpdates()](#startheadingupdates)
* [stopHeadingUpdates()](#stopheadingupdates)
* [Interfaces](#interfaces)
* [Type Aliases](#type-aliases)
### addListener('headingChange', ...)[ΒΆ](#addlistenerheadingchange "Permanent link")
`[](#%5F%5Fcodelineno-5-1)addListener(eventName: 'headingChange', listenerFunc: (event: HeadingChangeEvent) => void) => Promise
`
Add a listener for heading changes.
Only available on Android and iOS.
| Param | Type |
| ---------------- | ------------------------------------ |
| **eventName** | 'headingChange' |
| **listenerFunc** | (event: [Heading](#heading)) => void |
**Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>`
**Since:** 0.1.0
---
### getHeading()[ΒΆ](#getheading "Permanent link")
`[](#%5F%5Fcodelineno-6-1)getHeading() => Promise
`
Get the current device heading.
This method returns the most recent heading reading from the device's compass sensor.
Only available on Android and iOS.
**Returns:** `Promise<[Heading](#heading)>`
**Since:** 0.1.0
---
### isAvailable()[ΒΆ](#isavailable "Permanent link")
`[](#%5F%5Fcodelineno-7-1)isAvailable() => Promise
`
Check if the compass sensor is available on the device.
Only available on Android and iOS.
**Returns:** `Promise<[IsAvailableResult](#isavailableresult)>`
**Since:** 0.1.0
---
### removeAllListeners()[ΒΆ](#removealllisteners "Permanent link")
`[](#%5F%5Fcodelineno-8-1)removeAllListeners() => Promise
`
Remove all listeners for this plugin.
Only available on Android and iOS.
**Since:** 0.1.0
---
### startHeadingUpdates()[ΒΆ](#startheadingupdates "Permanent link")
`[](#%5F%5Fcodelineno-9-1)startHeadingUpdates() => Promise
`
Start emitting `headingChange` events.
Only available on Android and iOS.
**Since:** 0.1.0
---
### stopHeadingUpdates()[ΒΆ](#stopheadingupdates "Permanent link")
`[](#%5F%5Fcodelineno-10-1)stopHeadingUpdates() => Promise
`
Stop emitting `headingChange` events.
Only available on Android and iOS.
**Since:** 0.1.0
---
### Interfaces[ΒΆ](#interfaces "Permanent link")
#### PluginListenerHandle[ΒΆ](#pluginlistenerhandle "Permanent link")
| Prop | Type |
| ---------- | ------------------- |
| **remove** | () => Promise |
#### Heading[ΒΆ](#heading "Permanent link")
| Prop | Type | Description | Since |
| ------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- |
| **accuracy** | number \| null | The maximum deviation between the reported heading and the true heading in degrees. A negative value or null indicates that the accuracy is invalid or unknown. | 0.1.0 |
| **magneticHeading** | number | The heading relative to magnetic north in degrees. The value ranges from 0 to 360, where 0 means the device is pointing towards magnetic north. | 0.1.0 |
| **trueHeading** | number \| null | The heading relative to true (geographic) north in degrees. The value ranges from 0 to 360, where 0 means the device is pointing towards true north. Returns null if the true heading cannot be determined. On Android, this value is always null. On iOS, this value requires location services to be enabled and the NSLocationWhenInUseUsageDescription key to be set. Otherwise, it is null. | 0.1.0 |
#### IsAvailableResult[ΒΆ](#isavailableresult "Permanent link")
| Prop | Type | Description | Since |
| ------------- | ------- | ------------------------------------------------------ | ----- |
| **available** | boolean | Whether the compass sensor is available on the device. | 0.1.0 |
### Type Aliases[ΒΆ](#type-aliases "Permanent link")
#### HeadingChangeEvent[ΒΆ](#headingchangeevent "Permanent link")
`[Heading](#heading)`
#### GetHeadingResult[ΒΆ](#getheadingresult "Permanent link")
`[Heading](#heading)`
## Changelog[ΒΆ](#changelog "Permanent link")
See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/compass/CHANGELOG.md).
## License[ΒΆ](#license "Permanent link")
See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/compass/LICENSE).
July 7, 2026
Back to top
```json
{"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/compass/#article", "headline": "Capacitor Compass Plugin for Android & iOS", "name": "Capacitor Compass Plugin for Android & iOS", "description": "Capacitor plugin to read the device compass heading on Android and iOS. Get the current heading, listen for live updates, and read true north on iOS.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/compass/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/compass/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/compass/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/compass/#software", "name": "Capacitor Compass Plugin for Android & iOS", "description": "Capacitor plugin to read the device compass heading on Android and iOS. Get the current heading, listen for live updates, and read true north on iOS.", "url": "https://capawesome.io/docs/sdks/capacitor/compass/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]}
```