Leaflet Hero Marker

A highly customizable, lightweight Leaflet marker and icon plugin that supports custom SVG shapes, gradient colors, image icons, text badges, inline SVG/Heroicons, drop shadows, and various built-in CSS animations.

It automatically calculates matching outline/gradient colors and comes with built-in TypeScript definitions.

Features

• Custom Styling: Control primary colors, outline widths, and text colors. Colors automatically generate a subtle matching gradient using @ctrl/tinycolor.
• Text & Badge Support: Display letters or numbers directly inside the pin with auto-scaling font size based on character length.
• Heroicon / SVG Integration: Insert custom SVG icon strings (such as those from Heroicons) directly into the pin container.
• Built-in Animations: Apply smooth CSS-based animations (spin, bounce, shake, beat, drop, pulse, radar).
• Image Fallback: Render an external image URL instead of the default SVG marker, while preserving the animations and drop shadows.
• TypeScript Support: Fully typed, including extension of Leaflet’s global L namespace.

Installation

Install the package alongside its peer dependencies:

npm install leaflet-hero-marker

Make sure you also have leaflet installed in your project:

npm install leaflet
npm install --save-dev @types/leaflet

Quick Start

ESM / TypeScript

import L from 'leaflet';
import 'leaflet/dist/leaflet.css';
import { heroMarker, heroIcon } from 'leaflet-hero-marker';

// Initialize map
const map = L.map('map').setView([51.505, -0.09], 13);
L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png').addTo(map);

// 1. Simple marker with a text badge and bounce animation
heroMarker([51.505, -0.09], {
    color: '#ff4757',
    text: 'A1',
    animation: 'bounce',
}).addTo(map);

// 2. Marker using an SVG icon (e.g. Heroicons) inside the pin
const homeIconSvg = `<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" style="width: 100%; height: 100%;"><path stroke-linecap="round" stroke-linejoin="round" d="M2.25 12l8.954-8.955c.44-.439 1.152-.439 1.591 0L21.75 12M4.5 9.75v10.125c0 .621.504 1.125 1.125 1.125H9.75v-4.875c0-.621.504-1.125 1.125-1.125h2.25c.621 0 1.125.504 1.125 1.125V21h4.125c.621 0 1.125-.504 1.125-1.125V9.75M8.25 21h8.25" /></svg>`;

heroMarker([51.51, -0.09], {
    color: '#2ed573',
    heroicon: homeIconSvg,
    animation: 'pulse',
    animationColor: '#2ed573'
}).addTo(map);

// 3. Marker using an external image URL with a drop shadow
heroMarker([51.515, -0.09], {
    url: 'https://example.com/marker-image.png',
    showShadow: true,
    animation: 'radar'
}).addTo(map);

Global / UMD Usage (Browser)

If you load the library via a <script> tag, the classes and helper functions are automatically registered on the global L object.

<script src="path/to/leaflet.js"></script>
<script src="path/to/leaflet-hero-marker.js"></script>
<script>
  const marker = L.heroMarker([51.505, -0.09], {
      color: '#2b7fff',
      text: '1',
      animation: 'beat'
  }).addTo(map);
</script>

Configuration Options

HeroMarker options extend all standard Leaflet Marker Options, omitting the icon field. HeroIcon options extend Leaflet DivIcon Options.

Custom Properties

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | color | string | '#2b7fff' | The primary base color of the marker pin. | | url | string \| null | null | A URL to an image file. If provided, the standard SVG pin shape is ignored, and the image is used instead. | | heroicon | string \| null | null | Inline SVG structure or raw HTML. Rendered inside the center of the marker using a <foreignObject> wrapper. | | text | string \| number \| null | null | Plain text or numeric label. Text size scales automatically to fit within the marker. | | textColor | string | '#ffffff' | Color of the badge text. | | iconColor | string | '#ffffff' | Color of the default central dot or custom SVG icon (heroicon). | | outlineColor | string \| null | null | Color of the marker border. Defaults to a shade 15% darker than color. | | outlineWidth | number | 1 | Border stroke width of the marker. | | showShadow | boolean | true | Renders a perspective, blurred drop shadow beneath the pin. | | animation | string \| false \| null | null | The name of the CSS animation. Choose from: 'spin', 'bounce', 'shake', 'beat', 'drop', 'pulse', 'radar'. | | animationColor | string \| null | null | Base color used for ring animations (e.g., 'pulse' and 'radar'). Defaults to color. | | animationDuration | string \| number \| null | null | Duration of the CSS animation. Can be a string with units (e.g. '1.5s', '800ms') or a positive number representing seconds. |

Animations Overview

• spin: Continuously spins the interior icon (or image) 360 degrees.
• bounce: Smooth up-and-down motion. The bottom shadow scales dynamically in unison.
• shake: Alternating left-and-right rotation from the anchor point. Shadow skews dynamically.
• beat: Pumping heartbeat/pulse scale-up effect.
• drop: A drop-in entry animation (does not loop; uses forwards fill-mode).
• pulse: Generates a continuous expanding circle fading outwards from the bottom anchor of the pin.
• radar: Similar to pulse, but originates from the center of the pin, projecting circular wave ripples.

License

This project is licensed under the MIT License. See the LICENSE file for details.