LeCodesdocs

Geolocation

The device position — one-shot fixes and continuous watching. Unlike QRScanner / CameraView there is no view to present: Geolocation is a service plugin, a typed wrapper over the host-registered "geolocation" service. Host-optional — always guard with Geolocation.isSupported before offering location features.

At a glance

TypeScript
if (Geolocation.isSupported) {
  const pos = await Geolocation.getCurrent()
  console.log(pos.latitude, pos.longitude, '±' + pos.accuracy + 'm')
}

API

TypeScript
Geolocation.isSupported: boolean            // static — did this host register the service?

Geolocation.getCurrent(options?): Promise<GeoPosition>
Geolocation.watch(cb: (pos: GeoPosition) => void, options?): Promise<{ stop(): void }>

interface GeoPosition {
  latitude: number; longitude: number
  accuracy: number                // horizontal radius, meters
  altitude: number | null        // meters, null when unknown
  heading: number | null          // degrees clockwise from north, null when stationary
  speed: number | null            // m/s, null when unknown
  timestamp: number               // when the fix was taken, ms epoch
}
interface GeoOptions {
  highAccuracy?: boolean          // prefer GPS: slower first fix, more battery (default false)
  timeout?: number                // getCurrent only: reject "timeout" after this many ms
}
  • The OS permission prompt happens on the first call (getCurrent or watch) — never earlier. Denial is a rejection (Error("denied")); also expect "unavailable" (no provider) and "timeout". On hosts without the service both methods reject immediately, before any permission path.
  • watch() resolves once the host is actually watching (permission granted, provider started), so a denial is a rejection — never a silently dead callback. Updates then arrive at whatever rate the platform provider delivers.
  • One host watch serves every subscriber: watch() twice costs one GPS session, and the options of the watch that started it win. Each subscription has its own stop(); the last stop() releases the provider.
Note

lifecycle — a running watch keeps the location hardware (and the OS indicator) on. Always stop() when leaving the screen (onClose), same rule as closing a camera.

Watching a position

TypeScript
const screen = UIScreen(
  UIText(() => label.value).style({ fontSize: 20 }),
)
const label = signal('locating…')

const watch = await Geolocation.watch(pos => {
  label.value = pos.latitude.toFixed(5) + ', ' + pos.longitude.toFixed(5)
})
screen.onClose(() => watch.stop())

See also

← BackQRScannerNext →Push