Device Orientation

This controller uses the Device Orientation API to listen to changes in the physical orientation of a device (phone, tablet, etc.). It emits an updated event at a throttled rate containing the current rotation angles.

⚠️ Notes

• This API is available only on mobile and tablet devices equipped with motion sensors.

• On iOS (Safari), users must grant permission via a dialog triggered by a user gesture:

  if (typeof DeviceOrientationEvent.requestPermission === 'function') {
    await DeviceOrientationEvent.requestPermission();
  }

• On desktop browsers, events may never fire or return null values.

• For performance reasons, events are throttled by default (see throttleValue).

Usage

<div {{ stimulus_controller('@pwa/device-orientation', {throttle: 25}) }}>
  <p id="orientation-status">Waiting for orientation data…</p>
</div>

<script type="module">
  const el = document.querySelector('[data-controller="pwa__device-orientation"]');

  el.addEventListener('device-orientation:updated', (e) => {
    const { alpha, beta, gamma } = e.detail;
    document.getElementById('orientation-status').textContent =
      `α: ${alpha?.toFixed(1)}°, β: ${beta?.toFixed(1)}°, γ: ${gamma?.toFixed(1)}°`;
  });
</script>

Parameters

throttleValue: Intended to control how often updated events are dispatched to avoid spamming the UI.

Actions

None

Targets

None

Events

updated: Emitted each time the device orientation changes (subject to the throttle delay).

Contains an object with the information (values are in degrees):

• absolute: boolean,

• alpha: number | null,

• beta: number | null,

• gamma: number | null