Types & Interfaces

All TypeScript types and interfaces exported by the library, grouped by category.

import type {
  Coords,
  TrackingStatus,
  TrackingOptions,
  LocationUpdateEvent,
  LocationWarningEvent,
  LocationWarningType,
  NotificationAction,
  NotificationActionEvent,
  NotificationOptions,
  GeofenceRegion,
  GeofenceTransitionEvent,
  LocationPermissionState,
  NotificationPermissionState,
  PermissionState,
  UseLocationPermissionsResult,
  UseBackgroundLocationResult,
  UseLocationTrackingOptions,
  UseLocationTrackingResult,
  UseLocationUpdatesOptions,
  UseLocationUpdatesResult,
  UseGeofencingOptions,
  UseGeofencingReturn,
  UseGeofenceEventsOptions,
} from '@gabriel-sisjr/react-native-background-location';

---

Tracking Types

Coords

Location coordinates with extended location data. Returned by getLocations() and provided in location update events.

interface Coords {
  /** Latitude in decimal degrees */
  latitude: string;
  /** Longitude in decimal degrees */
  longitude: string;
  /** Timestamp in milliseconds since Unix epoch */
  timestamp: number;
  /** Horizontal accuracy in meters */
  accuracy?: number;
  /** Altitude in meters above sea level */
  altitude?: number;
  /** Speed in meters per second */
  speed?: number;
  /** Bearing in degrees (0-360) */
  bearing?: number;
  /** Vertical accuracy in meters (Android API 26+) */
  verticalAccuracyMeters?: number;
  /** Speed accuracy in meters per second (Android API 26+) */
  speedAccuracyMetersPerSecond?: number;
  /** Bearing accuracy in degrees (Android API 26+) */
  bearingAccuracyDegrees?: number;
  /** Elapsed realtime in nanoseconds since system boot */
  elapsedRealtimeNanos?: number;
  /** Location provider (gps, network, passive, etc.) */
  provider?: string;
  /** Whether the location is from a mock provider (Android API 18+) */
  isFromMockProvider?: boolean;
}

Property	Type	Required	Platform	Description
latitude	string	Yes	Both	Latitude in decimal degrees
longitude	string	Yes	Both	Longitude in decimal degrees
timestamp	number	Yes	Both	Milliseconds since Unix epoch
accuracy	number	No	Both	Horizontal accuracy in meters
altitude	number	No	Both	Altitude in meters above sea level
speed	number	No	Both	Speed in meters per second
bearing	number	No	Both	Bearing in degrees (0-360)
verticalAccuracyMeters	number	No	Android 26+	Vertical accuracy in meters
speedAccuracyMetersPerSecond	number	No	Android 26+	Speed accuracy in m/s
bearingAccuracyDegrees	number	No	Android 26+	Bearing accuracy in degrees
elapsedRealtimeNanos	number	No	Both	Nanoseconds since system boot
provider	string	No	Both	Location provider name
isFromMockProvider	boolean	No	Android 18+	Whether from a mock provider

---

TrackingStatus

Describes the current tracking state. Returned by isTracking().

interface TrackingStatus {
  active: boolean;
  tripId?: string;
}

Property	Type	Required	Description
active	boolean	Yes	Whether tracking is currently running
tripId	string	No	Current trip identifier (present when active is true)

---

LocationUpdateEvent

Location update event with extended location data. Emitted by the native event emitter.

interface LocationUpdateEvent {
  tripId: string;
  latitude: string;
  longitude: string;
  timestamp: number;
  accuracy?: number;
  altitude?: number;
  speed?: number;
  bearing?: number;
  verticalAccuracyMeters?: number;
  speedAccuracyMetersPerSecond?: number;
  bearingAccuracyDegrees?: number;
  elapsedRealtimeNanos?: number;
  provider?: string;
  isFromMockProvider?: boolean;
}

Same fields as Coords plus a required tripId field.

Property	Type	Required	Description
tripId	string	Yes	Trip identifier for this location update

All other fields match the Coords interface.

---

LocationWarningType

Union type for warning categories emitted by the location service.

type LocationWarningType =
  | 'SERVICE_TIMEOUT'
  | 'TASK_REMOVED'
  | 'LOCATION_UNAVAILABLE';

