useGeolocation

Browser & device

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

Install

$ npm install @usefy/use-geolocation

Quick start

useGeolocation.tsx

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

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

  if (loading) return <p>Loading location...</p>;
  if (error) return <p>Error: {error.message}</p>;
  if (!position) return <p>No position yet</p>;

  return (
    <div>
      <p>Latitude: {position.coords.latitude}</p>
      <p>Longitude: {position.coords.longitude}</p>
      <p>Accuracy: {position.coords.accuracy}m</p>
    </div>
  );
}

API reference

`useGeolocation(options?)`

A hook that manages geolocation state with real-time tracking and utility functions.

Parameters

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

Go deeper

This page is the quick reference. For every example, prop, and edge case, read the full README — or open Storybook to change props live.

Full README →Open in Storybook →