![\"usefy](\"https://raw.githubusercontent.com/mirunamu00/usefy/master/assets/logo.png\"){kind=logo}
\n\n \n
\n A powerful React hook for accessing device geolocation with real-time tracking and distance calculation\n
\n\n\n \n ![\"npm](\"https://img.shields.io/npm/v/@usefy/use-geolocation.svg?style=flat-square&color=007acc\")
\n \n \n ![\"npm](\"https://img.shields.io/npm/dm/@usefy/use-geolocation.svg?style=flat-square&color=007acc\")
\n \n \n ![\"bundle](\"https://img.shields.io/bundlephobia/minzip/@usefy/use-geolocation?style=flat-square&color=007acc\")
![\"license\"](\"https://img.shields.io/npm/l/@usefy/use-geolocation.svg?style=flat-square&color=007acc\")
\n \n
\n Installation ā¢\n Quick Start ā¢\n API Reference ā¢\n Examples ā¢\n License\n
\n\n\n \n š View Storybook Demo\n \n
\n\n---\n\n## Overview\n\n`@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.\n\n**Part of the [@usefy](https://www.npmjs.com/org/usefy) ecosystem** ā a collection of production-ready React hooks designed for modern applications.\n\n### Why use-geolocation?\n\n- **Zero Dependencies** ā Pure React implementation with no external dependencies\n- **TypeScript First** ā Full type safety with comprehensive type definitions\n- **Real-Time Tracking** ā Watch position changes as device moves\n- **Distance Calculation** ā Built-in Haversine formula for accurate distance calculations\n- **Bearing Calculation** ā Calculate direction/bearing between coordinates\n- **Permission Tracking** ā Monitor geolocation permission state changes\n- **Error Handling** ā Comprehensive error handling with typed error codes\n- **SSR Compatible** ā Works seamlessly with Next.js, Remix, and other SSR frameworks\n- **Stable References** ā Memoized functions for optimal performance\n- **Well Tested** ā Comprehensive test coverage with Vitest\n\n---\n\n## Installation\n\n```bash\n# npm\nnpm install @usefy/use-geolocation\n\n# yarn\nyarn add @usefy/use-geolocation\n\n# pnpm\npnpm add @usefy/use-geolocation\n```\n\n### Peer Dependencies\n\nThis package requires React 18 or 19:\n\n```json\n{\n \"peerDependencies\": {\n \"react\": \"^18.0.0 || ^19.0.0\"\n }\n}\n```\n\n---\n\n## Quick Start\n\n```tsx\nimport { useGeolocation } from \"@usefy/use-geolocation\";\n\nfunction MyLocation() {\n const { position, loading, error } = useGeolocation();\n\n if (loading) returnLoading location...
;\n if (error) returnError: {error.message}
;\n if (!position) returnNo position yet
;\n\n return (\nLatitude: {position.coords.latitude}
\nLongitude: {position.coords.longitude}
\nAccuracy: {position.coords.accuracy}m
\nLatitude: {position.coords.latitude}
\nLongitude: {position.coords.longitude}
\nAccuracy: {position.coords.accuracy}m
\n\n {position.coords.latitude}, {position.coords.longitude}\n
\n )}\nš“ Live tracking active
}\n\n {position && (\n\n {position.coords.latitude.toFixed(6)},{\" \"}\n {position.coords.longitude.toFixed(6)}\n
\n )}\nDistance to NYC: {(distance / 1000).toFixed(2)} km
}\n\n Direction to London: {getDirection(bearing)} ({bearing.toFixed(0)}Ā°)\n
\n )}\nHigh accuracy: {position.coords.accuracy.toFixed(1)}m
}\nPermission: {permission}
\n {permission === \"denied\" && (\nPlease enable location permissions in your browser settings.
\n )}\nError: {error.code}
\n{error.message}
\n\n {position.coords.latitude}, {position.coords.longitude}\n
\n )}\nAuto-tracking is active
\n \n\n {position && (\n\n {position.coords.latitude.toFixed(6)},{\" \"}\n {position.coords.longitude.toFixed(6)}\n
\n )}\n\n Built with care by the usefy team\n
\n","readmeFilename":"README.md"}