Value	Description
'SERVICE_TIMEOUT'	Android 15+ foreground service timeout reached; service is restarting
'TASK_REMOVED'	App was swiped from recents; tracking continues in background
'LOCATION_UNAVAILABLE'	GPS signal lost or location services disabled

---

LocationWarningEvent

Warning event emitted by the location service for non-critical issues that do not stop tracking.

interface LocationWarningEvent {
  /** Trip identifier for this warning */
  tripId: string;
  /** Type of warning */
  type: LocationWarningType;
  /** Human-readable description of the warning */
  message: string;
  /** Timestamp when the warning was emitted */
  timestamp: number;
}

Property	Type	Required	Description
tripId	string	Yes	Trip identifier for this warning
type	LocationWarningType	Yes	Warning category
message	string	Yes	Human-readable description
timestamp	number	Yes	Timestamp when emitted

---

NotificationAction

Configuration for a notification action button. Up to 3 actions can be added to the foreground service notification.

interface NotificationAction {
  /** Unique identifier for this action */
  id: string;
  /** Label displayed on the action button */
  label: string;
}

Property	Type	Required	Description
id	string	Yes	Unique identifier used to identify which action was pressed
label	string	Yes	Label displayed on the action button

---

NotificationActionEvent

Event emitted when a notification action button is pressed.

interface NotificationActionEvent {
  /** Trip identifier for the active tracking session */
  tripId: string;
  /** ID of the action that was pressed */
  actionId: string;
}

Property	Type	Required	Description
tripId	string	Yes	Trip identifier for the active tracking session
actionId	string	Yes	ID of the action that was pressed (matches NotificationAction.id)

---

TrackingOptions

Configuration options for location tracking. Passed to startTracking().

interface TrackingOptions {
  updateInterval?: number;
  fastestInterval?: number;
  maxWaitTime?: number;
  accuracy?: LocationAccuracy;
  waitForAccurateLocation?: boolean;
  distanceFilter?: number;
  notificationOptions?: NotificationOptions;
  foregroundOnly?: boolean;
  onUpdateInterval?: number;
}

Property	Type	Default	Platform	Description
updateInterval	number	5000	Both	Interval between location updates in milliseconds
fastestInterval	number	3000	Both	Fastest interval between updates in milliseconds. The system never updates faster than this.
maxWaitTime	number	10000	Both	Maximum wait time in milliseconds before delivering batched updates
accuracy	LocationAccuracy	HIGH_ACCURACY	Both	Location accuracy priority level
waitForAccurateLocation	boolean	false	Both	Whether to delay updates until accurate location is available
distanceFilter	number	0	Android	Minimum distance in meters between updates. 0 = no filter.
notificationOptions	NotificationOptions	—	Both	Foreground service notification configuration
foregroundOnly	boolean	false	Android	Foreground-only mode. Does not require background location permission.
onUpdateInterval	number	undefined	Both	Throttle interval for the onLocationUpdate callback in milliseconds. Locations are still collected at updateInterval rate.

---

Notification Types

NotificationOptions

Unified notification configuration interface used across the library for foreground service notifications and geofence transition notifications.

For geofencing, the title and text fields support template variables. See GEOFENCE_TEMPLATE_VARS.

interface NotificationOptions {
  enabled?: boolean;
  title?: string;
  text?: string;
  channelName?: string;
  channelId?: string;
  priority?: NotificationPriority;
  smallIcon?: string;
  largeIcon?: string;
  color?: string;
  showTimestamp?: boolean;
  subtext?: string;
  actions?: NotificationAction[];
  transitionOverrides?: Partial<
    Record<
      'ENTER' | 'EXIT' | 'DWELL',
      Omit<NotificationOptions, 'transitionOverrides' | 'enabled'>
    >
  >;
}

