How to Build Custom Markers and a Dynamic Info Box for WordPress Maps

What the Client Wanted: Clickable Locations with Rich Information

From a Simple Pin to a Fully Interactive Info Box

The default Leaflet marker is a blue teardrop icon that opens a small popup when clicked. For a content-rich map — one where each location has a name, description, image, and link — that popup is insufficient. It cannot display an image, cannot be styled to match the site’s design, and cannot accommodate a call-to-action button without significant workarounds.

The Design Reference That Guided the Implementation

The client provided a design mockup showing the info box as a panel overlaid on the bottom-left of the map, with a close button, a category icon in the header, a title, a description block, an image, and a CTA link in the footer. Translating this into HTML, CSS, and JavaScript — and making it work with Leaflet’s event system — was the core implementation challenge.

Building Custom Markers with Leaflet.js

Using L.icon for Custom Marker Images

Leaflet’s L.icon method creates a custom icon from an image URL. It accepts iconSize, iconAnchor, and popupAnchor parameters. The iconAnchor values require careful calibration — always test at multiple zoom levels.

Integrating WP Media Library for Per-Location Marker Uploads

Allowing content editors to upload a custom marker icon per location requires integrating the WordPress Media Library into the location metabox. The recommended icon size for custom markers is 40x40px or smaller to avoid overlapping neighboring locations at lower zoom levels.

Fallback to Default Marker When None Is Set

The marker rendering function should check whether a custom icon URL exists and fall back to the plugin’s default marker if it does not. This prevents broken image references and maintains visual consistency across locations that have not been individually configured.

Building a Dynamic Info Box

Info Box Structure: Title, Description, Image, CTA Link

The info box is a fixed HTML element that exists in the DOM from page load but is hidden until a location is selected. When a marker or polygon is clicked, JavaScript populates the info box fields with the location’s data and makes it visible via a CSS class toggle.

Showing Category Icon in the Info Box Header

When a location is selected, look up the location’s category ID in the category data object to retrieve the icon URL. This lookup happens entirely in JavaScript — no additional server requests are needed because all category data is already included in the initial map data payload.

Opening and Closing the Info Box on Marker Click

Attach the click handler to each marker during the location rendering loop. Use a CSS class toggle to show and hide the panel rather than JavaScript style manipulation — this makes the behavior controllable via CSS transitions.

Handling Polygon Clicks

Attaching Click Events to GeoJSON Polygon Layers

Leaflet’s L.geoJSON method accepts an onEachFeature callback. Use this to attach a click event to each polygon layer that calls the same showInfoBox function used for markers, ensuring consistent behavior regardless of which element the user clicks.

Reusing the Same Info Box for Both Markers and Polygons

A single info box component that is populated by both marker clicks and polygon clicks keeps the codebase simple and the user experience consistent. The info box function does not need to know whether it was triggered by a marker or a polygon.

Common Pitfalls with Markers and Info Boxes

Info Box Not Responsive on Mobile

An info box that overlays the map on desktop becomes a problem on mobile, where it may cover the entire map area. Position the info box below the map container on small screens using CSS media queries so the map remains fully visible when a location is selected.

Z-Index Conflicts with Other Page Elements

Leaflet assigns z-index values to its internal layers and controls. A fixed or absolute info box panel may render behind Leaflet’s tile layers if its z-index is not set explicitly. Set it higher than Leaflet’s control pane (z-index 800).

Summary and What Comes Next

Custom markers and a dynamic info box are what transform a data display into an interactive experience. Use L.icon for custom marker images, integrate WP Media Library for per-location uploads, and build a persistent info box panel. Attach click handlers to both markers and polygons to trigger the same info box function.

With individual location interactivity in place, the next step is adding navigation tools for maps with many locations. The next article covers category filter buttons and a dropdown that lets users jump to a specific location.