useGeolocation

sensors

Installation

npx usehooks-cli@latest add use-geolocation

Description

A React hook for accessing the user's geolocation with support for both one-time position requests and continuous position watching, including comprehensive error handling and configuration options.

Parameters

Name	Type	Default	Description
options?	GeolocationOptions	{ enableHighAccuracy: false, timeout: Infinity, maximumAge: 0 }	Geolocation API options for accuracy, timeout, and cache settings

Return Type

GeolocationState & { getCurrentPosition: () => void, startWatching: () => void, stopWatching: () => void }

Property	Type	Description
loading	boolean	True when requesting location data
latitude	number \| null	Current latitude coordinate
longitude	number \| null	Current longitude coordinate
accuracy	number \| null	Accuracy of the position in meters
altitude	number \| null	Altitude above sea level in meters
altitudeAccuracy	number \| null	Accuracy of altitude measurement in meters
heading	number \| null	Direction of travel in degrees (0-360)
speed	number \| null	Current speed in meters per second
timestamp	number \| null	Timestamp when position was acquired
error	GeolocationPositionError \| null	Error object if geolocation failed
getCurrentPosition	() => void	Get current position once
startWatching	() => void	Start continuously watching position changes
stopWatching	() => void	Stop watching position changes

Examples

Current Location Display

Getting and displaying the user's current location

const { 
  latitude, 
  longitude, 
  accuracy, 
  loading, 
  error, 
  getCurrentPosition 
} = useGeolocation({
  enableHighAccuracy: true,
  timeout: 10000
});

return (
  <div>
    <button onClick={getCurrentPosition} disabled={loading}>
      {loading ? 'Getting Location...' : 'Get My Location'}
    </button>
    
    {error && (
      <div className="error">
        Error: {error.message}
      </div>
    )}
    
    {latitude && longitude && (
      <div className="location-info">
        <p>Latitude: {latitude.toFixed(6)}</p>
        <p>Longitude: {longitude.toFixed(6)}</p>
        <p>Accuracy: ±{accuracy?.toFixed(0)}m</p>
      </div>
    )}
  </div>
);

Live Location Tracking

Continuously tracking user's position for navigation

const { 
  latitude, 
  longitude, 
  speed, 
  heading, 
  loading, 
  error,
  startWatching, 
  stopWatching 
} = useGeolocation({
  enableHighAccuracy: true,
  timeout: 5000,
  maximumAge: 1000
});

const [isTracking, setIsTracking] = useState(false);

const toggleTracking = () => {
  if (isTracking) {
    stopWatching();
    setIsTracking(false);
  } else {
    startWatching();
    setIsTracking(true);
  }
};

return (
  <div>
    <button onClick={toggleTracking}>
      {isTracking ? 'Stop Tracking' : 'Start Tracking'}
    </button>
    
    {loading && <div>📍 Getting location...</div>}
    
    {latitude && longitude && (
      <div className="tracking-info">
        <h3>Current Position</h3>
        <p>📍 {latitude.toFixed(6)}, {longitude.toFixed(6)}</p>
        {speed && <p>🏃 Speed: {(speed * 3.6).toFixed(1)} km/h</p>}
        {heading && <p>🧭 Heading: {heading.toFixed(0)}°</p>}
      </div>
    )}
  </div>
);

Distance Calculator

Calculating distance between user and a target location

const { latitude, longitude, error, getCurrentPosition } = useGeolocation();
const [targetLocation] = useState({ lat: 40.7128, lng: -74.0060 }); // NYC
const [distance, setDistance] = useState(null);

// Haversine formula for distance calculation
const calculateDistance = (lat1, lon1, lat2, lon2) => {
  const R = 6371; // Earth's radius in km
  const dLat = (lat2 - lat1) * Math.PI / 180;
  const dLon = (lon2 - lon1) * Math.PI / 180;
  const a = Math.sin(dLat/2) * Math.sin(dLat/2) +
    Math.cos(lat1 * Math.PI / 180) * Math.cos(lat2 * Math.PI / 180) *
    Math.sin(dLon/2) * Math.sin(dLon/2);
  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a));
  return R * c;
};

