# 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**:

  ```js
  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**

```twig

<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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pwa.spomky-labs.com/1.3.x/symfony-ux/device-orientation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.