🏷️ Label Markers - GEO Map Hub Plugin

This guide explains how to add label markers to your SVG map. Label markers display icons, shapes, or custom images with tooltips and optional labels below, positioned precisely using coordinates.

📘 What is a Label Marker?

A Label Marker is a type of map marker that combines a symbol (like a circle, square, or image) with a text label beneath or beside it. This allows you to visually mark a point on the map and describe it using readable text.

💡 Use Case

Use Label Markers when you want to:

• ✈️ Mark airports, landmarks, or tourist spots with icons and names

• 📍 Highlight cities, towns, or capitals

• 📊 Display key data points with labels (e.g., top producers, weather stations)

• 🧭 Help users locate items quickly via icon + label combo

📁 Folder Structure

Make sure the following files are correctly placed:

your-project/
├── gmh-plugin/
│    ├── assets/
│    │    ├── css/
│    │    │    └── style.css
│    │    ├── js/
│    │    │    └── script/
│    │    │    │    ├── geomaphub.js
│    │    │    │    └── lib/
│    │    │    │    │   ├── labels-below-marker-automatically-gmh.js       ← Required
│    │    │    │    │   └── interactive-tooltip-gmh.js  ← Required for interactive (tooltips and links.)
│    ├── data/
│    │    ├── us/
│    │    │    ├── map-content.js
│    │    │    └── us.svg
│ index.html

✅ Configuration Breakdown

🔹 map_config

export const map_config = [
  {
    "targetClass": "US-WA",  // Unique identifier for region.
    "name": "Washington",  // Display name for the region.

    /**
     * Marker Configuration
     *
     * This section defines different types of markers that can be added to the map.
     * Each marker type has its own structure and properties, allowing customization for
     * specific use cases such as displaying images, labels, vectors, or color markers.
     *
     * Supported Marker Types:
     * - label_marker: Markers with text labels.
    */
    "markers": [
      {
        "targetClass": "MARKER-US-WA-1",  // Unique identifier for this marker.

        /*
         * Label Marker Configuration
         * Defines label markers that can be displayed on the map with customizable positioning, shapes, tooltips, and labels.
        */
        "label_marker": [
          {
            "targetClass": "LM-US-WA-1", // Unique identifier for the label marker

            /*
             * Shape of the Label Marker
             * Defines the marker's visual style (e.g., "rounded", "cubic").
             * If using a custom marker (e.g., an image), leave this empty.
            */
            "shape": "", // Example: "rounded" or "cubic"

            /*
             * Custom Marker Source
             * If using a custom SVG or image as the marker, specify the file path here.
            */
            "src": "assets/images/icons/airplane.svg", // Path to the custom marker

            "tooltip": "Washington", // Tooltip text displayed when hovering over the marker

            /*
             * Positioning Properties
             * Specifies the coordinates (x, y) for placing the marker on the map.
            */
              "position": {
              "x": 110, // X-coordinate for the marker's position
              "y": 50   // Y-coordinate for the marker's position
            },

            "on_click": {
              "url": "https://en.wikipedia.org/wiki/Washington",
              "target": "_blank",
              "cursor": "pointer"
            },

            /*
             * Size Properties
             * Defines the marker's dimensions. Use "radius" for rounded shapes, and "width" and "height" for custom shapes.
            */
            "size": {
              "radius": 7, // Radius for rounded markers
              "width": 12, // Width for cubic or custom markers
              "height": 12 // Height for cubic or custom markers
            },

            /*
             * Color Properties
             * Configures the marker's default, hover, and active states.
            */
            "color": {
              "default": "#ec962a", // Default marker color
              "on_hover": "#005999" // Marker color on hover
            },

            /*
             * Stroke (Border) Properties
             * Defines the border color and width for the marker.
            */
            "stroke": {
              "color": "white", // Border color
              "width": "1px"    // Border width
            },

            /*
             * Label Configuration
             * Defines the label text, positioning, and font styling associated with the marker.
            */
            "label": {
              "text": "Washington", // Text displayed as the label

              /*
               * Positioning for the Label
               * Specifies the label's position relative to the marker.
              */
              "position": {
                "x": 0, // X-coordinate for label placement
                "y": 0  // Y-coordinate for label placement
              },

              /*
               * Adjustments for Fine-Tuning
               * Allows manual offsets for precise label placement.
              */
              "adjustments": {
                "x": 4, // Horizontal adjustment
                "y": 18  // Vertical adjustment
              },

              /*
               * Font Styling for the Label
               * Configures the font size, color, and weight for the label text.
              */
              "font": {
                "size": "7px",      // Font size for the label text
                "color": "black",   // Font color for the label text
                "weight": "normal"  // Font weight for the label text
              }
            }
          },
        ],
      }
    ],
  },
];

🔹 general_config

