Skip to content
On this page

useGeolocation

Category
Export Size
1.1 kB
Last Changed
2 months ago

Reactive Geolocation API. It allows the user to provide their location to web applications if they so desire. For privacy reasons, the user is asked for permission to report location information.

Demo

{
  "coords": {
    "accuracy": 0,
    "latitude": null,
    "longitude": null,
    "altitude": null,
    "altitudeAccuracy": null,
    "heading": null,
    "speed": null
  },
  "locatedAt": null,
  "error": null
}

Usage

js
import { useGeolocation } from '@vueuse/core'

const { coords, locatedAt, error, resume, pause } = useGeolocation()
import { useGeolocation } from '@vueuse/core'

const { coords, locatedAt, error, resume, pause } = useGeolocation()
StateTypeDescription
coordsCoordinatesinformation about the position retrieved like the latitude and longitude
locatedAtDateThe time of the last geolocation call
errorstringAn error message in case geolocation API fails.
resumefunctionControl function to resume updating geolocation
pausefunctionControl function to pause updating geolocation

Config

useGeolocation function takes PositionOptions object as an optional parameter.

Component Usage

This function also provides a renderless component version via the @vueuse/components package. Learn more about the usage.

html
<UseGeolocation v-slot="{ coords: { latitude, longitude } }">
  Latitude: {{ latitude }}
  Longitude: {{ longitude }}
</UseGeolocation>
<UseGeolocation v-slot="{ coords: { latitude, longitude } }">
  Latitude: {{ latitude }}
  Longitude: {{ longitude }}
</UseGeolocation>

Type Declarations

typescript
export interface UseGeolocationOptions
  extends Partial<PositionOptions>,
    ConfigurableNavigator {
  immediate?: boolean
}
/**
 * Reactive Geolocation API.
 *
 * @see https://vueuse.org/useGeolocation
 * @param options
 */
export declare function useGeolocation(options?: UseGeolocationOptions): {
  isSupported: Ref<boolean>
  coords: Ref<GeolocationCoordinates>
  locatedAt: Ref<number | null>
  error: Ref<{
    readonly code: number
    readonly message: string
    readonly PERMISSION_DENIED: number
    readonly POSITION_UNAVAILABLE: number
    readonly TIMEOUT: number
  } | null>
  resume: () => void
  pause: () => void
}
export type UseGeolocationReturn = ReturnType<typeof useGeolocation>
export interface UseGeolocationOptions
  extends Partial<PositionOptions>,
    ConfigurableNavigator {
  immediate?: boolean
}
/**
 * Reactive Geolocation API.
 *
 * @see https://vueuse.org/useGeolocation
 * @param options
 */
export declare function useGeolocation(options?: UseGeolocationOptions): {
  isSupported: Ref<boolean>
  coords: Ref<GeolocationCoordinates>
  locatedAt: Ref<number | null>
  error: Ref<{
    readonly code: number
    readonly message: string
    readonly PERMISSION_DENIED: number
    readonly POSITION_UNAVAILABLE: number
    readonly TIMEOUT: number
  } | null>
  resume: () => void
  pause: () => void
}
export type UseGeolocationReturn = ReturnType<typeof useGeolocation>

Source

SourceDemoDocs

Contributors

Anthony Fu
Antério Vieira
Jelf
vaakian X
Enric Bisbe Gil
Egor Startsev
Michael J. Roberts
Shinigami
wheat
Alex Kozack
Sanxiaozhizi

Changelog

v9.11.0 on 1/17/2023
d5321 - fix(components): mark defineComponent as pure (#2623)
v9.7.0 on 12/16/2022
161fd - fix: Implement immediate option (#2472)
v9.5.0 on 11/9/2022
2c4fd - feat: pause and resume controls (#2376)
v8.9.3 on 7/14/2022
48f79 - fix!: rename type GeolocationOptions to UseGeolocationOptions (#1868)
v8.9.2 on 7/12/2022
81d92 - fix(all)!: isSupported becomes Ref instead of boolean for SSR compatibility (#1800)

Released under the MIT License.