svelte-geolocation

Svelte bindings for the Geolocation API

Declaratively access the Geolocation API in Svelte components. This package provides a simple way to fetch the geolocation coordinates of the device.

Features

• Bind to coordinates in a 2-tuple ([longtitude: number, latitude: number]).
• Slotted states: loading/error/success.
• Programmatic access to the Geolocation API (e.g., geolocation.getCurrentPosition).
• Watch the current position.

Installation

# npm
npm i -D svelte-geolocation

# pnpm
pnpm i -D svelte-geolocation

# Bun
bun i -D svelte-geolocation

# Yarn
yarn add -D svelte-geolocation

Usage

Binding coordinates

Set getPosition to true to automatically 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>

Programmatic usage

By default, the component will not automatically fetch the geolocation coordinates. This method must be programmatically triggered.

<script>
  let ref;

  // Access the component instance and programmatically invoke the method.
  $: ref?.getGeolocationPosition({ enableHighAccuracy: true });
</script>

<Geolocation bind:this={ref} />

Slotted states

This example shows programmatic usage 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}
  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} />

API

Props

| Prop name | Value | | :----------- | :--------------------------------------------------------------------------------------------------------------------------------- | | coords | [longitude: number, latitude: number]; (default: [-1, -1]) | | position | GeolocationPosition | | options | PositionOptions | | getPosition | boolean (default: false) | | watch | boolean (default: false) | | loading | boolean (default: false) | | success | boolean (default: false) | | error | false or GeolocationPositionError (default:false) | | notSupported | boolean (default: false) |

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) => undefined | number;

  /** Programmatically get the geolocation position. */
  getGeolocationPosition: (options: PositionOptions) => Promise<void>;

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

Changelog

CHANGELOG.md

License

MIT