GebetaMap React Native SDK

A React Native SDK for integrating Gebeta Maps into your applications.

Features

• Interactive maps with Gebeta tiles
• Marker management
• Fence drawing
• Path visualization
• Clustering support
• Geocoding and reverse geocoding
• Directions and routing
• Navigation UI (route rendering + HUD)
• Custom styling options

Installation

yarn add @gebeta/tiles-react-native
yarn add @maplibre/maplibre-react-native

maplibre is a required dependency.

Basic Usage

import React, { useRef } from 'react';
import { View, Alert } from 'react-native';
import { GebetaMap, GebetaMapRef } from '@gebeta/tiles-react-native';

const App = () => {
  const mapRef = useRef<GebetaMapRef>(null);

  const handleMapClick = (lngLat: [number, number], event: any) => {
    Alert.alert(
      'Map Clicked',
      `Longitude: ${lngLat[0].toFixed(6)}\nLatitude: ${lngLat[1].toFixed(6)}`
    );
  };

  const handleMapLoaded = () => {
    // Add a marker after map loads
    if (mapRef.current) {
      mapRef.current.addImageMarker(
        [38.7463, 9.0223], // Addis Ababa coordinates
        'https://via.placeholder.com/32x32/007cbf/ffffff?text=M',
        [32, 32],
        (lngLat, marker, event) => {
          Alert.alert('Marker Clicked', 'You clicked on Addis Ababa!');
        }
      );
    }
  };

  return (
    <View style={{ flex: 1 }}>
      <GebetaMap
        ref={mapRef}
        apiKey="your-api-key-here"
        center={[38.7463, 9.0223]} // Addis Ababa
        zoom={12}
        onMapClick={handleMapClick}
        onMapLoaded={handleMapLoaded}
      />
    </View>
  );
};

export default App;

Fly

import React, { useRef } from 'react';
import { Alert, View, Button, StyleSheet } from 'react-native'; 
import GebetaMap, { GebetaMapRef } from '@gebeta/tiles-react-native';

const App = () => {
    const mapRef = useRef<GebetaMapRef>(null);

    const handleMapClick = (lngLat: [number, number]) => {
        Alert.alert(
            'Map Clicked',
            `Longitude: ${lngLat[0].toFixed(6)}\nLatitude: ${lngLat[1].toFixed(6)}`
        );
    };


    const handleFlyToBahirDar = () => {
        if (mapRef.current) {
            mapRef.current.flyTo({
                center: [37.3895, 11.5946],
                zoom: 14,
                pitch: 45,
                duration: 5000,
            });
        }
    };

    return (
        <View style={styles.container}>
            <GebetaMap
                ref={mapRef}
                apiKey="your-api-key-here"
                center={[38.7463, 9.0223]}
                zoom={12}
                onMapClick={handleMapClick}
                style={"https://tiles.gebeta.app/styles/standard/style.json"}
            />

            <View style={styles.buttonContainer}>
                <Button title="✈️ Fly to Bahir Dar" onPress={handleFlyToBahirDar} />
            </View>
        </View>
    );
};


const styles = StyleSheet.create({
    container: {
        flex: 1,
    },
    buttonContainer: {
        position: 'absolute',
        top: 60,
        left: 0,
        right: 0,
        alignItems: 'center',
    },
});

export default App;

API Reference

GebetaMap Props

| Prop | Type | Required | Description | |------|------|----------|-------------| | apiKey | string | Yes | Your Gebeta Maps API key | | center | [number, number] | Yes | Initial map center coordinates [longitude, latitude] | | zoom | number | Yes | Initial zoom level | | onMapClick | (lngLat: [number, number], event: any) => void | No | Callback when map is clicked | | onMapLoaded | () => void | No | Callback when map finishes loading | | blockInteractions | boolean | No | Disable map interactions | | style | any | No | Custom styles for the map container | | clusteringOptions | ClusteringOptions | No | Options for marker clustering |

GebetaMapRef Methods

Marker Management

• addImageMarker(lngLat, imageUrl, size, onClick, zIndex, popupHtml) - Add an image marker
• addMarker(options) - Add a basic marker
• clearMarkers() - Remove all markers
• getMarkers() - Get all current markers

Fence Management

• startFence() - Start drawing a fence
• addFencePoint(lngLat, customImage, onClick) - Add a point to the current fence
• closeFence() - Close the current fence
• clearFence() - Clear the current fence
• clearAllFences() - Clear all fences
• getFences() - Get all fences
• getFencePoints() - Get current fence points
• isDrawingFence() - Check if currently drawing a fence

Path Management

• addPath(path, options) - Add a path to the map
• clearPaths() - Clear all paths

Fly Control

• flyTo(options) – Animate the map camera to a specified location with optional zoom, bearing, pitch, and duration.

Clustering

• addClusteredMarker(marker) - Add a marker for clustering
• clearClusteredMarkers() - Clear all clustered markers
• updateClustering() - Update clustering
• setClusteringEnabled(enabled) - Enable/disable clustering
• setClusterImage(imageUrl) - Set custom cluster image

Geocoding

• geocode(name) - Geocode an address
• reverseGeocode(lat, lon) - Reverse geocode coordinates

Directions

• getDirections(origin, destination, options) - Get directions between two points
• convertDirectionsToNavigationRoute(response) - Convert Gebeta directions response to NavigationRoute
• displayRoute(routeData, options) - Display a route on the map
• clearRoute() - Clear the current route
• getCurrentRoute() - Get the current route
• getRouteSummary() - Get route summary
• updateRouteStyle(style) - Update route styling

Navigation

• startNavigation(route, options) - Start navigation with a NavigationRoute
• updateNavigationPosition([lng, lat]) - Update position (e.g., from GPS)
• stopNavigation() - Stop navigation
• getNavigationState() - Get current navigation state
• isNavigating() - Check if navigation is active

Navigation route shape

type NavigationRoute = {
  coordinates: [number, number][]; // [lng, lat]
  distance?: number;   // meters
  duration?: number;   // seconds
  instructions?: {
    type: 'turn' | 'straight' | 'arrive' | 'depart';
    direction?: 'left' | 'right' | 'slight-left' | 'slight-right' | 'sharp-left' | 'sharp-right';
    distance: number; // meters
    text: string;
    coordinate: [number, number];
  }[];
};

Using Gebeta Directions response The Gebeta API returns:

{
  "msg": "Ok",
  "timetaken": 5102.905,
  "totalDistance": 15308.715,
  "direction": [
    [lng, lat],
    ...
  ]
}

Convert and start navigation:

const res = await mapRef.current?.getDirections(origin, destination);
const route = mapRef.current?.convertDirectionsToNavigationRoute(res);
if (route) {
  mapRef.current?.startNavigation(route, {
    onNavigationUpdate: (state) => mapRef.current?.updateNavigationPosition(/* GPS coords */),
  });
}

GPS tracking

• The library does not bundle a GPS dependency; use your preferred location library (e.g. @react-native-community/geolocation) to call updateNavigationPosition([lng, lat]).
• On Android, request ACCESS_FINE_LOCATION. On iOS, set NSLocationWhenInUseUsageDescription.

Example App

To test the package, navigate to the example and run:

cd example/GebetaMapsFence
yarn install
yarn android  # or yarn ios

Development

To build the package:

yarn build

License

MIT