Gebeta Maps React SDK

A modern React SDK for integrating Gebeta Maps into your applications.
Provides a declarative <GebetaMap /> component, advanced marker management, fence drawing, clustering, and a clean, extensible API.

Features

• React component for embedding Gebeta Maps
• Add default and custom image markers
• Marker management (add, remove, clear, batch)
• Popups, z-index, and click handlers for markers
• Fence drawing and management
• Marker clustering
• Geocoding and reverse geocoding
• Directions and routing
• Example gallery and usage patterns

Installation

yarn add @gebeta/tiles

Quick Start

1. Add your API key

Create a .env file in your project root:

VITE_GEBETA_MAPS_API_KEY=your_gebeta_maps_api_key

2. Use the <GebetaMap /> component

import React, { useRef, useState } from "react";
import GebetaMap, { GebetaMapRef } from "@gebeta/tiles";

const MyMap = () => {
  const mapRef = useRef<GebetaMapRef>(null);
  const [isMapLoaded, setIsMapLoaded] = useState(false);

  const handleMapClick = (lngLat: [number, number]) => {
    // Add a default marker
    const marker = mapRef.current?.addMarker();
    const mapInstance = mapRef.current?.getMapInstance();
    if (marker && mapInstance) {
      marker.setLngLat(lngLat).addTo(mapInstance);
    }
  };

  const handleMapLoaded = () => {
    setIsMapLoaded(true);
    console.log("Map has finished loading!");
  };

  return (
    <div style={{ width: "100vw", height: "100vh" }}>
      {!isMapLoaded && <div>Loading map...</div>}
      <GebetaMap
        ref={mapRef}
        apiKey={import.meta.env.VITE_GEBETA_MAPS_API_KEY}
        center={[38.7685, 9.0161]}
        zoom={15}
        onMapClick={handleMapClick}
        onMapLoaded={handleMapLoaded}
        blockInteractions={false} // Set to true to disable all interactions
      />
    </div>
  );
};

Note for TypeScript strict mode: If you're using verbatimModuleSyntax or strict TypeScript settings, you may need to import types separately:

import GebetaMap from "@gebeta/tiles";
import type { GebetaMapRef } from "@gebeta/tiles";

Advanced Features

Marker Management

You can add custom image markers, popups, and more:

// Add a custom image marker
mapRef.current?.addImageMarker(
  [38.7685, 9.0161],
  "https://cdn-icons-png.flaticon.com/512/3081/3081559.png",
  [40, 40],
  () => alert("Marker clicked!"),
  10,
  "<b>Custom Marker Popup</b>"
);

// Remove all markers
mapRef.current?.clearMarkers();

Fence Drawing

Draw fences by clicking on the map:

const handleMapClick = (lngLat: [number, number]) => {
  if (!mapRef.current) return;
  mapRef.current.addFencePoint(lngLat);
};

// Clear the current fence
mapRef.current?.clearFence();

// Get all fences
const fences = mapRef.current?.getFences();

Marker Clustering

Enable clustering for better performance with many markers:

<GebetaMap
  ref={mapRef}
  apiKey={import.meta.env.VITE_GEBETA_MAPS_API_KEY}
  center={[38.7685, 9.0161]}
  zoom={15}
  clusteringOptions={{
    enabled: true,
    maxZoom: 16,
    radius: 50
  }}
/>

Geocoding

Search for locations and get coordinates:

// Search for a location
const results = await mapRef.current?.geocode("Addis Ababa");

// Reverse geocoding
const address = await mapRef.current?.reverseGeocode(38.7685, 9.0161);

Directions

Get and display routes:

// Get directions
const route = await mapRef.current?.getDirections(
  { lat: 38.7685, lng: 9.0161 },
  { lat: 38.7595, lng: 9.0061 }
);

// Display the route
mapRef.current?.displayRoute(route);

API Reference

<GebetaMap /> Props

| Prop | Type | Description | |---------------------|----------------------------------------|---------------------------------------------| | apiKey | string | Required. Your Gebeta Maps API key. | | center | [number, number] | Initial map center [lng, lat]. | | zoom | number | Initial zoom level. | | onMapClick | (lngLat, event) => void | Callback for map click events. | | onMapLoaded | () => void | Callback when map has finished loading. | | blockInteractions | boolean | Disable all map interactions (pan, zoom, etc). | | style | React.CSSProperties | Optional. Custom styles for the container. | | clusteringOptions | ClusteringOptions | Optional. Marker clustering configuration. |

Ref Methods

Marker Management

• addMarker(options?): Returns a default marker instance (call .setLngLat and .addTo(map)).
• addImageMarker(lngLat, imageUrl, size?, onClick?, zIndex?, popupHtml?): Adds a custom image marker.
• clearMarkers(): Removes all markers from the map.
• getMarkers(): Returns all current marker instances.

Fence Management

• startFence(): Start drawing a new fence.
• addFencePoint(lngLat): Add a point to the current fence.
• closeFence(): Close the current fence.
• clearFence(): Clear the current fence.
• clearAllFences(): Clear all fences.
• getFences(): Returns all fence instances.
• getFencePoints(): Returns all fence points.
• isDrawingFence(): Returns true if currently drawing a fence.

Clustering

• addClusteredMarker(markerData): Add a marker to clustering.
• clearClusteredMarkers(): Clear all clustered markers.
• updateClustering(): Manually update clustering.
• setClusteringEnabled(enabled): Enable/disable clustering.
• setClusterImage(imageUrl): Set custom cluster image.

Geocoding

• geocode(query): Search for locations.
• reverseGeocode(lat, lng): Get address from coordinates.

Directions

• getDirections(origin, destination, options?): Get route between points.
• displayRoute(routeData, options?): Display a route on the map.
• clearRoute(): Clear the current route.
• getCurrentRoute(): Get the current route data.
• getRouteSummary(): Get route summary information.
• updateRouteStyle(style): Update route appearance.

Utility

• getMapInstance(): Returns the underlying map instance.

Types

import { GebetaMapRef, Fence, GebetaMapProps, MarkerData, FencePoint, ClusteringOptions } from '@gebeta/tiles';

For TypeScript strict mode:

import GebetaMap from '@gebeta/tiles';
import type { GebetaMapRef, Fence, GebetaMapProps, MarkerData, FencePoint, ClusteringOptions } from '@gebeta/tiles';

Examples

See the src/examples/ directory for full-featured examples:

• FenceExample.tsx - Fence drawing functionality
• CustomMarkersExample.tsx - Advanced marker management
• ClusteringExample.tsx - Marker clustering
• DirectionsExample.tsx - Routing and directions