# provider-geolocation

Declarative Geolocation API — request a position, read the result from
attributes/state.


```html
<div>
  <button type="button" command="--request" commandfor="geo-request">
    Request my location
  </button>
  <provider-geolocation id="geo-request" is-paused>
    <output>Click above — your browser will prompt for permission.</output>
  </provider-geolocation>
  <quark-sheet>
    provider-geolocation {
      $result: prop("provision");
      &[is-success] output { content: "#{$result.coords.latitude}, #{$result.coords.longitude}"; }
      &[is-error] output { content: $result.message; }
    }
  </quark-sheet>
</div>
```


## Features

- **Attribute-driven** Request + read a position through attributes
- **User-gesture requests** `is-paused` + the `--request` command
  so permission prompts follow a click
- **One-shot or watch** `watch-position` streams updates instead of a
  single read

## Installation


`@excom/provider-geolocation` v0.1.4

```bash
pnpm add @excom/provider-geolocation
```

```bash
npm install @excom/provider-geolocation
```

```bash
yarn add @excom/provider-geolocation
```

### Import

```ts
import "@excom/provider-geolocation";
```



## Usage

Requesting location on page load is poor UX (an unsolicited permission
prompt) — gate it behind a user gesture with `is-paused` and a trigger:

```html
<button type="button" command="--request" commandfor="geo">
  Share my location
</button>
<provider-geolocation id="geo" is-paused></provider-geolocation>
```

### API Reference


#### Attributes

| Name | Surface | Type | Default | Values | Description |
| --- | --- | --- | --- | --- | --- |
| `is-paused` | option | `boolean` |  |  | Skip making a request on connect. `provider-geolocation-request` still works while paused. |
| `high-accuracy` | option | `boolean` |  |  | Request the most accurate position available (more battery / time cost). |
| `geo-timeout` | option | `number` | `"Infinity"` |  | Give up and fire `provider-geolocation-error` after this many ms. |
| `maximum-age` | option | `number` |  |  | Accept a cached position up to this many ms old instead of requesting a fresh one. Ignored when `watch-position` is set (always `0`, i.e. no caching). |
| `watch-position` | option | `boolean` |  |  | Keep requesting — `provider-geolocation-success` fires on every position update instead of once. Uses `navigator.geolocation.watchPosition` under the hood. |
| `is-requesting` | state | `boolean` |  |  | A position request is currently pending. |
| `is-success` | state | `boolean` |  |  | The most recent request resolved successfully. With `watch-position`, stays set across updates. |
| `is-error` | state | `boolean` |  |  | The most recent request failed. Fires with the `error` event. |

#### Provision

| Name | Type | Description |
| --- | --- | --- |
| `provision` | `GeoSuccess` (`{ coords: { longitude: number; latitude: number; altitude?: number; accuracy?: number; altitudeAccuracy?: number; heading?: number; speed?: number; timestamp?: number; }; }`) | Latest result: the coords object on success, or the `GeolocationPositionError` (or thrown error) on failure. Not reflected as an attribute. |

#### Fires

| Name | Type | Description |
| --- | --- | --- |
| `provider-geolocation-success` | `ProviderGeolocationSuccessEvent` (`CustomEvent & { type: "provider-geolocation-success"; detail: { coords: { longitude: number; latitude: number; altitude?: number; accuracy?: number; altitudeAccuracy?: number; heading?: number; speed?: number; timestamp?: number; }; }; bubbles: true; cancelable: true; composed: true }`) | Dispatched on every successful position read (including each update while `watch-position` is set). |
| `provider-geolocation-error` | `ProviderGeolocationErrorEvent` (`CustomEvent & { type: "provider-geolocation-error"; detail: GeolocationPositionError; bubbles: true; cancelable: true; composed: true }`) | Dispatched when the request fails (permission denied, timeout, position unavailable, or a thrown error). |

#### Commands

| Command | Action |
| --- | --- |
| `--request` | (Re)requests the position on demand — the standard way to request from a button (`<button command="--request" commandfor="…">`) while `is-paused` is set, or to force a fresh read at any time. |

#### Default actions

| Event | Default behavior (unless preventDefault() is called) |
| --- | --- |
| `provider-geolocation-success` | Stores the result in `provision` and sets `is-success` (clearing `is-requesting` / `is-error`). |
| `provider-geolocation-error` | Stores the error in `provision` and sets `is-error` (clearing `is-requesting` / `is-success`). |

## Release notes

### 0.1.1 (2026-09-23)

- Ship only dist (and declared extras) in the npm tarball; drop build logs, tests and sources