useDeviceOrientation

sensors

Installation

npx usehooks-cli@latest add use-device-orientation

Description

A hook for accessing device orientation data using the DeviceOrientationEvent API. Provides alpha, beta, and gamma rotation values along with compass heading on supported devices.

Parameters

Name	Type	Default	Description
options?	UseDeviceOrientationOptions	-	Configuration options for device orientation

Parameter Properties

options properties:

Name	Type	Description
absolute?	boolean	Whether to request absolute orientation values (auto-starts listening)

Return Type

UseDeviceOrientationReturn

Property	Type	Description
orientation	DeviceOrientation \| null	Current device orientation data including alpha, beta, gamma values
isSupported	boolean	Whether DeviceOrientationEvent is supported
error	string \| null	Error message if orientation access failed
requestPermission	() => Promise<boolean>	Request permission for device orientation (required on iOS 13+)
startListening	() => void	Start listening to orientation changes
stopListening	() => void	Stop listening to orientation changes
isListening	boolean	Whether currently listening to orientation changes

Examples

Basic Orientation Display

Display device orientation values with manual start/stop

import { useDeviceOrientation } from '@usehooks/use-device-orientation';

function OrientationDisplay() {
  const {
    orientation,
    isSupported,
    isListening,
    error,
    requestPermission,
    startListening,
    stopListening
  } = useDeviceOrientation();

  const handleStart = async () => {
    const hasPermission = await requestPermission();
    if (hasPermission) {
      startListening();
    }
  };

  if (!isSupported) {
    return <div>Device orientation not supported</div>;
  }

  return (
    <div>
      <div>
        <button onClick={handleStart} disabled={isListening}>
          Start Listening
        </button>
        <button onClick={stopListening} disabled={!isListening}>
          Stop Listening
        </button>
      </div>
      
      <p>Status: {isListening ? 'Listening' : 'Stopped'}</p>
      
      {error && <p>Error: {error}</p>}
      
      {orientation && (
        <div>
          <h3>Device Orientation:</h3>
          <p>Alpha (Z-axis): {orientation.alpha?.toFixed(2)}°</p>
          <p>Beta (X-axis): {orientation.beta?.toFixed(2)}°</p>
          <p>Gamma (Y-axis): {orientation.gamma?.toFixed(2)}°</p>
          <p>Absolute: {orientation.absolute ? 'Yes' : 'No'}</p>
          {orientation.webkitCompassHeading && (
            <p>Compass: {orientation.webkitCompassHeading.toFixed(2)}°</p>
          )}
        </div>
      )}
    </div>
  );
}

Compass Application

Create a simple compass using device orientation

import { useDeviceOrientation } from '@usehooks/use-device-orientation';
import { useEffect, useState } from 'react';

function Compass() {
  const { orientation, requestPermission, startListening } = useDeviceOrientation();
  const [compassHeading, setCompassHeading] = useState(0);

  useEffect(() => {
    const initCompass = async () => {
      const hasPermission = await requestPermission();
      if (hasPermission) {
        startListening();
      }
    };
    initCompass();
  }, []);

  useEffect(() => {
    if (orientation) {
      // Use webkitCompassHeading if available, otherwise use alpha
      const heading = orientation.webkitCompassHeading ?? orientation.alpha ?? 0;
      setCompassHeading(heading);
    }
  }, [orientation]);

  const compassStyle = {
    width: '200px',
    height: '200px',
    border: '2px solid #333',
    borderRadius: '50%',
    position: 'relative' as const,
    margin: '20px auto',
    backgroundColor: '#f0f0f0'
  };

  const needleStyle = {
    position: 'absolute' as const,
    top: '10px',
    left: '50%',
    width: '2px',
    height: '80px',
    backgroundColor: 'red',
    transformOrigin: 'bottom center',
    transform: `translateX(-50%) rotate(${compassHeading}deg)`,
    transition: 'transform 0.3s ease'
  };

  return (
    <div style={{ textAlign: 'center' }}>
      <h2>Compass</h2>
      <div style={compassStyle}>
        <div style={needleStyle}></div>
        <div style={{ position: 'absolute', top: '5px', left: '50%', transform: 'translateX(-50%)' }}>N</div>
        <div style={{ position: 'absolute', bottom: '5px', left: '50%', transform: 'translateX(-50%)' }}>S</div>
        <div style={{ position: 'absolute', left: '5px', top: '50%', transform: 'translateY(-50%)' }}>W</div>
        <div style={{ position: 'absolute', right: '5px', top: '50%', transform: 'translateY(-50%)' }}>E</div>
      </div>
      <p>Heading: {compassHeading.toFixed(1)}°</p>
    </div>
  );
}

Auto-start with Absolute Values

Automatically start listening with absolute orientation values

import { useDeviceOrientation } from '@usehooks/use-device-orientation';