Property	Type	Default	Platform	Description
enabled	boolean	true	Both	Whether notifications are shown
title	string	—	Both	Notification title. Supports template variables for geofencing.
text	string	—	Both	Notification body text. Supports template variables for geofencing.
channelName	string	—	Android	Android notification channel name
channelId	string	—	Android	Android notification channel ID
priority	NotificationPriority	—	Android	Notification priority
smallIcon	string	—	Android	Android drawable resource name for the small icon
largeIcon	string	—	Android	Android drawable resource name for the large icon
color	string	—	Android	Hex color string for notification accent color
showTimestamp	boolean	—	Android	Whether to show timestamp on the notification
subtext	string	—	Android	Subtext displayed below the notification content
actions	NotificationAction[]	—	Android	Action buttons (max 3). Currently supported for foreground service notifications only.
transitionOverrides	Partial<Record<...>>	—	Both	Per-transition notification overrides (ENTER, EXIT, DWELL)

Note: transitionOverrides allows customizing notification content per transition type. Unspecified fields fall through to the parent config. The enabled and transitionOverrides fields are excluded from per-transition overrides to prevent recursion.

---

GEOFENCE_TEMPLATE_VARS

Constant object providing available template variables for geofence notification title and text fields. Variables are resolved at notification time on the native side.

const GEOFENCE_TEMPLATE_VARS = {
  IDENTIFIER: '{{identifier}}',
  TRANSITION_TYPE: '{{transitionType}}',
  LATITUDE: '{{latitude}}',
  LONGITUDE: '{{longitude}}',
  RADIUS: '{{radius}}',
  TIMESTAMP: '{{timestamp}}',
} as const;

Key	Template	Resolved to
IDENTIFIER	{{identifier}}	The geofence's identifier string
TRANSITION_TYPE	{{transitionType}}	ENTER, EXIT, or DWELL
LATITUDE	{{latitude}}	Device latitude at transition
LONGITUDE	{{longitude}}	Device longitude at transition
RADIUS	{{radius}}	Geofence radius in meters
TIMESTAMP	{{timestamp}}	Transition timestamp

Usage

import { GEOFENCE_TEMPLATE_VARS } from '@gabriel-sisjr/react-native-background-location';

const options = {
  title: 'Geofence Alert',
  text: `You entered ${GEOFENCE_TEMPLATE_VARS.IDENTIFIER} at ${GEOFENCE_TEMPLATE_VARS.TIMESTAMP}`,
};

---

Permission Types

LocationPermissionState

Granular status information for location permissions.

interface LocationPermissionState {
  hasPermission: boolean;
  status: LocationPermissionStatus;
  canRequestAgain: boolean;
}

Property	Type	Description
hasPermission	boolean	true if status is GRANTED or WHEN_IN_USE
status	LocationPermissionStatus	Current permission status enum value
canRequestAgain	boolean	Whether the permission dialog can be shown again

---

NotificationPermissionState

Granular status information for notification permissions.

interface NotificationPermissionState {
  hasPermission: boolean;
  status: NotificationPermissionStatus;
  canRequestAgain: boolean;
}

Property	Type	Description
hasPermission	boolean	true if status is GRANTED
status	NotificationPermissionStatus	Current permission status enum value
canRequestAgain	boolean	Whether the permission dialog can be shown again

---

PermissionState

Combined permission state for both location and notification permissions.

interface PermissionState {
  hasAllPermissions: boolean;
  location: LocationPermissionState;
  notification: NotificationPermissionState;
}

Property	Type	Description
hasAllPermissions	boolean	true only when both location and notification are granted
location	LocationPermissionState	Location permission details
notification	NotificationPermissionState	Notification permission details

---

UseLocationPermissionsResult

Return type for the useLocationPermissions hook.

interface UseLocationPermissionsResult {
  permissionStatus: PermissionState;
  requestPermissions: () => Promise<boolean>;
  checkPermissions: () => Promise<boolean>;
  isRequesting: boolean;
}

Property	Type	Description
permissionStatus	PermissionState	Current permission state
requestPermissions	() => Promise<boolean>	Request all permissions. Returns true if location is granted.
checkPermissions	() => Promise<boolean>	Check permissions without requesting. Returns true if location is granted.
isRequesting	boolean	Whether a permission request is in progress

---

Geofencing Types

GeofenceRegion

Defines a circular geofence region for monitoring.

interface GeofenceRegion {
  identifier: string;
  latitude: number;
  longitude: number;
  radius: number;
  transitionTypes?: GeofenceTransitionType[];
  loiteringDelay?: number;
  expirationDuration?: number;
  metadata?: Record<string, unknown>;
  notificationOptions?: NotificationOptions | false;
}

