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

ย 

History

67 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

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)

Releases

No releases published

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •