Skip to content

API in Capabilities

Generic Sensor API

Published Updated

Limited availabilityNot supported in Firefox (Desktop), Firefox (Android), Safari (macOS), Safari (iOS)W3C draft

The Generic Sensor API provides a shared Sensor base interface (start(), stop(), reading, activate, and error events) that concrete device sensors extend: Accelerometer, LinearAccelerationSensor, GravitySensor, Gyroscope, AbsoluteOrientationSensor, RelativeOrientationSensor, Magnetometer, and AmbientLightSensor. Pages construct a concrete class, call start(), and read the latest sample from its attributes inside a reading handler; readings are only delivered to a visible, focused document in a secure context.

Only Chromium implements these interfaces, and some require a flag. Chrome 67 (Edge 79, Samsung Internet 9.0, Android WebView 67) ships Accelerometer, LinearAccelerationSensor, Gyroscope, AbsoluteOrientationSensor, and RelativeOrientationSensor without a flag, and Chrome 91 added GravitySensor. Magnetometer and AmbientLightSensor exist since Chrome 56 only behind chrome://flags/#enable-experimental-web-platform-features. Firefox and Safari implement none of these interfaces (BCD api.Accelerometer, api.Magnetometer, api.AmbientLightSensor); the DeviceMotionEvent path is the cross-engine fallback for motion data.

new Accelerometer()
new Accelerometer(options)
new Gyroscope(options)
new AbsoluteOrientationSensor(options)
new Magnetometer(options)
new AmbientLightSensor(options)
sensor.start()
sensor.stop()

Constructors are synchronous and return an idle sensor. start() and stop() return undefined; activation happens asynchronously and is signalled by the activate event, after which activated is true, hasReading becomes true on the first sample, and timestamp carries the sample’s DOMHighResTimeStamp. Motion sensors expose x, y, z (m/s² for accelerometers, rad/s for Gyroscope, µT for Magnetometer); orientation sensors expose quaternion plus populateMatrix(target); AmbientLightSensor exposes illuminance in lux. Every interface is [SecureContext].

Each constructor takes one optional options dictionary. The base SensorOptions has one member; the motion and orientation sensors extend it with referenceFrame.

Member Type Required Applies to Description
frequency double (Hz) No All sensors Requested sampling and reporting rate. The specification makes it a hint: the browser may clamp it to the platform sensor’s limits. Chromium caps accelerometer, gyroscope, and orientation sensors at 60 Hz (default 10 Hz) and Magnetometer and AmbientLightSensor at 10 Hz (sensor_traits.h).
referenceFrame "device" or "screen" No, defaults to "device" Accelerometer, LinearAccelerationSensor, GravitySensor, Gyroscope, Magnetometer, both orientation sensors Coordinate system for the readings. "screen" rotates the axes with the current screen orientation so a landscape tablet still reports “up” as positive y.

Readings are quantized before they reach the page. The Accelerometer specification rounds x, y, and z to the nearest 0.1 m/s², a fingerprinting mitigation that also sets the floor for how small a motion you can detect.

The constructor throws synchronously; start() does not throw and reports failure through an error event whose event.error is the DOMException below.

Exception Where Condition
SecurityError Constructor The document is not allowed to use the sensor’s policy-controlled feature (accelerometer, gyroscope, magnetometer, or ambient-light-sensor; orientation sensors need accelerometer plus gyroscope, and the absolute one also magnetometer). A cross-origin iframe needs these in its allow attribute.
NotSupportedError Constructor options contains a key the sensor type does not support (the “initialize a sensor object” step).
NotAllowedError error event The sensor permission request resolved to "denied". Chromium ties these permissions to the accelerometer, gyroscope, magnetometer, and ambient-light-sensor names in navigator.permissions.query().
NotReadableError error event “Connect to sensor” failed: the device has no such sensor, the platform refused it, or the sensor stopped mid-use. The sensor returns to "idle" and stays silent until start() is called again.

A ReferenceError from new Magnetometer() means the browser has no definition for the constructor; it does not report a sensor failure. Check for the constructor before calling it.

Check for the sensor constructor you need. If it is absent, fall back to DeviceMotionEvent, which Firefox and Safari implement. Use a static UI when neither path is available.

Shake detection with an Accelerometer and a DeviceMotionEvent fallback

Section titled “Shake detection with an Accelerometer and a DeviceMotionEvent fallback”