Property	Type	Default	Description
identifier	string	—	Unique identifier for this geofence (required)
latitude	number	—	Center latitude (-90 to 90)
longitude	number	—	Center longitude (-180 to 180)
radius	number	—	Radius in meters (minimum 100)
transitionTypes	GeofenceTransitionType[]	[ENTER, EXIT]	Transition types to monitor
loiteringDelay	number	30000	Loitering delay in milliseconds for DWELL detection
expirationDuration	number	undefined	Expiration duration in milliseconds. If omitted, remains active indefinitely.
metadata	Record<string, unknown>	undefined	Optional JSON-serializable metadata
notificationOptions	NotificationOptions | false	undefined	Per-geofence notification config. Set to false to suppress notifications for this geofence.

Note: The notificationOptions resolution chain (highest to lowest priority):

1. Per-geofence notificationOptions (this field)
2. Global config via configureGeofenceNotifications()
3. Platform defaults

---

GeofenceTransitionEvent

Event emitted when a geofence transition is detected.

interface GeofenceTransitionEvent {
  geofenceId: string;
  transitionType: GeofenceTransitionType;
  latitude: number;
  longitude: number;
  timestamp: string;
  distanceFromCenter: number;
  metadata?: Record<string, unknown>;
}

Property	Type	Description
geofenceId	string	Identifier of the geofence that triggered the event
transitionType	GeofenceTransitionType	Type of transition detected (ENTER, EXIT, or DWELL)
latitude	number	Device latitude at the moment of transition
longitude	number	Device longitude at the moment of transition
timestamp	string	Timestamp of the transition (ISO 8601 string)
distanceFromCenter	number	Distance from the center of the geofence in meters
metadata	Record<string, unknown>	Metadata associated with the geofence, if any

---

Hook Types

UseBackgroundLocationResult

Return type for the useBackgroundLocation hook.

interface UseBackgroundLocationResult {
  tripId: string | null;
  isTracking: boolean;
  locations: Coords[];
  isLoading: boolean;
  error: Error | null;
  startTracking: (customTripId?: string, options?: TrackingOptions) => Promise<string | null>;
  stopTracking: () => Promise<void>;
  refreshLocations: () => Promise<void>;
  clearCurrentTrip: () => Promise<void>;
  clearError: () => void;
}

Property	Type	Description
tripId	string | null	Current trip ID, or null if not tracking
isTracking	boolean	Whether tracking is active
locations	Coords[]	All locations collected for the current trip
isLoading	boolean	Whether an async operation is in progress
error	Error | null	Last error that occurred
startTracking	(customTripId?, options?) => Promise<string | null>	Start tracking with optional trip ID and options
stopTracking	() => Promise<void>	Stop tracking
refreshLocations	() => Promise<void>	Reload locations from database
clearCurrentTrip	() => Promise<void>	Clear all data for the current trip
clearError	() => void	Reset error state to null

---

UseLocationTrackingOptions

Options for the useBackgroundLocation hook.

interface UseLocationTrackingOptions {
  autoStart?: boolean;
  tripId?: string;
  options?: TrackingOptions;
  onTrackingStart?: (tripId: string) => void;
  onTrackingStop?: () => void;
  onError?: (error: Error) => void;
}

Property	Type	Default	Description
autoStart	boolean	false	Automatically start tracking when component mounts
tripId	string	—	Custom trip ID to use
options	TrackingOptions	—	Tracking configuration options
onTrackingStart	(tripId: string) => void	—	Callback when tracking starts
onTrackingStop	() => void	—	Callback when tracking stops
onError	(error: Error) => void	—	Callback when an error occurs

---

UseLocationTrackingResult

Return type for the useLocationTracking hook.

interface UseLocationTrackingResult {
  isTracking: boolean;
  tripId: string | null;
  refresh: () => Promise<void>;
  isLoading: boolean;
}

Property	Type	Description
isTracking	boolean	Whether tracking is active
tripId	string | null	Current trip ID, or null
refresh	() => Promise<void>	Manually re-check tracking status
isLoading	boolean	Whether status is being checked

---

UseLocationUpdatesOptions

Options for the useLocationUpdates hook.