useEffect(() => {
  if (latitude && longitude) {
    const dist = calculateDistance(
      latitude, longitude,
      targetLocation.lat, targetLocation.lng
    );
    setDistance(dist);
  }
}, [latitude, longitude, targetLocation]);

return (
  <div>
    <button onClick={getCurrentPosition}>
      Calculate Distance to NYC
    </button>
    
    {error && <div>Error: {error.message}</div>}
    
    {distance && (
      <div>
        <p>Distance to New York City:</p>
        <p><strong>{distance.toFixed(2)} km</strong></p>
      </div>
    )}
  </div>
);

Dependencies

react

Notes

•Requires user permission to access location data
•Works only in secure contexts (HTTPS) in most browsers
•Automatically cleans up watch positions on component unmount
•Provides comprehensive position data including altitude, speed, and heading
•Supports both one-time position requests and continuous watching
•Handles browser compatibility and provides meaningful error messages

Implementation

'use client';

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

export interface GeolocationState {
  loading: boolean;
  accuracy: number | null;
  altitude: number | null;
  altitudeAccuracy: number | null;
  heading: number | null;
  latitude: number | null;
  longitude: number | null;
  speed: number | null;
  timestamp: number | null;
  error: GeolocationPositionError | null;
}

export interface GeolocationOptions {
  enableHighAccuracy?: boolean;
  timeout?: number;
  maximumAge?: number;
}

const defaultOptions: GeolocationOptions = {
  enableHighAccuracy: false,
  timeout: Infinity,
  maximumAge: 0,
};

export function useGeolocation(options: GeolocationOptions = defaultOptions) {
  const [state, setState] = useState<GeolocationState>({
    loading: true,
    accuracy: null,
    altitude: null,
    altitudeAccuracy: null,
    heading: null,
    latitude: null,
    longitude: null,
    speed: null,
    timestamp: null,
    error: null,
  });

  const watchIdRef = useRef<number | null>(null);
  const optionsRef = useRef(options);

  // Update options ref when options change
  useEffect(() => {
    optionsRef.current = options;
  }, [options]);

  const onSuccess = useCallback((position: GeolocationPosition) => {
    setState({
      loading: false,
      accuracy: position.coords.accuracy,
      altitude: position.coords.altitude,
      altitudeAccuracy: position.coords.altitudeAccuracy,
      heading: position.coords.heading,
      latitude: position.coords.latitude,
      longitude: position.coords.longitude,
      speed: position.coords.speed,
      timestamp: position.timestamp,
      error: null,
    });
  }, []);

  const onError = useCallback((error: GeolocationPositionError) => {
    setState((prev) => ({
      ...prev,
      loading: false,
      error,
    }));
  }, []);

  const getCurrentPosition = useCallback(() => {
    if (!navigator.geolocation) {
      onError({
        code: 2,
        message: "Geolocation is not supported by this browser.",
      } as GeolocationPositionError);
      return;
    }

    setState((prev) => ({ ...prev, loading: true, error: null }));
    navigator.geolocation.getCurrentPosition(
      onSuccess,
      onError,
      optionsRef.current
    );
  }, [onSuccess, onError]);

  const startWatching = useCallback(() => {
    if (!navigator.geolocation) {
      onError({
        code: 2,
        message: "Geolocation is not supported by this browser.",
      } as GeolocationPositionError);
      return;
    }

    if (watchIdRef.current !== null) {
      navigator.geolocation.clearWatch(watchIdRef.current);
    }

    setState((prev) => ({ ...prev, loading: true, error: null }));
    watchIdRef.current = navigator.geolocation.watchPosition(
      onSuccess,
      onError,
      optionsRef.current
    );
  }, [onSuccess, onError]);

  const stopWatching = useCallback(() => {
    if (watchIdRef.current !== null) {
      navigator.geolocation.clearWatch(watchIdRef.current);
      watchIdRef.current = null;
    }
  }, []);

  // Cleanup on unmount
  useEffect(() => {
    return () => {
      if (watchIdRef.current !== null) {
        navigator.geolocation.clearWatch(watchIdRef.current);
      }
    };
  }, []);

  return {
    ...state,
    getCurrentPosition,
    startWatching,
    stopWatching,
  };
}

useDeviceOrientation

CLI Docs All Hooks

useHover