function AbsoluteOrientation() {
  const {
    orientation,
    isSupported,
    isListening,
    error
  } = useDeviceOrientation({ absolute: true });

  if (!isSupported) {
    return <div>Device orientation not supported</div>;
  }

  return (
    <div>
      <h3>Absolute Device Orientation</h3>
      <p>Status: {isListening ? 'Active' : 'Inactive'}</p>
      
      {error && (
        <div style={{ color: 'red' }}>
          <p>Error: {error}</p>
          <p>Note: On iOS, you may need to enable motion access in Settings.</p>
        </div>
      )}
      
      {orientation && (
        <div style={{ fontFamily: 'monospace' }}>
          <div>Alpha (Z): {orientation.alpha?.toFixed(3)}°</div>
          <div>Beta (X): {orientation.beta?.toFixed(3)}°</div>
          <div>Gamma (Y): {orientation.gamma?.toFixed(3)}°</div>
          <div>Absolute: {orientation.absolute ? '✓' : '✗'}</div>
          
          {/* Visual representation */}
          <div style={{ marginTop: '20px' }}>
            <div>Tilt Forward/Back: {orientation.beta ? (orientation.beta > 0 ? 'Forward' : 'Back') : 'Level'}</div>
            <div>Tilt Left/Right: {orientation.gamma ? (orientation.gamma > 0 ? 'Right' : 'Left') : 'Level'}</div>
          </div>
        </div>
      )}
    </div>
  );
}

Dependencies

react

Notes

•Requires user permission on iOS 13+ devices
•HTTPS required in production environments
•Alpha represents rotation around Z-axis (0-360°)
•Beta represents rotation around X-axis (-180° to 180°)
•Gamma represents rotation around Y-axis (-90° to 90°)
•WebKit compass heading available on some iOS devices
•Automatically cleans up event listeners on unmount

Implementation

'use client';

import { useState, useEffect, useCallback } from "react";

interface DeviceOrientation {
  alpha: number | null;
  beta: number | null;
  gamma: number | null;
  absolute: boolean;
  webkitCompassHeading?: number;
  webkitCompassAccuracy?: number;
}

interface UseDeviceOrientationOptions {
  absolute?: boolean;
}

interface UseDeviceOrientationReturn {
  orientation: DeviceOrientation | null;
  isSupported: boolean;
  error: string | null;
  requestPermission: () => Promise<boolean>;
  startListening: () => void;
  stopListening: () => void;
  isListening: boolean;
}

// Extend DeviceOrientationEvent interface for webkit properties
declare global {
  interface DeviceOrientationEvent {
    webkitCompassHeading?: number;
    webkitCompassAccuracy?: number;
  }
}

// Check if DeviceOrientationEvent is supported
export const isDeviceOrientationSupported = 
  typeof globalThis !== 'undefined' && 'DeviceOrientationEvent' in globalThis;

// Backwards-compatible alias used internally (keeps existing name)
const isSupported = isDeviceOrientationSupported;

export const useDeviceOrientation = (
  options: UseDeviceOrientationOptions = {}
): UseDeviceOrientationReturn => {
  const [orientation, setOrientation] = useState<DeviceOrientation | null>(
    null
  );
  const [isListening, setIsListening] = useState(false);
  const [error, setError] = useState<string | null>(null);

  // Handle orientation change
  const handleOrientationChange = useCallback(
    (event: DeviceOrientationEvent) => {
      setOrientation({
        alpha: event.alpha,
        beta: event.beta,
        gamma: event.gamma,
        absolute: event.absolute,
        webkitCompassHeading: event.webkitCompassHeading,
        webkitCompassAccuracy: event.webkitCompassAccuracy,
      });
    },
    []
  );

  // Request permission for iOS 13+ devices
  const requestPermission = useCallback(async (): Promise<boolean> => {
    if (!isSupported) {
      setError("DeviceOrientationEvent is not supported");
      return false;
    }

    try {
      setError(null);

      // Check if permission is required (iOS 13+)
      if (
        typeof (DeviceOrientationEvent as any).requestPermission === "function"
      ) {
        const permission = await (
          DeviceOrientationEvent as any
        ).requestPermission();

        if (permission === "granted") {
          return true;
        } else {
          setError("Permission denied for device orientation");
          return false;
        }
      }

      // Permission not required or already granted
      return true;
    } catch (err) {
      const errorMessage =
        err instanceof Error ? err.message : "Failed to request permission";
      setError(errorMessage);
      return false;
    }
  }, []);

  // Start listening to orientation changes
  const startListening = useCallback(() => {
    if (!isSupported || isListening) return;

    try {
      setError(null);
      window.addEventListener(
        "deviceorientation",
        handleOrientationChange,
        true
      );
      setIsListening(true);
    } catch (err) {
      const errorMessage =
        err instanceof Error ? err.message : "Failed to start listening";
      setError(errorMessage);
    }
  }, [isListening, handleOrientationChange]);

  // Stop listening to orientation changes
  const stopListening = useCallback(() => {
    if (!isSupported || !isListening) return;

    try {
      window.removeEventListener(
        "deviceorientation",
        handleOrientationChange,
        true
      );
      setIsListening(false);
      setOrientation(null);
    } catch (err) {
      const errorMessage =
        err instanceof Error ? err.message : "Failed to stop listening";
      setError(errorMessage);
    }
  }, [isListening, handleOrientationChange]);

  // Auto-start listening if absolute option is provided
  useEffect(() => {
    if (options.absolute !== undefined && isSupported) {
      const initializeOrientation = async () => {
        const hasPermission = await requestPermission();
        if (hasPermission) {
          startListening();
        }
      };

      initializeOrientation();
    }

    return () => {
      if (isListening) {
        stopListening();
      }
    };
  }, [options.absolute, stopListening, isListening, requestPermission, startListening]);

  // Cleanup on unmount
  useEffect(() => {
    return () => {
      if (isListening) {
        stopListening();
      }
    };
  }, [isListening, stopListening]);

  return {
    orientation,
    isSupported,
    error,
    requestPermission,
    startListening,
    stopListening,
    isListening,
  };
};

useBarcodeDetector

CLI Docs All Hooks

useGeolocation