interface UseLocationUpdatesOptions {
  tripId?: string;
  onLocationUpdate?: (location: Coords) => void;
  onUpdateInterval?: number;
  onLocationWarning?: (warning: LocationWarningEvent) => void;
  onNotificationAction?: (event: NotificationActionEvent) => void;
  autoLoad?: boolean;
}

Property	Type	Default	Description
tripId	string	—	Specific trip ID to watch. If not provided, watches all trips.
onLocationUpdate	(location: Coords) => void	—	Callback for each new location
onUpdateInterval	number	undefined	Throttle interval in milliseconds for the onLocationUpdate callback
onLocationWarning	(warning: LocationWarningEvent) => void	—	Callback for service warnings
onNotificationAction	(event: NotificationActionEvent) => void	—	Callback for notification action button presses
autoLoad	boolean	true	Whether to automatically load existing locations on mount

---

UseLocationUpdatesResult

Return type for the useLocationUpdates hook.

interface UseLocationUpdatesResult {
  tripId: string | null;
  isTracking: boolean;
  locations: Coords[];
  lastLocation: Coords | null;
  lastWarning: LocationWarningEvent | null;
  isLoading: boolean;
  error: Error | null;
  clearError: () => void;
  clearLocations: () => Promise<void>;
  refreshLocations: () => Promise<void>;
}

Property	Type	Description
tripId	string | null	Current trip ID being watched
isTracking	boolean	Whether tracking is active
locations	Coords[]	All locations received, updated in real time
lastLocation	Coords | null	Most recently received location
lastWarning	LocationWarningEvent | null	Most recent service warning
isLoading	boolean	Whether data is being loaded
error	Error | null	Last error that occurred
clearError	() => void	Reset error state
clearLocations	() => Promise<void>	Clear all locations for the current trip
refreshLocations	() => Promise<void>	Manually re-load locations from the database

---

UseGeofencingOptions

Options for the useGeofencing hook.

interface UseGeofencingOptions {
  autoLoad?: boolean;
  notificationOptions?: NotificationOptions;
}

Property	Type	Default	Description
autoLoad	boolean	true	Whether to automatically load geofences on mount
notificationOptions	NotificationOptions	—	Global notification config. When provided, calls configureGeofenceNotifications() on mount.

---

UseGeofencingReturn

Return type for the useGeofencing hook.

interface UseGeofencingReturn {
  geofences: GeofenceRegion[];
  isLoading: boolean;
  error: Error | null;
  addGeofence: (region: GeofenceRegion) => Promise<void>;
  addGeofences: (regions: GeofenceRegion[]) => Promise<void>;
  removeGeofence: (identifier: string) => Promise<void>;
  removeGeofences: (identifiers: string[]) => Promise<void>;
  removeAllGeofences: () => Promise<void>;
  maxGeofences: number | null;
  refresh: () => Promise<void>;
  clearError: () => void;
}

Property	Type	Description
geofences	GeofenceRegion[]	Currently active geofence regions
isLoading	boolean	Whether an async operation is in progress
error	Error | null	Last error that occurred
addGeofence	(region) => Promise<void>	Register a single geofence
addGeofences	(regions) => Promise<void>	Register multiple geofences atomically
removeGeofence	(identifier) => Promise<void>	Remove a single geofence
removeGeofences	(identifiers) => Promise<void>	Remove multiple geofences
removeAllGeofences	() => Promise<void>	Remove all geofences
maxGeofences	number | null	Platform limit, or null if not yet loaded
refresh	() => Promise<void>	Reload geofences and platform limit
clearError	() => void	Reset error state

---

UseGeofenceEventsOptions

Options for the useGeofenceEvents hook.

interface UseGeofenceEventsOptions {
  onTransition?: (event: GeofenceTransitionEvent) => void;
  filter?: GeofenceTransitionType[];
  geofenceId?: string;
}

Property	Type	Default	Description
onTransition	(event: GeofenceTransitionEvent) => void	—	Callback when a geofence transition is detected (after filters are applied)
filter	GeofenceTransitionType[]	—	Only emit events matching these transition types. If omitted, all transitions fire.
geofenceId	string	—	Only emit events for this specific geofence identifier. If omitted, all geofences fire.