@sonardigital/location

A React package for getting device location using the browser's Geolocation API.

Features

• 🌍 Get device GPS coordinates (latitude, longitude)
• 📍 High accuracy mode support (GPS vs network-based)
• 🔄 One-time position fetch or continuous watching
• ⚡ Permission state tracking
• 🛡️ TypeScript support with full type definitions
• ⚛️ React Context provider pattern

Installation

npm install @sonardigital/location

Usage

With Provider (Recommended)

import { DeviceLocationProvider, useDeviceLocation, useDeviceLocationContext } from '@sonardigital/location';

function App() {
	const methods = useDeviceLocation({
		enableHighAccuracy: true,
		autoStart: true,
	});

	return (
		<DeviceLocationProvider methods={methods}>
			<LocationDisplay />
		</DeviceLocationProvider>
	);
}

// Use the context in child components
function LocationDisplay() {
	const { coordinates, isLoading, error, permissionState } = useDeviceLocationContext();

	if (isLoading) return <div>Getting location...</div>;
	if (error) return <div>Error: {error}</div>;
	if (!coordinates) return <div>No location data</div>;

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

With Hook Directly

import { useDeviceLocation } from '@sonardigital/location';

function LocationComponent() {
	const {
		coordinates,
		isLoading,
		error,
		isSupported,
		permissionState,
		getCurrentPosition,
		startWatching,
		stopWatching,
	} = useDeviceLocation({ enableHighAccuracy: true });

	return (
		<div>
			<button onClick={getCurrentPosition}>Get Location</button>
			<button onClick={startWatching}>Start Watching</button>
			<button onClick={stopWatching}>Stop Watching</button>

			{coordinates && (
				<p>
					{coordinates.latitude}, {coordinates.longitude}
				</p>
			)}
		</div>
	);
}

API

UseDeviceLocationProps

| Prop | Type | Default | Description | | -------------------- | --------- | ------- | -------------------------------------------------- | | enableHighAccuracy | boolean | true | Use GPS for higher accuracy (slower, more battery) | | maximumAge | number | 0 | Max age of cached position in ms | | timeout | number | 10000 | Timeout for position request in ms | | autoStart | boolean | false | Auto-request position on mount | | watchOnMount | boolean | false | Auto-start watching on mount |

DeviceLocationProviderProps

| Prop | Type | Description | | ---------- | -------------------------------------- | --------------------------------- | | methods | ReturnType<typeof useDeviceLocation> | Device location methods from hook | | children | React.ReactNode | Child components |

DeviceLocationContextType

| Property | Type | Description | | -------------------- | --------------------------- | --------------------------------- | | coordinates | DeviceCoordinates \| null | Current location coordinates | | isLoading | boolean | Whether location is being fetched | | error | string \| null | Error message if fetch failed | | errorCode | number \| null | GeolocationPositionError code | | isSupported | boolean | Whether geolocation is supported | | permissionState | LocationPermissionState | Current permission state | | lastUpdated | Date \| null | Timestamp of last update | | isWatching | boolean | Whether watching position | | getCurrentPosition | () => void | Request position once | | startWatching | () => void | Start continuous updates | | stopWatching | () => void | Stop watching | | clearError | () => void | Clear error state |

DeviceCoordinates

| Property | Type | Description | | ------------------ | ---------------- | --------------------------------- | | latitude | number | Latitude in decimal degrees | | longitude | number | Longitude in decimal degrees | | accuracy | number | Accuracy in meters | | altitude | number \| null | Altitude in meters (if available) | | altitudeAccuracy | number \| null | Altitude accuracy in meters | | heading | number \| null | Direction of travel in degrees | | speed | number \| null | Speed in m/s |

License

ISC