> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider/propiedades/geolocation.md).

# geolocation

Configure the browser's native geolocation capture as disabled, optional, or required.

## Details

**Attribute:** `geolocation`

**Type:** `GeolocationMode`

**Default value:** `GeolocationMode.Disabled` (`DISABLED`)

## Morphology

```typescript
import { GeolocationMode } from '@facephi/sdk-web-wc';

provider.geolocation = GeolocationMode.Optional;
```

### GeolocationMode

| Member     | Value      | Description                                                             |
| ---------- | ---------- | ----------------------------------------------------------------------- |
| `Disabled` | `DISABLED` | Location is not requested.                                              |
| `Optional` | `OPTIONAL` | Location is requested, and the flow continues regardless of the result. |
| `Required` | `REQUIRED` | Location is requested, and the flow continues only if it is obtained.   |

## Description

Requests the user's location through the browser's native API (`navigator.geolocation`) once the license has been validated, which displays the browser's permission dialog. The request is made before any SDK service or capture flow starts. It runs only once per component mount, and its result is emitted in the [geolocationFinish](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider/eventos/geolocationfinish.md).

A `video-provider` with local recording is the exception: it starts when mounted and may request access to the camera and microphone before requesting the location.

Works the same with standard SDK licenses and IDV licenses.

When the location is obtained, the coordinates (`latitude`, `longitude` and `accuracy`):

* are sent to the operation's tracking as a `COORDINATES`event. Only with standard SDK licenses: they are not yet sent to tracking in IDV flows.
* They are added to the object received in the `extractionFinish` event from [Selphi](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/selphi-biometria-facial/eventos/extractionfinish.md) and [SelphID](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/selphid-documentos/eventos/extractionfinish.md).

### OPTIONAL

The SDK does not wait for the permission dialog: initialization continues after the request is made. If the user denies permission or the location cannot be obtained, the flow continues as usual, and the result is only reported in `geolocationFinish`.

Because the flow does not stop, a capture can finish while the request is still pending. In that case, the `coordinates` property of `extractionFinish` is `null`, just as if permission had been denied: `geolocationFinish` is the channel that distinguishes the two cases. In `REQUIRED` this never happens, because it resolves the request before any capture starts.

### REQUIRED

The SDK waits for the request to resolve before continuing. If the user denies permission or the location cannot be obtained, the flow stops with the error `GeolocationError` ([code `SDK_139`](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider/codigos-de-error.md)).

If the result is `DENIED` or `UNAVAILABLE` (permission denied or location disabled in the operating system), the SDK displays a screen asking the user to enable location. With `INSECURE` or `UNSUPPORTED` the user cannot resolve the issue, so the generic error screen is displayed.

### Additional information

**Secure context:** the browser only allows geolocation in secure contexts (`https` or `localhost`). On any other origin, the result is `INSECURE` and the permission dialog is not shown.

**Remembered permission:** the browser remembers the user's decision for the domain. Once denied, the dialog does not appear again until permission is reset in the browser settings.

**Timeout:** the request is delegated entirely to the browser, with no SDK-specific timeout. In `REQUIRED` mode, this means the SDK remains in a loading state while the user does not respond to the dialog.

**Validation:** the value is normalized to uppercase. An unsupported value is replaced with `DISABLED` with a console warning or, if [settingsStrictness](https://docs.facephi.com/docs.facephi-en/sdks/sdk-web/componentes/sdk-provider/propiedades/settingsstrictness.md) is enabled, it stops the SDK with the error `SettingsError`.

***

## Example

```jsx
import { GeolocationMode } from '@facephi/sdk-web-wc';

<facephi-sdk-provider
    apikey={process.env.FACEPHI_SDK_APIKEY}
    geolocation={GeolocationMode.Required}
    onGeolocationFinish={(event) => console.log('Geolocation:', event.detail)}
/>
```
