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

metonym / svelte-geolocation