svelte-geolocation

Geolocation API wrapper for Svelte.

Features

• loading/error/success states
• access coordinates in a 2-tuple ([longtitude: number, latitude: number])

Installation

Yarn

yarn add -D svelte-geolocation

NPM

npm i -D svelte-geolocation

Usage

Binding coordinates

Set getPosition to true to invoke the geolocation.getCurrentPosition method and bind to the coords prop to retrieve the [longitude, latitude] of the device. The default coords value is [-1, -1].

<script>
  import Geolocation from "svelte-geolocation";

  let coords = [];
</script>

<Geolocation getPosition bind:coords />

<pre>{JSON.stringify(coords)}</pre>

Binding geolocation position

Bind to position to access all properties from GeolocationPosition.

<script>
  import Geolocation from "svelte-geolocation";

  let position;
</script>

<Geolocation getPosition bind:position />

<pre>{JSON.stringify(position, null, 2)}</pre>

Controlled trigger + default slot

This example shows the controlled invocation of geolocation.getCurrentPosition.

Using the default slot, you can destructure the following props:

• coords: geolocation coordinates in [lng, lat] format
• loading: true when the geolocation is being fetched
• success: true if the geolocation has been obtained
• error: true if an error occurs when fetching the geolocation
• notSupported: true if the device does not support the Geolocation API

<script>
  import Geolocation from "svelte-geolocation";

  let getPosition = false;
</script>

<button on:click="{() => (getPosition = true)}"> Get geolocation </button>

<Geolocation
  getPosition="{getPosition}"
  let:coords
  let:loading
  let:success
  let:error
  let:notSupported
>
  {#if notSupported}
    Your browser does not support the Geolocation API.
  {:else}
    {#if loading}
      Loading...
    {/if}
    {#if success}
      {JSON.stringify(coords)}
    {/if}
    {#if error}
      An error occurred. {error.code} {error.message}
    {/if}
  {/if}
</Geolocation>

Watching Position

Set watch to true to invoke the geolocation.watchPosition method and get informed if the user changes position.

<script>
  import Geolocation from "svelte-geolocation";

  let getPositionAgain = false;
  let detail = {};
</script>

<button on:click="{() => (getPositionAgain = !getPositionAgain)}">
  Get Position
</button>

<Geolocation
  getPosition="{getPositionAgain}"
  watch="{true}"
  on:position="{(e) => {
    detail = e.detail;
  }}"
/>

<pre>{JSON.stringify(detail, null, 2)}</pre>

Dispatched Events

You can listen to dispatched events as an alternative to binding.

• on:position: fired when geolocation.getCurrentPosition succeeds
• on:error: fired when geolocation.getCurrentPosition fails

<script>
  import Geolocation from "svelte-geolocation";

  let events = [];
</script>

<Geolocation
  getPosition
  on:position="{(e) => {
    events = [...events, e.detail];
    console.log(e.detail); // GeolocationPosition
  }}"
  on:error="{(e) => {
    events = [...events, e.detail];
    console.log(e.detail); // GeolocationError
  }}"
/>

<strong>Dispatched events:</strong>

{#each events as event}
  <pre>{JSON.stringify(event, null, 2)}</pre>
{/each}

Geolocation options

Specify Geolocation position options using the options prop.

<script>
  import Geolocation from "svelte-geolocation";

  let options = {
    /**
     * @type {boolean}
     * @default false
     */
    enableHighAccuracy: true,

    /**
     * @type {number}
     * @default Infinity
     */
    timeout: 5000, // milliseconds

    /**
     * @type {number}
     * @default 0
     */
    maximumAge: 60 * 60 * 1000, // milliseconds
  };
</script>

<Geolocation getPosition options="{options}" />

API

Props

Accessors

Use the bind:this directive to access the accessor methods available on the component instance.

<script>
  import Geolocation from "svelte-geolocation";

  let geolocation;

  $: geolocation?.getGeolocationPosition({ enableHighAccuracy: true });
</script>

<Geolocation bind:this="{geolocation}" />

API

interface Accessors {
  /** Watch the geolocation position */
  watchPosition: (options: PositionOptions) => Promise<Number | undefined>;

  /** Invoke the geolocation.getCurrentPosition method */
  getGeolocationPosition: (options: PositionOptions) => Promise<void>;

  /** Clear the Geolocation watcher */
  clearWatcher: (watcherId: number) => Promise<void>;
}

TypeScript

Svelte version 3.31 or greater is required to use this module with TypeScript.

TypeScript definitions are located in the types folder.

Changelog

CHANGELOG.md

License

MIT