geolocation

Watch the device position with the Geolocation API.


Package	`@vizejs/composable/geolocation`
Own the source	`vize lib pull composable:geolocation`
Runtime exports	`useGeolocation`
Gzip budget	2048 B

Usage

import { useGeolocation } from "@vizejs/composable/geolocation";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useGeolocation`	sensors	experimental	deterministic-fallback	stable	reactive-scope	web, desktop	`window`	`availableCapability`, `unavailableCapability`, `tryOnScopeDispose`

API

`useGeolocation`

Watch the device position with the Geolocation API. The watch follows the reactive host and is cleared when paused or when the owning reactive scope stops. Coordinates are copied into a plain snapshot so they are serializable. The capability result reports "unsupported", "permission-denied", "unavailable", or "not-ready" (before the first fix) as data instead of throwing. Server renders expose null coordinates.

function useGeolocation(options: UseGeolocationOptions = {}): GeolocationControls

Types

`GeolocationHost`

Navigator-like capability used by useGeolocation.

Member	Type	Description
`geolocation`?	`Pick<Geolocation, "watchPosition" \| "clearWatch">`	Geolocation service, absent in unsupported runtimes.

`GeolocationCoordinatesSnapshot`

Serializable snapshot of GeolocationCoordinates.

Member	Type	Description
`latitude`	`number`	Latitude in decimal degrees.
`longitude`	`number`	Longitude in decimal degrees.
`accuracy`	`number`	Accuracy radius of latitude/longitude in meters.
`altitude`	`number \| null`	Altitude in meters, when available.
`altitudeAccuracy`	`number \| null`	Altitude accuracy in meters, when available.
`heading`	`number \| null`	Heading in degrees clockwise from true north, when available.
`speed`	`number \| null`	Ground speed in meters per second, when available.

`UseGeolocationOptions`

Options for useGeolocation.

Member	Type	Description
`enableHighAccuracy`?	`boolean`	Ask for the most accurate position the device can provide.
`maximumAge`?	`number`	Maximum age in milliseconds of a cached position.
`timeout`?	`number`	Maximum time in milliseconds to wait for a position.
`immediate`?	`boolean`	Start watching during composable creation. When `false`, call `resume` (typically from a user gesture, which some browsers require).
`host`?	`MaybeRefOrGetter<GeolocationHost \| null \| undefined>`	Reactive navigator capability for alternate runtimes and tests.

`GeolocationControls`

Reactive position state returned by useGeolocation.

Member	Type	Description
`isSupported`	`Readonly<Ref<boolean>>`	Whether the host exposes geolocation. `false` during server rendering.
`coords`	`Readonly<ShallowRef<GeolocationCoordinatesSnapshot \| null>>`	Latest coordinates; `null` until the first fix and during server rendering.
`locatedAt`	`Readonly<Ref<number \| null>>`	Epoch milliseconds of the latest fix; `null` before the first fix.
`error`	`Readonly<ShallowRef<GeolocationPositionError \| null>>`	Latest platform error; cleared by the next successful fix.
`capability`	`ComputedRef< CapabilityResult<GeolocationCoordinatesSnapshot, GeolocationUnavailableReason> >`	Capability result combining support, permission, and readiness.
`isActive`	`Readonly<Ref<boolean>>`	Whether a position watch is active.
`resume`	`() => void`	Start (or restart) watching.
`pause`	`() => void`	Stop watching. Idempotent.