{"id":13469643,"url":"https://github.com/no23reason/react-geolocated","last_synced_at":"2025-05-14T19:07:30.188Z","repository":{"id":38418590,"uuid":"62507065","full_name":"no23reason/react-geolocated","owner":"no23reason","description":"React hook for using Geolocation API","archived":false,"fork":false,"pushed_at":"2025-05-05T08:55:12.000Z","size":18785,"stargazers_count":314,"open_issues_count":1,"forks_count":75,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-05T09:56:52.333Z","etag":null,"topics":["geolocation","geolocation-api","gps","hooks","react","react-hook","react-hooks","typescript"],"latest_commit_sha":null,"homepage":"https://no23reason.github.io/react-geolocated/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/no23reason.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-07-03T17:13:59.000Z","updated_at":"2025-05-05T08:55:09.000Z","dependencies_parsed_at":"2023-02-10T03:15:17.561Z","dependency_job_id":"fa76d7ad-5160-4e1b-907c-b188fb0ced5b","html_url":"https://github.com/no23reason/react-geolocated","commit_stats":{"total_commits":1449,"total_committers":13,"mean_commits":"111.46153846153847","dds":0.5127674258109041,"last_synced_commit":"3ecb5a1d38c6e5c4b81d1af8467c8ff0b5e168e1"},"previous_names":[],"tags_count":38,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/no23reason%2Freact-geolocated","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/no23reason%2Freact-geolocated/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/no23reason%2Freact-geolocated/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/no23reason%2Freact-geolocated/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/no23reason","download_url":"https://codeload.github.com/no23reason/react-geolocated/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209859,"owners_count":22032897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["geolocation","geolocation-api","gps","hooks","react","react-hook","react-hooks","typescript"],"created_at":"2024-07-31T15:01:48.292Z","updated_at":"2025-05-14T19:07:29.527Z","avatar_url":"https://github.com/no23reason.png","language":"TypeScript","readme":"![Node.js CI](https://github.com/no23reason/react-geolocated/workflows/Node.js%20CI/badge.svg) [![npm version](https://img.shields.io/npm/v/react-geolocated.svg)](https://www.npmjs.com/package/react-geolocated) [![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)\n\n# react-geolocated - React hook for using [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation)\n\n## Demo\n\nBasic demo can be found at the [demo page](https://no23reason.github.io/react-geolocated/).\n\n## HOC version\n\nThis package used to be a HOC, not a hook. If you want to use the HOC version, please stick with versions \u003c 4.\n\n## Basic Usage\n\nInstall using `npm`:\n\n```bash\nnpm install react-geolocated --save\n```\n\nThen use in your application like this:\n\n```jsx\nimport React from \"react\";\nimport { useGeolocated } from \"react-geolocated\";\n\nconst Demo = () =\u003e {\n    const { coords, isGeolocationAvailable, isGeolocationEnabled } =\n        useGeolocated({\n            positionOptions: {\n                enableHighAccuracy: false,\n            },\n            userDecisionTimeout: 5000,\n        });\n\n    return !isGeolocationAvailable ? (\n        \u003cdiv\u003eYour browser does not support Geolocation\u003c/div\u003e\n    ) : !isGeolocationEnabled ? (\n        \u003cdiv\u003eGeolocation is not enabled\u003c/div\u003e\n    ) : coords ? (\n        \u003ctable\u003e\n            \u003ctbody\u003e\n                \u003ctr\u003e\n                    \u003ctd\u003elatitude\u003c/td\u003e\n                    \u003ctd\u003e{coords.latitude}\u003c/td\u003e\n                \u003c/tr\u003e\n                \u003ctr\u003e\n                    \u003ctd\u003elongitude\u003c/td\u003e\n                    \u003ctd\u003e{coords.longitude}\u003c/td\u003e\n                \u003c/tr\u003e\n                \u003ctr\u003e\n                    \u003ctd\u003ealtitude\u003c/td\u003e\n                    \u003ctd\u003e{coords.altitude}\u003c/td\u003e\n                \u003c/tr\u003e\n                \u003ctr\u003e\n                    \u003ctd\u003eheading\u003c/td\u003e\n                    \u003ctd\u003e{coords.heading}\u003c/td\u003e\n                \u003c/tr\u003e\n                \u003ctr\u003e\n                    \u003ctd\u003espeed\u003c/td\u003e\n                    \u003ctd\u003e{coords.speed}\u003c/td\u003e\n                \u003c/tr\u003e\n            \u003c/tbody\u003e\n        \u003c/table\u003e\n    ) : (\n        \u003cdiv\u003eGetting the location data\u0026hellip; \u003c/div\u003e\n    );\n};\n\nexport default Demo;\n```\n\n## Hook return value\n\nThe values returned from the hook are:\n\n```js\n{\n    coords: {\n        latitude,\n        longitude,\n        altitude,\n        accuracy,\n        altitudeAccuracy,\n        heading,\n        speed,\n    },\n    timestamp, // timestamp of when the last position was retrieved\n    isGeolocationAvailable, // boolean flag indicating that the browser supports the Geolocation API\n    isGeolocationEnabled, // boolean flag indicating that the user has allowed the use of the Geolocation API\n    positionError, // object with the error returned from the Geolocation API call\n    getPosition, // a callback you can use to trigger the location query manually\n}\n```\n\nThe `coords` value is equivalent to the [Coordinates](https://developer.mozilla.org/en-US/docs/Web/API/Coordinates) object and the `positionError` is equivalent to the [PositionError](https://developer.mozilla.org/en-US/docs/Web/API/PositionError).\n\n## Configuration\n\nThe `useGeolocated` hook takes optional configuration parameter:\n\n```js\n{\n    positionOptions: {\n        enableHighAccuracy: true,\n        maximumAge: 0,\n        timeout: Infinity,\n    },\n    watchPosition: false,\n    userDecisionTimeout: null,\n    suppressLocationOnMount: false,\n    geolocationProvider: navigator.geolocation,\n    isOptimisticGeolocationEnabled: true,\n    watchLocationPermissionChange: false,\n    onError,\n    onSuccess,\n}\n```\n\nThe `positionOptions` object corresponds to the [PositionOptions](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions) of the Geolocation API.\n\nBy default the hook only sets position once. To watch the user's position and provide live updates to position, set `watchPosition = true`. The geolocation event handler is unregistered when the hook unmounts.\n\nIf set, the `userDecisionTimeout` determines how much time (in milliseconds) we give the user to make the decision whether to allow to share their location or not. In Firefox, if the user declines to use their location, the Geolocation API call does not end with an error. Therefore we want to fallback to the error state if the user declines and the API does not tell us.\n\nThe location is obtained when the hook mounts by default. If you want to prevent this and get the location later, set the `suppressLocationOnMount` to `true` and use the `getPosition` function returned by the hook to trigger the geolocation query manually.\n\nThe `geolocationProvider` allows to specify alternative source of the geolocation API. This was added mainly for testing purposes, however feel free to use it if need be.\n\nThe `isOptimisticGeolocationEnabled` allows you to set the default value of `isGeolocationEnabled`. By default it is `true`, which means `isGeolocationEnabled` will be `true` on first render. There may be cases where you don't want to assume that the user will give permission, ie you want the first value to for `isGeolocationEnabled` to be `false`. In that case, you can set `isOptimisticGeolocationEnabled` to `false`.\n\nThe `watchLocationPermissionChange` allows you to watch for changes in the geolocation permissions on browsers that support the permissions API. When set to `true`, the hook will set a watch on the geolocation permission so that when this permission changes, the location will be obtained again unless the `suppressLocationOnMount` is also set to `true`.\n\nThe `onError` callback is called when the geolocation query fails or when the time for the user decision passes.\nThe `onSuccess` is called when the geolocation query succeeds.\n\n## Browser support\n\nThe package supports all the browsers with ES6 support (i.e. any modern browser). If you need to support IE11, stick to version \u003c 4 of this package.\n\n## Acknowledgements\n\nMany thanks belong to [@mcumpl](https://github.com/mcumpl) for the original idea for this as well as many suggestions and comments.\n\nThis project uses the [react-component-boilerplate](https://github.com/survivejs/react-component-boilerplate).\n\n## License\n\n_react-geolocated_ is available under MIT. See [LICENSE](https://github.com/no23reason/react-geolocated/tree/master/LICENSE) for more details.\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fno23reason%2Freact-geolocated","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fno23reason%2Freact-geolocated","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fno23reason%2Freact-geolocated/lists"}