provider-geolocation

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

<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

pnpm add @excom/provider-geolocation

npm install @excom/provider-geolocation

yarn add @excom/provider-geolocation

Import

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:

<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

Full documentation: https://nucleus.excom.dev/packages/provider-geolocation