@gebeta/tiles-react-native

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