useDeviceOrientation

Tracks the physical orientation of the device using the deviceorientation window event, exposing reactive observables for all orientation angles.

Demo

Device Orientation

Not Supported

Tracks device orientation angles via the DeviceOrientation API. Best tested on a mobile device.

Alpha (Z)

—

Beta (X)

—

Gamma (Y)

—

Absolute

No

Usage

Hook

import { useDeviceOrientation } from "@usels/web";

function MyComponent() {
  const { isSupported$, isAbsolute$, alpha$, beta$, gamma$ } = useDeviceOrientation();

  return (
    <div>
      <p>Alpha: {alpha$.get()}</p>
      <p>Beta: {beta$.get()}</p>
      <p>Gamma: {gamma$.get()}</p>
    </div>
  );
}

Scope

import { createDeviceOrientation } from "@usels/web";

function MyComponent() {
  "use scope"
  const { isSupported$, isAbsolute$, alpha$, beta$, gamma$ } = createDeviceOrientation();

  return (
    <div>
      <p>Alpha: {alpha$.get()}</p>
      <p>Beta: {beta$.get()}</p>
      <p>Gamma: {gamma$.get()}</p>
    </div>
  );
}

Type

Parameters

Parameter	Type	Description
options	ConfigurableWindow (optional)	-

Returns

UseDeviceOrientationReturn

Name	Type	Description
hasRealData$	ReadonlyObservable<boolean>	Whether the device has real orientation sensor hardware. isSupported only checks API availability — desktop browsers expose the API but fire events with all-null values when no hardware exists. hasRealData$ becomes true on the first event where any of alpha/beta/gamma is non-null.
isAbsolute$	ReadonlyObservable<boolean>	Whether the orientation data is absolute (relative to the Earth’s coordinate frame)
alpha$	ReadonlyObservable<number | null>	Rotation around the z-axis in degrees (0–360)
beta$	ReadonlyObservable<number | null>	Rotation around the x-axis in degrees (-180–180)
gamma$	ReadonlyObservable<number | null>	Rotation around the y-axis in degrees (-90–90)
isSupported$	ReadonlyObservable<boolean>	-
permissionState$	ReadonlyObservable<PermissionState>	Current permission state. "unsupported" = API not available in this environment. Never undefined.
permissionGranted$	ReadonlyObservable<boolean>	true only when permissionState$ is "granted"
needsPermission$	ReadonlyObservable<boolean>	true when permissionState$ is "prompt" or "denied". "unsupported" → false.
ensurePermission	() => Promise<void>	Request permission. No-op if unsupported or already granted. If requestPermission throws, the error is propagated (state unchanged).

Source

View on GitHub