Skip to content

README.md

Latest commit

 

History

History
135 lines (103 loc) · 4.45 KB

README.md

File metadata and controls

135 lines (103 loc) · 4.45 KB
Raw

@ailuracode/alpine-geo

Reactive geolocation via the $store.geo store. Wraps the browser Geolocation API with one-shot requests and continuous position watching.

Install

pnpm add @ailuracode/alpine-geo @ailuracode/alpine-core @ailuracode/alpine-permissions alpinejs

Quick start

import Alpine from "alpinejs";
import geo from "@ailuracode/alpine-geo";

Alpine.plugin(geo);
Alpine.start();

Avoiding name collisions

If your application already owns a $store.geo or another toolkit plugin registers on that name, rename the integration surface without touching the controller:

Alpine.plugin(geoPlugin({
  storeKey: "location",        // → $store.location
  // magicKey follows storeKey by default → $location
  magicKey: "geoState",        // explicit override → $geoState
}));

storeKey is the only argument most hosts need. magicKey moves independently only when both names must be freed. The exposed constants DEFAULT_GEO_STORE_KEY and DEFAULT_GEO_MAGIC_KEY keep the rename discoverable from TypeScript.

Store API

State

Property Type Description
latitude number | null Last known latitude in decimal degrees
longitude number | null Last known longitude in decimal degrees
accuracy number | null Accuracy radius in meters
altitude number | null Altitude in meters above ellipsoid
altitudeAccuracy number | null Altitude accuracy in meters
heading number | null Direction of travel in degrees
speed number | null Speed in meters per second
timestamp number | null Position timestamp (Unix ms)
error string | null Last error message
errorCode number | null Geolocation error code (1 denied, 2 unavailable, 3 timeout)
loading boolean true while a one-shot request() is pending
watching boolean true while watch() is active

Getters

Getter Type Description
hasPosition boolean true when latitude and longitude are available
isSupported boolean true when navigator.geolocation exists
isWatching boolean Alias for watching
isLoading boolean Alias for loading
hasError boolean true when error is set

Actions

Method Returns Description
request(options?) Promise<boolean> One-shot position via getCurrentPosition
watch(options?) boolean Start watchPosition; returns false if unsupported or already watching
unwatch() boolean Stop active watch; returns false if none is active
reset() boolean Clear position and error state without stopping a watch

All actions accept optional PositionOptions: enableHighAccuracy, timeout, maximumAge.

HTML examples

<button
  @click="$store.geo.request({ enableHighAccuracy: true })"
  :disabled="!$store.geo.isSupported || $store.geo.isLoading"
>
  Use my location
</button>

<p x-show="$store.geo.hasPosition">
  You are at
  <span x-text="$store.geo.latitude.toFixed(4)"></span>,
  <span x-text="$store.geo.longitude.toFixed(4)"></span>
  (±<span x-text="Math.round($store.geo.accuracy)"></span> m)
</p>

<p x-show="$store.geo.hasError" x-text="$store.geo.error"></p>
<button
  x-show="!$store.geo.isWatching"
  @click="$store.geo.watch()"
>
  Start tracking
</button>

<button
  x-show="$store.geo.isWatching"
  @click="$store.geo.unwatch()"
>
  Stop tracking
</button>

Notes

  • Requires user permission in secure contexts (HTTPS or localhost)
  • request() and watch() share the same reactive state; a successful update clears the previous error
  • reset() clears stored coordinates but does not stop an active watch — call unwatch() first if needed
  • Read-only environment access is not exposed as a magic; use the store for shared state and actions across components

Unified permissions adapter

import { permissionsPlugin } from "@ailuracode/alpine-permissions";
import { createGeoPermissionAdapter } from "@ailuracode/alpine-geo";

Alpine.plugin(
  permissionsPlugin({
    adapters: [createGeoPermissionAdapter()],
  })
);

Registry key: geolocation. See permissions.md.

License

MIT