device-orientation

Track device orientation angles.


Package	`@vizejs/composable/device-orientation`
Own the source	`vize lib pull composable:device-orientation`
Runtime exports	`useDeviceOrientation`, `requestMotionPermission`
Gzip budget	1792 B

Usage

import { useDeviceOrientation, requestMotionPermission } from "@vizejs/composable/device-orientation";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useDeviceOrientation`	sensors	experimental	deterministic-fallback	stable	reactive-scope	web, desktop	`window`	`requestMotionPermission`, `tryOnScopeDispose`
`requestMotionPermission`	sensors	experimental	safe	not-applicable	none	web, desktop	—	—

API

`useDeviceOrientation`

Track device orientation angles. Server renders expose null angles and isSupported: false. The listener follows the reactive host and is removed with the owning reactive scope. On platforms with a permission prompt, permission starts as "prompt" and readings arrive only after requestPermission resolves "granted".

function useDeviceOrientation( options: UseDeviceOrientationOptions = {}, ): DeviceOrientationControls

`requestMotionPermission`

Request motion/orientation sensor permission from an event constructor. Normalizes the platform result to MotionPermissionState. Missing constructors resolve "denied"; constructors without a prompt resolve "granted"; unknown results resolve "prompt". Rejections (for example when not called from a user gesture) resolve "denied" instead of throwing.

async function requestMotionPermission( constructor: MotionPermissionConstructor | undefined, ): Promise<MotionPermissionState>

Types

`MotionPermissionConstructor`

Event constructor that may expose the iOS requestPermission static.

Member	Type	Description
`prototype`	`object`	Constructor prototype; present on every platform event constructor.
`requestPermission`?	`() => Promise<string>`	Ask the user for sensor access (Safari on iOS/iPadOS 13+).

`DeviceOrientationHost`

Window-like capability observed by useDeviceOrientation.

Member	Type	Description
`DeviceOrientationEvent`?	`MotionPermissionConstructor`	Constructor used to detect support and request permission.

`UseDeviceOrientationOptions`

Options for useDeviceOrientation.

Member	Type	Description
`absolute`?	`boolean`	Listen to `deviceorientationabsolute` (earth-frame) instead of `deviceorientation`.
`host`?	`MaybeRefOrGetter<DeviceOrientationHost \| null \| undefined>`	Reactive window capability for alternate runtimes and tests.

`DeviceOrientationControls`

Reactive orientation state returned by useDeviceOrientation.

Member	Type	Description
`isSupported`	`Readonly<Ref<boolean>>`	Whether the host exposes `DeviceOrientationEvent`. `false` during server rendering.
`isAbsolute`	`Readonly<Ref<boolean>>`	Whether the latest reading is relative to the earth frame.
`alpha`	`Readonly<Ref<number \| null>>`	Rotation around the Z axis in degrees `[0, 360)`.
`beta`	`Readonly<Ref<number \| null>>`	Rotation around the X axis in degrees `[-180, 180)`.
`gamma`	`Readonly<Ref<number \| null>>`	Rotation around the Y axis in degrees `[-90, 90)`.
`permission`	`Readonly<Ref<MotionPermissionState>>`	Latest permission outcome; `"granted"` where no prompt exists.
`requestPermission`	`() => Promise<MotionPermissionState>`	Request sensor permission where the platform requires it. Must be called from a user gesture on iOS.