export const general_config = {
  "id": {
    /*
     * SVG and Element IDs
     * These IDs are used to reference specific SVG elements or HTML
     * elements in your configuration. If you want to change any of
     * these IDs, ensure you update them in the corresponding svg.js file.
    */
    "svg_id": "US-MAP-GMH",  /** ID for the main SVG map element. */
    "tooltip_id": "tooltip-gmh",  /** ID for the tooltip element. */
    "custom_tooltip_id": "custom-tooltip-gmh",  /** ID for the tooltip element. */
    "marker_id": "US-MARKER-GMH",  /** ID for the marker element. */
  },

  /*
   * Label Marker Configuration
   * This section defines the configuration for label markers on the map,
   * including color and stroke settings for the label marker elements.
  */
  "label_marker": {
    /*
     * Map Color Settings
     * These define the default and hover colors for the label markers on the map.
    */
    "color": {
      "default": "#f3faff",  /** Default color for the label marker. */
      "on_hover": "#005999"   /** Color when the label marker is hovered over. */
    },

    /*
     * Stroke Settings
     * These define the border (stroke) properties for the label marker,
     * including the color and width of the border.
    */
    "stroke": {
      "color": "#6B8B9E",  /** Border color for the label marker. */
      "width": "0.8px"     /** Border width for the label marker. */
    },
  },
}

✅🛠️ Initialization Script

<!-- Labels below markers automatically -->
<script type="module">
  const currentCountry = "us";

  async function initMap() {
    try {
      // Dynamically import map-specific data
      const {map_config, general_config} = await import(`/gmh-plugin/data/${currentCountry}/map-content.js`);
      const {GEOMapHub} = await import('/gmh-plugin/assets/js/script/geomaphub.js');
      const {geoMapHubLabelsBelowMarker} = await import('/gmh-plugin/assets/js/script/lib/labels-below-marker-automatically-gmh.js');
      const {geoMapHubInteractiveTooltip} = await import('/gmh-plugin/assets/js/script/lib/interactive-tooltip-gmh.js');

      const map = new GEOMapHub("#svg-wrapper-gmh", {
        svgUrl: `/gmh-plugin/data/${currentCountry}/${currentCountry}.svg`,
        mapConfig: map_config,
        generalConfig: general_config,
      });

      map.registerPlugin(geoMapHubLabelsBelowMarker);
      map.registerPlugin(geoMapHubInteractiveTooltip);

      map.init();
    } catch (error) {
      console.error("Error initializing map:", error);
    }
  }

  initMap();
</script>
<!-- Labels below markers automatically -->

Here's a working example to display the map

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>GEO Map Hub – Label Marker</title>
  <link rel="stylesheet" href="/gmh-plugin/assets/css/style.css" />
</head>

<body>
  <div id="tooltip-gmh"></div>
  <div id="custom-tooltip-gmh"></div>

  <div class="row row-gap-2">
    <div class="col-lg-12 col-12">
      <div class="svg-container-gmh">
        <div id="svg-wrapper-gmh"></div>
      </div>
    </div>
  </div>

  <!-- Labels below markers automatically -->
  <script type="module">
    const currentCountry = "us";

    async function initMap() {
      try {
        // Dynamically import map-specific data
        const {map_config, general_config} = await import(`/gmh-plugin/data/${currentCountry}/map-content.js`);
        const {GEOMapHub} = await import('/gmh-plugin/assets/js/script/geomaphub.js');
        const {geoMapHubLabelsBelowMarker} = await import('/gmh-plugin/assets/js/script/lib/labels-below-marker-automatically-gmh.js');
        const {geoMapHubInteractiveTooltip} = await import('/gmh-plugin/assets/js/script/lib/interactive-tooltip-gmh.js');

        const map = new GEOMapHub("#svg-wrapper-gmh", {
          svgUrl: `/gmh-plugin/data/${currentCountry}/${currentCountry}.svg`,
          mapConfig: map_config,
          generalConfig: general_config,
        });

        map.registerPlugin(geoMapHubLabelsBelowMarker);
        map.registerPlugin(geoMapHubInteractiveTooltip);

        map.init();
      } catch (error) {
        console.error("Error initializing map:", error);
      }
    }

    initMap();
  </script>
  <!-- Labels below markers automatically -->
</body>

</html>

⚠️ Local CORS Warning

If you're testing with a .html file locally and see this error:

Access to script at 'file:///...' from origin 'null' has been blocked by CORS policy...

It means you're loading the file using the file:// protocol.

✅ How to Fix

Option 1: Use a Local Server (Recommended for HTML)

• Live Server (VS Code Extension)

  Install Live Server, right-click your HTML, and choose “Open with Live Server”.

• Or use any other local server:

  # Python 3
  python -m http.server
  
  # Node.js
  npx http-server
  
  # PHP
  php -S localhost:8080
  

• Or use a local web server (e.g., XAMPP or Laragon)

Option 2: Deploy to a Real Server

You can upload your files to:

• Your cPanel or shared hosting

• A staging VPS or domain

Once the files are accessible via http:// or https://, the plugin works without issues.

🎯 Output Behavior

✅ Custom image or shape marker appears at x, y on the map

✅ Tooltip appears on hover

✅ Clickable link optional

✅ Label text auto-positioned with adjustments

✅ Consistent styling through general_config