# svelte-geolocation

> Svelte bindings for the Geolocation API

Latest version **1.0.0** (published 2024-07-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install svelte-geolocation
pnpm add svelte-geolocation
yarn add svelte-geolocation
bun add svelte-geolocation
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; has provenance.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2024-07-13 |
| First published | 2020-12-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 15.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 30 |
| Author | Eric Liu |
| Maintainers | metonym |
| Keywords | svelte, svelte component, geolocation, web api, coordinates, latitude, longitude |

## Links

- npm: https://www.npmjs.com/package/svelte-geolocation
- Repository: https://github.com/metonym/svelte-geolocation
- Issues: https://github.com/metonym/svelte-geolocation/issues
- npm.io page: https://npm.io/package/svelte-geolocation

## Recent versions

- 1.0.0 (latest) — 2024-07-13
- 0.3.0 — 2021-10-28
- 0.2.3 — 2021-09-29
- 0.2.2 — 2021-07-22
- 0.2.1 — 2021-02-06
- 0.2.0 — 2021-02-02
- 0.1.0 — 2020-12-30

## README

# svelte-geolocation

[![NPM][npm]][npm-url]

> Svelte bindings for the [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API)

<!-- REPO_URL -->

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.

---

<!-- TOC -->

## Installation

```bash
# 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]`.

```svelte
<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](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPosition).

```svelte
<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.

```svelte no-eval
<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

```svelte
<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.

```svelte
<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

```svelte
<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](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions) using the `options` prop.

```svelte no-eval
<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](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPosition)                                        |
| options      | [PositionOptions](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions)                                                |
| getPosition  | `boolean` (default: `false`)                                                                                                       |
| watch        | `boolean` (default: `false`)                                                                                                       |
| loading      | `boolean` (default: `false`)                                                                                                       |
| success      | `boolean` (default: `false`)                                                                                                       |
| error        | `false` or [GeolocationPositionError](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPositionError) (default:`false`) |
| notSupported | `boolean` (default: `false`)                                                                                                       |

### Accessors

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

```svelte no-display
<script>
  import Geolocation from "svelte-geolocation";

  let geolocation;

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

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

#### API

```ts
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](CHANGELOG.md)

## License

[MIT](LICENSE)

[npm]: https://img.shields.io/npm/v/svelte-geolocation.svg?style=for-the-badge&color=%23ff3e00
[npm-url]: https://npmjs.com/package/svelte-geolocation

---
_Source: https://npm.io/package/svelte-geolocation · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._