> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rebellapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# my.startCompass

> Start listening for compass heading data.

Use this API to start the compass sensor. After calling this, you can use `my.onCompassChange` to receive compass heading data.

## Parameters

| Property | Type     | Required | Description                                                                                                                                                                                                               |
| -------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| interval | String   | No       | Execution frequency of the callback functions that monitor compass data updates (the listeners registered with `my.onCompassChange`). Valid values: `game` (\~20ms), `ui` (\~60ms), `normal` (\~200ms). Default: `normal` |
| success  | Function | No       | Callback on success                                                                                                                                                                                                       |
| fail     | Function | No       | Callback on failure                                                                                                                                                                                                       |
| complete | Function | No       | Callback that always executes                                                                                                                                                                                             |

## Code Example

### Basic Usage

```javascript theme={null}
my.startCompass({
  success() {
    console.log('Compass started');
    my.onCompassChange((res) => {
      console.log('Heading:', res.direction);
    });
  }
});
```

### Navigation App

```javascript theme={null}
Page({
  onLoad() {
    my.startCompass({
      success: () => {
        my.onCompassChange(this.updateCompass);
      },
      fail(err) {
        my.showToast({
          content: 'Compass not available',
          type: 'fail'
        });
      }
    });
  },

  updateCompass(res) {
    this.setData({
      heading: Math.round(res.direction),
      compassRotation: -res.direction
    });
  },

  onUnload() {
    my.offCompassChange(this.updateCompass);
  }
});
```

### Combining with Location

```javascript theme={null}
Page({
  async onLoad() {
    // Start compass for heading
    my.startCompass({
      success: () => {
        my.onCompassChange(this.updateHeading);
      }
    });

    // Get current location
    my.getLocation({
      success: (res) => {
        this.setData({
          latitude: res.latitude,
          longitude: res.longitude
        });
      }
    });
  },

  updateHeading(res) {
    this.setData({ heading: res.direction });
  }
});
```

<Warning>
  The compass may not be available on all devices. Always handle the `fail` callback to provide a fallback experience.
</Warning>

## Related APIs

<CardGroup cols={2}>
  <Card title="my.onCompassChange" icon="compass" href="/jsapi/device/compass/my.onCompassChange">
    Listen for compass data
  </Card>

  <Card title="my.offCompassChange" icon="xmark" href="/jsapi/device/compass/my.offCompassChange">
    Stop listening
  </Card>
</CardGroup>