{"id":13907394,"url":"https://github.com/trekhleb/use-position","last_synced_at":"2025-04-04T10:06:23.559Z","repository":{"id":46700266,"uuid":"194388894","full_name":"trekhleb/use-position","owner":"trekhleb","description":"🌍 React hook usePosition() for fetching and following a browser geolocation","archived":false,"fork":false,"pushed_at":"2023-03-18T06:36:08.000Z","size":4713,"stargazers_count":305,"open_issues_count":9,"forks_count":51,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-28T09:06:32.278Z","etag":null,"topics":["browser","geolocation","hooks","location","position","react","react-hook","react-hooks"],"latest_commit_sha":null,"homepage":"https://trekhleb.dev/use-position/","language":"JavaScript","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/trekhleb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"github":"trekhleb","patreon":"trekhleb"}},"created_at":"2019-06-29T09:38:15.000Z","updated_at":"2025-02-20T08:46:55.000Z","dependencies_parsed_at":"2023-12-11T21:48:03.080Z","dependency_job_id":null,"html_url":"https://github.com/trekhleb/use-position","commit_stats":{"total_commits":66,"total_committers":4,"mean_commits":16.5,"dds":0.06060606060606055,"last_synced_commit":"8aff56cc8461ac12abc11f6d7a0dbc8b3843b8d4"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trekhleb%2Fuse-position","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trekhleb%2Fuse-position/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trekhleb%2Fuse-position/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/trekhleb%2Fuse-position/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/trekhleb","download_url":"https://codeload.github.com/trekhleb/use-position/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247157108,"owners_count":20893215,"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":["browser","geolocation","hooks","location","position","react","react-hook","react-hooks"],"created_at":"2024-08-06T23:01:55.162Z","updated_at":"2025-04-04T10:06:23.533Z","avatar_url":"https://github.com/trekhleb.png","language":"JavaScript","readme":"# React hook for following a browser geolocation\n\n[![npm version](https://badge.fury.io/js/use-position.svg)](https://badge.fury.io/js/use-position)\n[![codecov](https://codecov.io/gh/trekhleb/use-position/branch/master/graph/badge.svg)](https://codecov.io/gh/trekhleb/use-position)\n\nReact hook `usePosition()` allows you to fetch a client's browser geolocation and/or subscribe to all further geolocation changes.\n\n▶︎ [Storybook demo](https://trekhleb.github.io/use-position/) of `usePosition()` hook.\n\n![](https://repository-images.githubusercontent.com/194388894/00bf0e80-9a90-11e9-917f-aeaa68667edf)\n\n## Installation\n\nUsing `yarn`:\n\n```bash\nyarn add use-position\n```\n\nUsing `npm`:\n\n```bash\nnpm i use-position --save\n```\n\n## Usage\n\nImport the hook:\n\n```javascript\nimport { usePosition } from 'use-position';\n```\n\n### Fetching client location\n\n```javascript\nconst {\n  latitude,\n  longitude,\n  speed,\n  timestamp,\n  accuracy,\n  heading,\n  error,\n} = usePosition();\n```\n\n### Following client location\n\nIn this case if browser detects geolocation change the `latitude`, `longitude` and `timestamp` values will be updated.\n\n```javascript\nconst watch = true;\nconst {\n  latitude,\n  longitude,\n  speed,\n  timestamp,\n  accuracy,\n  heading,\n  error,\n} = usePosition(watch);\n```\n\n### Following client location with the highest accuracy\n\nThe second parameter of `usePosition()` hook is [position options](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions).\n\n```javascript\nconst watch = true;\nconst {\n  latitude,\n  longitude,\n  speed,\n  timestamp,\n  accuracy,\n  heading,\n  error,\n} = usePosition(watch, { enableHighAccuracy: true });\n```\n\n### Full example\n\n```javascript\nimport React from 'react';\nimport { usePosition } from 'use-position';\n\nexport const Demo = () =\u003e {\n  const watch = true;\n  const {\n    latitude,\n    longitude,\n    speed,\n    timestamp,\n    accuracy,\n    heading,\n    error,\n  } = usePosition(watch);\n\n  return (\n    \u003ccode\u003e\n      latitude: {latitude}\u003cbr/\u003e\n      longitude: {longitude}\u003cbr/\u003e\n      speed: {speed}\u003cbr/\u003e\n      timestamp: {timestamp}\u003cbr/\u003e\n      accuracy: {accuracy \u0026\u0026 `${accuracy} meters`}\u003cbr/\u003e\n      heading: {heading \u0026\u0026 `${heading} degrees`}\u003cbr/\u003e\n      error: {error}\n    \u003c/code\u003e\n  );\n};\n```\n\n## Specification\n\n### `usePosition()` input\n\n- `watch: boolean` - set it to `true` to follow the location.\n- `settings: object` - [position options](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions)\n  - `settings.enableHighAccuracy` - indicates the application would like to receive the most accurate results (default `false`),\n  - `settings.timeout` - maximum length of time (in milliseconds) the device is allowed to take in order to return a position (default `Infinity`),\n  - `settings.maximumAge` - the maximum age in milliseconds of a possible cached position that is acceptable to return (default `0`).\n\n### `usePosition()` output\n\n- `latitude: number` - latitude (i.e. `52.3172414`),\n- `longitude: number` - longitude (i.e. `4.8717809`),\n- `speed: number | null` - velocity of the device in meters per second (i.e. `2.5`),\n- `timestamp: number` - timestamp when location was detected (i.e. `1561815013194`),\n- `accuracy: number` - location accuracy in meters (i.e. `24`),\n- `heading: number | null` - direction in which the device is traveling, in degrees (`0` degrees - north, `90` degrees - east, `270` degrees - west, and so on),\n- `error: string` - error message or `null` (i.e. `User denied Geolocation`)\n","funding_links":["https://github.com/sponsors/trekhleb","https://patreon.com/trekhleb"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrekhleb%2Fuse-position","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftrekhleb%2Fuse-position","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftrekhleb%2Fuse-position/lists"}