useDeviceOrientation

v0.0.14testeddemo

Reactive DeviceOrientationEvent. Provides physical orientation of the device relative to Earth's coordinate frame. SSR-safe, uses a single passive listener, and supports the iOS 13+ permission flow.

Source Tests

Examples

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

// iOS 13+: request permission from a user gesture
const { ensurePermissions, alpha, beta, gamma } = useDeviceOrientation();
button.addEventListener('click', ensurePermissions);

Demo

Loading demo…

Signature

export function useDeviceOrientation(options: UseDeviceOrientationOptions ={ ... }

Parameters

Parameter	Type	Default	Description
`options`?	`UseDeviceOrientationOptions`	`{}`	Options

Returns

UseDeviceOrientationReturnisSupported, isAbsolute, the alpha/beta/gamma angles, and the permission state

Property	Type	Default	Description
`isSupported`	`ComputedRef<boolean>`	—	Whether the `DeviceOrientationEvent` is supported in the current environment.
`requirePermissions`	`ComputedRef<boolean>`	—	Whether an explicit permission grant is required (iOS 13+).
`permissionGranted`	`ShallowRef<boolean>`	—	Whether orientation permission has been granted.
`isAbsolute`	`ShallowRef<boolean>`	—	Whether the device is providing orientation data absolutely (relative to Earth's coordinate frame) rather than relative to an arbitrary frame.
`alpha`	`ShallowRef<number \| null>`	—	Motion of the device around the z axis, in degrees (`0`–`360`), or `null` when unavailable.
`beta`	`ShallowRef<number \| null>`	—	Motion of the device around the x axis, in degrees (`-180`–`180`), or `null` when unavailable.
`gamma`	`ShallowRef<number \| null>`	—	Motion of the device around the y axis, in degrees (`-90`–`90`), or `null` when unavailable.
`ensurePermissions`	`() => Promise<void>`	—	Request orientation permission (iOS 13+). Must be triggered by a user gesture. Resolves once the request settles; on grant the listener is attached.