@nur_djedd/mapbox-component

A reusable React MapBox GL component with configurable language, worldview, and style overrides. Perfect for logistics and tracking applications.

Features

• 🌍 Configurable Language - Set map labels language (default: fr)
• 🏳️ Custom Worldview - Set country worldview (default: MA for Morocco)
• 🎨 Style Override - Replace disputed territory labels (e.g., "Israel" → "Palestine")
• 🗺️ Customizable Map Style - Any MapBox style URL supported
• 📦 TypeScript Ready - Full type definitions included
• ⚡ Dynamic Loading - mapbox-gl loaded only when needed

Installation

npm install @nur_djedd/mapbox-component mapbox-gl

Quick Start

Basic Usage

import { MapView } from "@nur_djedd/mapbox-component";

function App() {
  return (
    <MapView
      accessToken={import.meta.env.VITE_MAPBOX_TOKEN}
    />
  );
}

With Custom Configuration

import { MapView } from "@nur_djedd/mapbox-component";

function App() {
  return (
    <MapView
      accessToken={import.meta.env.VITE_MAPBOX_TOKEN}
      language="fr"           // Map labels language
      worldview="MA"          // Country worldview (Morocco)
      style="mapbox://styles/mapbox/navigation-night-v1"
      center={[-1, 39]}       // Mediterranean center
      zoom={4.2}
      pitch={55}
      bearing={0}
      styleOverride={{
        replaceCountryCode: "IL",
        originalName: "Israel",
        newName: "Palestine",
      }}
    />
  );
}

With Custom Markers and Routes

import { MapView, createMarkerElement, splitRouteAtProgress } from "@nur_djedd/mapbox-component";
import type { Map as MapboxMap } from "mapbox-gl";

function TrackingMap({ dossiers, selectedId, onSelectDossier }) {
  const handleMapInit = (map: MapboxMap) => {
    dossiers.forEach((dossier) => {
      const { completed, remaining } = splitRouteAtProgress(
        dossier.route,
        dossier.progress
      );

      // Add route line
      map.addSource(`route-${dossier.id}`, {
        type: "geojson",
        data: {
          type: "Feature",
          geometry: { type: "LineString", coordinates: completed },
        },
      });
      map.addLayer({
        id: `route-${dossier.id}`,
        type: "line",
        source: `route-${dossier.id}`,
        paint: { "line-color": "#3b82f6", "line-width": 2 },
      });

      // Add custom marker
      const color = dossier.alertes.length > 0 ? "#dc2626" : "#059669";
      const { element } = createMarkerElement(color, {
        hasAlert: dossier.alertes.length > 0,
        onClick: () => onSelectDossier(dossier.id),
      });

      new mapboxgl.Marker({ element, anchor: "center" })
        .setLngLat(dossier.positionActuelle)
        .addTo(map);
    });
  };

  return (
    <MapView
      accessToken={import.meta.env.VITE_MAPBOX_TOKEN}
      onMapInit={handleMapInit}
      className="h-screen w-full"
    />
  );
}

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | accessToken | string | required | MapBox access token | | style | string | "mapbox://styles/mapbox/navigation-night-v1" | Map style URL | | center | [number, number] | [-1, 39] | Initial center coordinates [lng, lat] | | zoom | number | 4.2 | Initial zoom level | | pitch | number | 55 | Initial pitch (tilt) | | bearing | number | 0 | Initial bearing (rotation) | | language | string | "fr" | Map labels language | | worldview | string | "MA" | Country worldview code | | styleOverride | MapStyleOverride | undefined | Label override for disputed territories | | className | string | "" | CSS class for container | | loadingText | string | "Chargement de la carte..." | Loading state text | | onMapLoaded | (map) => void | undefined | Callback when map is loaded | | onMapInit | (map) => void | undefined | Callback for map customization |

MapStyleOverride Type

interface MapStyleOverride {
  /** Country code to replace (e.g., "IL" for Israel) */
  replaceCountryCode: string;
  /** Original country name to detect (e.g., "Israel") */
  originalName: string;
  /** New label to display (e.g., "Palestine") */
  newName: string;
}

Utilities

createMarkerElement

Creates a styled marker element with hover and click handlers.

function createMarkerElement(
  color: string,
  options?: {
    size?: number;
    borderSize?: number;
    hasAlert?: boolean;
    onClick?: () => void;
    onMouseEnter?: () => void;
    onMouseLeave?: () => void;
  }
): { element: HTMLElement; update: (selected: boolean) => void }

splitRouteAtProgress

Splits a route at a given progress percentage.

function splitRouteAtProgress(
  route: [number, number][],
  progress: number // 0 to 1
): { completed: [number, number][]; remaining: [number, number][] }

pointAlongRoute

Gets a coordinate point along a route at a given progress.

function pointAlongRoute(
  route: [number, number][],
  progress: number
): [number, number]

Environment Variables

Add your MapBox token to your .env file:

VITE_MAPBOX_TOKEN=pk.your_token_here

Common Map Styles

// Night navigation
"mapbox://styles/mapbox/navigation-night-v1"

// Day navigation
"mapbox://styles/mapbox/navigation-day-v1"

// Streets
"mapbox://styles/mapbox/streets-v12"

// Satellite
"mapbox://styles/mapbox/satellite-v9"

// Satellite Streets
"mapbox://styles/mapbox/satellite-streets-v12"

// Dark
"mapbox://styles/mapbox/dark-v11"

// Light
"mapbox://styles/mapbox/light-v11"

License

MIT