> ## Documentation Index
> Fetch the complete documentation index at: https://committ.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# useLocation

> GPS position tracking with three-branch permission handling.

# useLocation

**Source:** `hooks/useLocation.ts` (102 lines)

The useLocation hook manages GPS position tracking with a three-branch permission handling strategy that adapts to the user's current permission state.

***

## Permission State Machine

The hook handles three distinct permission states:

```
getForegroundPermissionsAsync()
    │
    ├── CASE A: status === "granted"
    │       → Fetch location immediately
    │
    ├── CASE B: status !== "granted" AND canAskAgain === true
    │       → Show system permission dialog
    │       → If granted, fetch location
    │
    └── CASE C: status !== "granted" AND canAskAgain === false
            → Permission permanently blocked
            → Show Alert with "Open Settings" button
            → Deep-link to Android Settings via Linking.openSettings()
```

***

## Location Fetch

When permission is granted, the hook fetches the current position with high accuracy:

```typescript theme={null}
const location = await Location.getCurrentPositionAsync({
  accuracy: Location.Accuracy.High,
});
```

***

## Callback Pattern

The requestLocation function accepts an optional onSuccess callback, allowing callers to run additional logic (like animating the map camera) immediately after coordinates are available:

```typescript theme={null}
const coords = await requestLocation((coords) => {
  mapRef.current?.animateCamera({ center: coords });
});
```

***

## Return Value

| Field           | Type                   | Purpose                                                |
| :-------------- | :--------------------- | :----------------------------------------------------- |
| hasPermission   | boolean or null        | null = not yet checked, true = granted, false = denied |
| currentLocation | LocationCoords or null | Latest GPS coordinates                                 |
| isLocating      | boolean                | True while a position request is in flight             |
| requestLocation | function               | Triggers the permission check and location fetch       |

***

## LocationCoords Type

```typescript theme={null}
interface LocationCoords {
  latitude: number;
  longitude: number;
}
```