@johnson361/advanced-label-marker

The Modern, Drift-Free Successor to markerwithlabel

AdvancedLabelMarker is a high-performance Google Maps overlay engineered to eliminate the "floating" or "sliding" effect (drift) often seen in custom HTML labels. It is built specifically to address the February 2024 deprecation of google.maps.Marker.

📍 Advanced Label Marker

A powerful and customizable label marker for the Google Maps JavaScript API.

🌟 Interactive Documentation Hub

Why read when you can experiment? Our Live Demo Suite allows you to see the library in action with real-world scenarios.

✨ Features

• Zero Zoom Drift Pixel-perfect synchronization during zoom and pan.

• Custom HTML Labels Full control over label DOM and CSS.

• Custom HTML Icons Use <div> or <img> elements as marker icons.

• Drag & Drop Support Built-in synchronization for draggable markers and labels.

• Event Forwarding Native-like click, drag, dragstart, and dragend events.

• Clustering Ready Compatible with MarkerClustererPlus and other clusterers.

• Dynamic Updates Change content, styles, or visibility on the fly.

• Legacy-Friendly API Modern internals with a familiar API for easy migration.

🚀 Why This Module?

1. Fixes the Deprecation Warning

If you see the console error: As of February 21st, 2024, google.maps.Marker is deprecated. Please use AdvancedMarkerElement instead. This library is your solution. It bridges the gap between the new AdvancedMarkerElement and custom HTML overlays.

2. Zero Zoom Drift (Pixel-Perfect)

Legacy libraries like markerwithlabel rely on events that fire after a zoom, causing labels to "drift" away from their pins. This module hooks into the map's internal render loop via OverlayView, ensuring the label and marker stay mathematically locked together during transitions.

3. Modern Tech Stack

• Supports Google Maps JS API v3.56+.
• Uses WebGL-optimized markers.
• Fully compatible with modern bundlers (Vite, Webpack, ES Modules).

📦 Installation

Requirements

This library requires the Google Maps JavaScript API.

🚀 Quick Start

1. Install the package via npm:

npm install @johnson361/advanced-label-marker

2. Include the Google Maps Script Add this to your index.html. Replace YOUR_API_KEY with your actual key.

<script
  src="[https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=weekly](https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&v=weekly)"
  defer
></script>```

3. Initialize the Marker


```JavaScript
import { AdvancedLabelMarker } from '@johnson361/advanced-label-marker';

const marker = new AdvancedLabelMarker({
  map,
  position: { lat: 37.422, lng: -122.084 },
  label: 'Hello World!',
});```