The accelerometer path is preferred because it delivers calibrated, quantized samples at a rate you choose. Where the constructor is missing the same threshold runs on devicemotion, which reports unquantized accelerationIncludingGravity.

const SHAKE_THRESHOLD = 25; // m/s^2, total magnitude
function onShake(callback) {
if ('Accelerometer' in window) {
let sensor;
try {
sensor = new Accelerometer({ frequency: 30 });
} catch (err) {
console.warn(`${err.name}: ${err.message}`); // blocked by Permissions Policy
return false;
}
sensor.addEventListener('error', (event) => {
console.warn(`${event.error.name}: ${event.error.message}`);
});
sensor.addEventListener('reading', () => {
if (Math.hypot(sensor.x, sensor.y, sensor.z) > SHAKE_THRESHOLD) callback();
});
sensor.start();
return true;
}
if ('DeviceMotionEvent' in window) {
window.addEventListener('devicemotion', (event) => {
const a = event.accelerationIncludingGravity;
if (a && Math.hypot(a.x, a.y, a.z) > SHAKE_THRESHOLD) callback();
});
return true;
}
return false; // no motion data: show a button instead
}
if (!onShake(() => document.body.classList.toggle('shaken'))) {
document.querySelector('#shake-button').hidden = false;
}

On iOS 13 and later devicemotion is itself permission-gated through DeviceMotionEvent.requestPermission(), which must be called from a user gesture; the fallback branch therefore belongs behind a tap in a real app.

Checking permission before constructing an orientation sensor

Section titled “Checking permission before constructing an orientation sensor”

AbsoluteOrientationSensor depends on three permissions at once. Querying them first lets the page explain what is blocked instead of waiting for a NotAllowedError on the error event.

async function startCompass(onHeading) {
if (!('AbsoluteOrientationSensor' in window)) return 'unsupported';
const names = ['accelerometer', 'gyroscope', 'magnetometer'];
const states = await Promise.all(
names.map((name) => navigator.permissions.query({ name }).then((s) => s.state)),
);
if (states.includes('denied')) return 'denied';
const sensor = new AbsoluteOrientationSensor({ frequency: 10, referenceFrame: 'screen' });
sensor.addEventListener('reading', () => {
const [qx, qy, qz, qw] = sensor.quaternion;
const yaw = Math.atan2(2 * (qw * qz + qx * qy), 1 - 2 * (qy * qy + qz * qz));
onHeading(((yaw * 180) / Math.PI + 360) % 360);
});
sensor.addEventListener('error', (event) => {
if (event.error.name === 'NotReadableError') onHeading(null); // no magnetometer on this device
});
sensor.start();
return 'started';
}

The caller uses the returned string to choose a compass, a “turn on motion access” message, or a plain north-up map when the API is absent.

Specifications

SpecificationStatus
Generic Sensor APIW3C draft
Generic Sensor API: the Sensor interfaceW3C
Accelerometer: the Accelerometer interfaceW3C
Gyroscope: the Gyroscope interfaceW3C
Orientation Sensor: the AbsoluteOrientationSensor interfaceW3C
  • Legend
  • Yes
  • Partial
  • Flag
  • No
  • Unknown
Browser / PlatformSupportVersionsConfidenceSourceNotes
Chrome (Desktop)#Yes67highsource—
Chrome (Android)#Yes67highsource1
Edge (Desktop)#Yes79highsource2
Firefox (Desktop)#No—highsource3
Firefox (Android)#No—highsource45
Safari (macOS)#No—highsource6
Safari (iOS)#No—highsource78
Samsung Internet#Yes9.0highsource9
WebView (Android)#Yes67highsource10
  1. Derived by browser-compat-data mirroring from Chrome.
  2. Derived by browser-compat-data mirroring from Chrome.
  3. No Firefox support is recorded in browser-compat-data.
  4. No Firefox for Android support is recorded in browser-compat-data.
  5. Derived by browser-compat-data mirroring from Firefox.
  6. No Safari support is recorded in browser-compat-data.
  7. No Safari on iOS support is recorded in browser-compat-data.
  8. Derived by browser-compat-data mirroring from Safari.
  9. Derived by browser-compat-data mirroring from Chrome Android.
  10. Derived by browser-compat-data mirroring from Chrome Android.

Source data: /compatibility/sensors.json · Global usage: 75 % (StatCounter 2026-09, CC BY-SA 4.0)

Source: spec · MDN · Last verified 2026-10-03 · Confidence: high (computed from sources)