Building a Qibla Compass for the Web

There are native apps for this. Android and iOS both have qibla apps with tight hardware integration. So when I added a compass to islami.click ↗, the reasonable question was: why bother with a browser version?

The answer is friction. A web page loads immediately. No install, no permission dialogs, no “update available.” For something you use a few times a week at most, the low barrier matters.

The Math#

The compass shows the direction of the Ka’bah in Mecca (21.4225°N, 39.8262°E). Given the user’s GPS coordinates, you need the bearing - the angle clockwise from North along the shortest path on the globe’s surface. That’s the great-circle bearing formula:

Δλ = destination_lng - source_lng  (in radians)
x  = sin(Δλ) × cos(dest_lat)
y  = cos(src_lat) × sin(dest_lat) − sin(src_lat) × cos(dest_lat) × cos(Δλ)
bearing = atan2(x, y) × (180 / π)

The result is degrees from -180 to 180. Normalize to 0-360 with (bearing + 360) % 360.

The Device API#

The browser exposes DeviceOrientationEvent to read the magnetometer. On mobile, event.alpha gives the compass heading in degrees clockwise from North. On desktop, there is no magnetometer - alpha stays null or returns 0.

The needle angle is:

needleAngle = bearing - heading

When heading = 0 (desktop), the needle sits at bearing degrees from North. Technically correct - it points toward Mecca relative to a fixed North-up reference - but it doesn’t track physical movement, which makes it useless as a live compass.

The Desktop Problem#

I tried making the compass look interactive on desktop anyway: animated movement, a pulsing ring, anything to signal “this is working.” Then I looked at how Google Maps and Apple Maps handle it. Both show a static north-facing map unless a real heading signal is present. They don’t fake it.

The right answer for desktop is a static display. The compass needle points toward Mecca from North-up. An info panel shows the exact bearing in degrees, the cardinal direction (NNE, SW, etc.), the distance in kilometers, and the user’s coordinates. That’s more useful than a compass that doesn’t respond to physical orientation.

Mobile keeps the live rotating compass. Desktop gets the static one.

Calibration#

Magnetometers drift. Metal objects, electronics, and concrete floors all interfere with the reading. A common symptom: the needle spins even when the phone is held still.

The fix is a figure-8 motion - hold the phone flat and trace a figure-8 in the air a few times. This recalibrates the magnetometer’s internal offset. The steps (figure-8, avoid metal, rotate in all axes) cover the three main calibration techniques documented by both Android and iOS.

The calibration button appears only on mobile. It’s irrelevant on desktop where there is no compass hardware to calibrate.

What You Don’t Control#

DeviceOrientationEvent requires user permission on iOS 13+. The browser prompts the user; you can’t pre-grant it. If the user denies, heading stays at 0 and the compass falls back to static bearing mode.

Some Android browsers fire the event but return constant values for a few seconds on cold start. Adding a hasCompass flag - set to true only after the heading changes by more than a small threshold - prevents showing a live compass until the sensor actually responds.

Is This Right for You?#

Use the Web DeviceOrientation API if:

• You need a compass feature embedded in a web app without requiring a native install
• Static bearing on desktop is acceptable (it almost always is for qibla use)
• You’re okay with iOS prompting for sensor permission on first use

Skip it if:

• You need sub-second compass latency (native sensors have lower overhead)
• Your target audience denies sensor permissions by policy
• You need compass access in a background context (the API only works while the page is visible)