@usefy/use-geolocation

A powerful React hook for accessing device geolocation with real-time tracking and distance calculation

Installation •
Quick Start •
API Reference •
Examples •
License

📚 View Storybook Demo

---

Overview

@usefy/use-geolocation is a feature-rich React hook for accessing device geolocation with real-time tracking, distance calculation, and comprehensive error handling. It provides a simple API for getting current position, watching position changes, calculating distances, and tracking permission states.

Part of the @usefy ecosystem — a collection of production-ready React hooks designed for modern applications.

$3

- Zero Dependencies — Pure React implementation with no external dependencies
- TypeScript First — Full type safety with comprehensive type definitions
- Real-Time Tracking — Watch position changes as device moves
- Distance Calculation — Built-in Haversine formula for accurate distance calculations
- Bearing Calculation — Calculate direction/bearing between coordinates
- Permission Tracking — Monitor geolocation permission state changes
- Error Handling — Comprehensive error handling with typed error codes
- SSR Compatible — Works seamlessly with Next.js, Remix, and other SSR frameworks
- Stable References — Memoized functions for optimal performance
- Well Tested — Comprehensive test coverage with Vitest

---

Installation

``bash


npm

`json
{
"peerDependencies": {
"react": "^18.0.0 || ^19.0.0"
}
}
`

---

Quick Start

`tsx
import { useGeolocation } from "@usefy/use-geolocation";

function MyLocation() {
const { position, loading, error } = useGeolocation();

if (loading) return

Loading location...

| Parameter | Type | Description |
| --------- | ----------------------- | ----------------------------- |
| options | UseGeolocationOptions | Optional configuration object |

#### Options

| Option | Type | Default | Description |
| -------------------- | ----------------------------------- | ------- | ----------------------------------------------------------- |
| enableHighAccuracy | boolean | false | Enable high accuracy mode (uses GPS, consumes more battery) |
| maximumAge | number | 0 | Maximum age of cached position in milliseconds |
| timeout | number | 30000 | Timeout in milliseconds for position request |
| watch | boolean | false | Start watching position immediately on mount |
| immediate | boolean | true | Get initial position immediately on mount |
| onSuccess | (position: GeoPosition) => void | — | Callback when position is successfully retrieved |
| onError | (error: GeolocationError) => void | — | Callback when an error occurs |
| onPositionChange | (position: GeoPosition) => void | — | Callback when position changes (during watch mode) |
| onPermissionChange | (state: PermissionState) => void | — | Callback when permission state changes |

#### Returns UseGeolocationReturn

| Property | Type | Description |
| -------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------- |
| position | GeoPosition \| null | Current position data (null if not yet retrieved) |
| loading | boolean | Loading state (true while fetching position) |
| error | GeolocationError \| null | Error object (null if no error) |
| permission | PermissionState | Current permission state (prompt, granted, denied, unavailable) |
| isSupported | boolean | Whether geolocation is supported in this environment |
| getCurrentPosition | () => void | Manually get current position (one-time request) |
| watchPosition | () => void | Start watching position for real-time updates |
| clearWatch | () => void | Stop watching position |
| distanceFrom | (lat: number, lon: number) => number \| null | Calculate distance from current position to target coordinates in meters |
| bearingTo | (lat: number, lon: number) => number \| null | Calculate bearing/direction from current position to target coordinates (0-360 degrees) |

#### Error Codes

| Code | Description |
| ---------------------- | ------------------------------------------------ |
| PERMISSION_DENIED | User denied geolocation permission |
| POSITION_UNAVAILABLE | Position information unavailable |
| TIMEOUT | Position request timed out |
| NOT_SUPPORTED | Geolocation is not supported in this environment |

---

Examples

$3

`tsx
import { useGeolocation } from "@usefy/use-geolocation";

