Skip to content

🌍 React hook usePosition() for fetching and following a browser geolocation

License

Notifications You must be signed in to change notification settings

trekhleb/use-position

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Oct 26, 2021
8aff56c Β· Oct 26, 2021

History

67 Commits
Oct 26, 2021
Jun 29, 2019
Oct 26, 2021
Oct 26, 2021
Apr 19, 2020
Oct 26, 2021
Jun 29, 2019
Jun 29, 2019
Jun 29, 2019
Jun 29, 2019
Jun 29, 2019
Jun 29, 2019
Jun 29, 2019
Oct 26, 2021
Jun 29, 2019
Oct 26, 2021
Jun 29, 2019
Oct 23, 2020

Repository files navigation

React hook for following a browser geolocation

npm version codecov

React hook usePosition() allows you to fetch a client's browser geolocation and/or subscribe to all further geolocation changes.

β–ΆοΈŽ Storybook demo of usePosition() hook.

Installation

Using yarn:

yarn add use-position

Using npm:

npm i use-position --save

Usage

Import the hook:

import { usePosition } from 'use-position';

Fetching client location

const {
  latitude,
  longitude,
  speed,
  timestamp,
  accuracy,
  heading,
  error,
} = usePosition();

Following client location

In this case if browser detects geolocation change the latitude, longitude and timestamp values will be updated.

const watch = true;
const {
  latitude,
  longitude,
  speed,
  timestamp,
  accuracy,
  heading,
  error,
} = usePosition(watch);

Following client location with the highest accuracy

The second parameter of usePosition() hook is position options.

const watch = true;
const {
  latitude,
  longitude,
  speed,
  timestamp,
  accuracy,
  heading,
  error,
} = usePosition(watch, { enableHighAccuracy: true });

Full example

import React from 'react';
import { usePosition } from 'use-position';

export const Demo = () => {
  const watch = true;
  const {
    latitude,
    longitude,
    speed,
    timestamp,
    accuracy,
    heading,
    error,
  } = usePosition(watch);

  return (
    <code>
      latitude: {latitude}<br/>
      longitude: {longitude}<br/>
      speed: {speed}<br/>
      timestamp: {timestamp}<br/>
      accuracy: {accuracy && `${accuracy} meters`}<br/>
      heading: {heading && `${heading} degrees`}<br/>
      error: {error}
    </code>
  );
};

Specification

usePosition() input

  • watch: boolean - set it to true to follow the location.
  • settings: object - position options
    • settings.enableHighAccuracy - indicates the application would like to receive the most accurate results (default false),
    • settings.timeout - maximum length of time (in milliseconds) the device is allowed to take in order to return a position (default Infinity),
    • settings.maximumAge - the maximum age in milliseconds of a possible cached position that is acceptable to return (default 0).

usePosition() output

  • latitude: number - latitude (i.e. 52.3172414),
  • longitude: number - longitude (i.e. 4.8717809),
  • speed: number | null - velocity of the device in meters per second (i.e. 2.5),
  • timestamp: number - timestamp when location was detected (i.e. 1561815013194),
  • accuracy: number - location accuracy in meters (i.e. 24),
  • heading: number | null - direction in which the device is traveling, in degrees (0 degrees - north, 90 degrees - east, 270 degrees - west, and so on),
  • error: string - error message or null (i.e. User denied Geolocation)