🏷️ Text Labels - GEO Map Hub Plugin

This guide explains how to display custom text labels on your SVG map using the GEO Map Hub plugin. These labels can have tooltips, different font styles, hover effects, and even links.

✨ What is a text_label?

A text_label lets you display text-based labels directly over regions (like state names) with:

• Custom text, color, and hover styles
• Adjustable X/Y positioning
• tooltips
• Optional clickable links
• Font customization

Ideal for naming regions, city overlays, or map-based dashboards.

📁 Folder Structure

Make sure your files are structured like this:

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

✏️ Step-by-Step Integration

1. Add Text Label to Config

Inside /gmh-plugin/data/us/map-content.js, define the label under the desired region:

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

    /*
     * Text Label Configuration
     * This section defines the properties for displaying a text label on the map.
     * The label includes customizable text, tooltip, position, and font styling.
    */
    "text_label": {
      "text": "Washington", // The text displayed as the label
      "tooltip": "Washington", // Tooltip text displayed on hover

      // Position of the label relative to the map
      "position": {
        "x": 94, // Horizontal position
        "y": 70, // Vertical position
      },

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

      // Font styling for the text label
      "font": {
        "size": "7px",      // Font size for the label text
        "color": "black",   // Font color
        "hover_color": "white",
        "weight": "normal"  // Font weight (e.g., "normal", "bold", "lighter")
      }
    },
  },
]

💡 You can repeat this for multiple regions (e.g., "US-AL", "US-NY", etc.).

2. Define general_config

Also add these configuration in the same file:

/*
 * General Configuration
 * This section contains global settings for the map, including
 * IDs for various elements like markers, lines, and tooltips.
 */
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. */

      /*
       * Text Label Configuration
       * This section defines the ID for the text label displayed on the map.
      */
      "text_label": {
          "id": "US-TEXT-LABEL-GMH"  /** ID for the text label element. */
      },
  },

  /*
   * Text Label Configuration
   * This section defines the settings for the text label on the map, including
   * color and stroke settings for the label.
  */
  "text_label": {
    "map": {
      /*
       * Text Color Settings
       * These define the color for the text label on the map, including
       * the default color and hover color.
      */
      "color": {
        "default": "#f3faff",  /** Default color for the text label. */
        "on_hover": "#005999",  /** Color when the text label is hovered over. */
      },

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

3. Create HTML and Script to Load Map

Here's a working example to display the map with the text labels:

<!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 – Text Labels</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="svg-container-gmh">
    <div id="svg-wrapper-gmh"></div>
  </div>

  <script type="module">
    const currentCountry = "us";

    async function initMap() {
      try {
        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 {geoMapHubTextLabel} = await import('/assets/js/script/lib/text-labels-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(geoMapHubTextLabel);
        map.registerPlugin(geoMapHubInteractiveTooltip);

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

    initMap();
  </script>
</body>
</html>

🎨 Text Label Configuration Reference

⚙️ General Configuration Options general_config

The general_config object defines global settings for your map - especially for identifying important SVG elements and applying consistent styling across all labels.

🔑 ID Settings

These define the IDs used inside your .svg or generated DOM elements. It's crucial they match what's used in your actual SVG and plugin setup.

/*
 * General Configuration
 * This section contains global settings for the map, including
 * IDs for various elements like markers, lines, and tooltips.
 */
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. */

  /*
   * Text Label Configuration
   * This section defines the ID for the text label displayed on the map.
  */
  "text_label": {
      "id": "US-TEXT-LABEL-GMH"  /** ID for the text label element. */
    },
  },
}

✅ Make sure your SVG has id="US-MAP-GMH" or match it accordingly.

🎨 Text Label Styling Defaults

These control how all labels look by default. You can override them per region if needed.

/*
 * Text Label Configuration
 * This section defines the settings for the text label on the map, including
 * color and stroke settings for the label.
*/
"text_label": {
  "map": {
    /*
     * Text Color Settings
     * These define the color for the text label on the map, including
     * the default color and hover color.
    */
    "color": {
      "default": "#f3faff",  /** Default color for the text label. */
      "on_hover": "#005999",  /** Color when the text label is hovered over. */
    },

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

⚠️ Local Dev (CORS Note)

If loading via file://, you'll hit this error:

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

✅ 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”.
• 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.

🧪 Checklist