Geolocation

Permission and secure context Geolocation only works in a secure context (HTTPS or localhost), and the browser prompts the user for permission on first use. A denied prompt surfaces as a GeolocationException with Code == GeolocationErrorCode.PermissionDenied - always wrap calls in a try/catch.

Support check

IsSupported

Returns true when the runtime exposes navigator.geolocation. During prerender/SSR the check returns false rather than throwing, so defer it to OnAfterRenderAsync.

@inject Bit.Butil.Geolocation geolocation

var supported = await geolocation.IsSupported();

Live sample

support check output

Results will appear here when you interact with the samples.

Current position

GetCurrentPosition

One-shot read of the device position. GeolocationOptions maps to the browser's PositionOptions: EnableHighAccuracy trades power for precision, Timeout caps how long the device may take (milliseconds), and MaximumAge allows a cached fix up to the given age.

try
{
    var pos = await geolocation.GetCurrentPosition(new GeolocationOptions
    {
        EnableHighAccuracy = true,
        Timeout = 10_000,
        MaximumAge = 0,
    });

    var lat = pos.Coords.Latitude;
    var lng = pos.Coords.Longitude;
    var accuracy = pos.Coords.Accuracy; // meters
}
catch (GeolocationException ex)
{
    // ex.Code: PermissionDenied, PositionUnavailable, Timeout or Unknown
}

Live sample

Timeout (ms)

Maximum age (ms)

Enable high accuracy

current position output

Results will appear here when you interact with the samples.

Watch position

Watch / ClearWatch

Subscribes to continuous position updates. Watch returns a Guid you pass to ClearWatch to stop; the position handler runs on the Blazor sync context, so updating component state from it is safe.

var watchId = await geolocation.Watch(
    onPosition: pos => { /* fires on every movement */ },
    onError: ex => { /* GeolocationException */ });

// later:
await geolocation.ClearWatch(watchId);

Live sample

watch position output

Results will appear here when you interact with the samples.

Subscription-style watch

SubscribeWatch / ClearAllWatches

SubscribeWatch is the same as Watch but returns a ButilSubscription, so a component can hold one field and dispose it in DisposeAsync - no Guid bookkeeping. ClearAllWatches stops every watch this Geolocation instance has started.

private ButilSubscription? _sub;

_sub = await geolocation.SubscribeWatch(pos => { /* ... */ });

// stop this one:
await _sub.DisposeAsync();

// or stop everything started by this instance:
await geolocation.ClearAllWatches();

Live sample

subscription watch output

Results will appear here when you interact with the samples.

Timeout default When you pass no options, Timeout defaults to long.MaxValue - the call waits indefinitely for a fix. Set an explicit timeout when a slow GPS lock should fail fast.

API reference

Member

Signature

Description

IsSupported

ValueTask<bool> IsSupported()

True when the runtime exposes navigator.geolocation. Returns default (false) during prerender/SSR instead of throwing.

GetCurrentPosition

Task<GeolocationPosition> GetCurrentPosition(GeolocationOptions? options = null)

Returns the device's current position once. Throws GeolocationException on denial, unavailability or timeout.

Watch

Task<Guid> Watch(Action<GeolocationPosition>? onPosition, Action<GeolocationException>? onError = null, GeolocationOptions? options = null)

Subscribes to continuous position updates; returns the watch id. The handler runs on the Blazor sync context.

ClearWatch

ValueTask ClearWatch(Guid id)

Stops a previously registered watch.

SubscribeWatch

Task<ButilSubscription> SubscribeWatch(Action<GeolocationPosition>? onPosition, Action<GeolocationException>? onError = null, GeolocationOptions? options = null)

Watch variant that returns an IAsyncDisposable subscription handle instead of a Guid.

ClearAllWatches

ValueTask ClearAllWatches()

Stops every watch this instance has started.

DisposeAsync

ValueTask DisposeAsync()

Clears all watches and releases the JS callback reference. Called automatically on scope/circuit teardown.

InvokePosition

void InvokePosition(Guid id, GeolocationPosition position)

JSInvokable interop plumbing for watch updates - not intended for app code.

InvokeError

void InvokeError(Guid id, int code, string message)

JSInvokable interop plumbing for watch errors - not intended for app code.

GeolocationOptions.EnableHighAccuracy

bool EnableHighAccuracy { get; set; }

Request the most accurate result possible (may be slower / use more power).

GeolocationOptions.MaximumAge

long MaximumAge { get; set; }

Maximum acceptable age of a cached position in milliseconds. 0 means never use a cache.

GeolocationOptions.Timeout

long Timeout { get; set; }

How long the device may take to return a position before a GeolocationException is raised. Defaults to long.MaxValue.