function CurrentLocation() {
const { position, loading, error } = useGeolocation();

if (loading) return

`tsx
import { useGeolocation } from "@usefy/use-geolocation";

function ManualLocation() {
const {
position,
loading,
error,
getCurrentPosition,
watchPosition,
clearWatch,
} = useGeolocation({ immediate: false, watch: false });

return (


`tsx
import { useGeolocation } from "@usefy/use-geolocation";

function LiveTracking() {
const { position, watchPosition, clearWatch } = useGeolocation({
immediate: false,
watch: false,
onPositionChange: (pos) => {
console.log("Position updated:", pos);
},
});

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

const handleStart = () => {
watchPosition();
setIsTracking(true);
};

const handleStop = () => {
clearWatch();
setIsTracking(false);
};

return (


`tsx
import { useGeolocation } from "@usefy/use-geolocation";

function DistanceToDestination() {
const { position, distanceFrom } = useGeolocation();

// New York City coordinates
const nyLat = 40.7128;
const nyLon = -74.006;

const distance = distanceFrom(nyLat, nyLon);

return (


`tsx
import { useGeolocation } from "@usefy/use-geolocation";

function DirectionToDestination() {
const { position, bearingTo } = useGeolocation();

// London coordinates
const londonLat = 51.5074;
const londonLon = -0.1278;

const bearing = bearingTo(londonLat, londonLon);

const getDirection = (bearing: number | null) => {
if (bearing === null) return "—";
if (bearing < 22.5 || bearing >= 337.5) return "North";
if (bearing < 67.5) return "Northeast";
if (bearing < 112.5) return "East";
if (bearing < 157.5) return "Southeast";
if (bearing < 202.5) return "South";
if (bearing < 247.5) return "Southwest";
if (bearing < 292.5) return "West";
return "Northwest";
};

return (


`tsx
import { useGeolocation } from "@usefy/use-geolocation";

function HighAccuracyLocation() {
const { position, loading } = useGeolocation({
enableHighAccuracy: true,
timeout: 10000,
});

if (loading) return

`tsx
import { useGeolocation } from "@usefy/use-geolocation";

function PermissionStatus() {
const { permission, onPermissionChange } = useGeolocation({
onPermissionChange: (state) => {
console.log("Permission changed:", state);
},
});

return (


`tsx
import { useGeolocation } from "@usefy/use-geolocation";

function RobustLocation() {
const { position, error, getCurrentPosition } = useGeolocation({
immediate: false,
onError: (err) => {
console.error("Geolocation error:", err.code, err.message);

if (err.code === "PERMISSION_DENIED") {
alert("Please allow location access");
} else if (err.code === "TIMEOUT") {
alert("Location request timed out. Please try again.");
}
},
});

return (


`tsx
import { useGeolocation } from "@usefy/use-geolocation";

function AutoTracking() {
const { position, clearWatch } = useGeolocation({
watch: true, // Automatically start watching on mount
immediate: false,
});

return (


`tsx
import {
useGeolocation,
type UseGeolocationOptions,
type UseGeolocationReturn,
type GeoPosition,
type GeolocationError,
type PermissionState,
} from "@usefy/use-geolocation";

// Full type inference
const geolocation: UseGeolocationReturn = useGeolocation({
enableHighAccuracy: true,
timeout: 10000,
onSuccess: (position: GeoPosition) => {
console.log("Got position:", position);
},
onError: (error: GeolocationError) => {
console.error("Error:", error.code, error.message);
},
});

// Permission state is typed as union
const permission: PermissionState = geolocation.permission;
// "prompt" | "granted" | "denied" | "unavailable"
`

---

Performance

- Stable Function References — All control functions are memoized with useCallback
- Smart Re-renders — Only re-renders when position, loading, or error state changes
- Automatic Cleanup — Watch is automatically cleared on unmount
- Options Auto-Restart — Watch automatically restarts when options change

`tsx
const { getCurrentPosition, watchPosition, clearWatch } = useGeolocation();

// These references remain stable across renders
useEffect(() => {
// Safe to use as dependencies
}, [getCurrentPosition, watchPosition, clearWatch]);
``

---

Testing

This package maintains comprehensive test coverage to ensure reliability and stability.

$3

📊 View Detailed Coverage Report (GitHub Pages)

$3

---

Browser Compatibility

This hook uses the Geolocation API, which is supported in:

- ✅ Chrome 5+
- ✅ Firefox 3.5+
- ✅ Safari 5+
- ✅ Edge 12+
- ✅ Opera 10.6+
- ✅ Mobile browsers (iOS Safari, Chrome Mobile)

Note: HTTPS is required for geolocation in most modern browsers (except localhost).

---

License

MIT © mirunamu

This package is part of the usefy monorepo.

---

_{Built with care by the usefy team}