Leaflet.js in WordPress: Why We Chose It Over Google Maps for a University Campus Project

The Client Problem: A Map That Needed to Live Everywhere

Multiple Websites, One Backend, Zero Google API Budget

The project started with a straightforward brief: build a map for a university client that shows campus buildings and points of interest. Simple enough — until the requirements expanded. The map needed to be managed from one place but displayed on multiple websites. One of those websites was not even running WordPress. And there was no budget for ongoing API costs.

That last constraint was the decisive one. Google Maps API pricing is based on map loads, and for an institution with multiple websites each potentially serving thousands of visitors, the monthly cost was not justifiable — especially when the map’s function was purely informational with no need for routing or Places API features.

Why Google Maps Was Ruled Out Early

Beyond cost, Google Maps presented two other problems. First, it requires an API key that must be configured and secured on every site where the map appears. For a map embedded across multiple domains, this creates a management overhead that grows with each new deployment. Second, Google Maps styling is limited — you can change colors with JSON style arrays, but you cannot achieve the clean, minimal aesthetic the client wanted without significant workarounds.

Leaflet.js with a CartoDB tile layer solved all three problems at once: no API key, no cost, and a clean light-gray map style that matched the client’s design without any custom configuration.

What Is Leaflet.js and Why It Works Well in WordPress

Lightweight, Open-Source, and API-Key Free

Leaflet.js is an open-source JavaScript library for interactive maps. It weighs around 42KB gzipped — a fraction of the Google Maps SDK — and handles everything you need for a content-focused map: markers, polygons, popups, zoom controls, and tile layer rendering. There is no registration required, no API key, and no usage limits imposed by the library itself.

How Leaflet Compares to Google Maps for Custom Projects

Google Maps wins when you need routing, Street View, real-time traffic, or deep integration with Google’s Places database. For everything else — custom markers, polygon overlays, category filtering, custom styling, and embedding across multiple sites — Leaflet is more flexible, more lightweight, and significantly cheaper to operate.

How to Properly Enqueue Leaflet in WordPress

Adding Leaflet CSS and JS via wp_enqueue_scripts

The correct way to load Leaflet in WordPress is via the wp_enqueue_scripts hook. Never add Leaflet directly to a theme’s header template — using the enqueue system ensures proper dependency management and prevents duplicate loading.

add_action( 'wp_enqueue_scripts', 'my_map_enqueue_assets' );

function my_map_enqueue_assets() {
    wp_enqueue_style(
        'leaflet-css',
        'https://unpkg.com/leaflet@1.9.4/dist/leaflet.css'
    );

    wp_enqueue_script(
        'leaflet-js',
        'https://unpkg.com/leaflet@1.9.4/dist/leaflet.js',
        [],
        null,
        true
    );
}

Loading Assets Only Where Needed

Loading Leaflet on every page of a website is wasteful and can affect Core Web Vitals scores on pages that have no map. The correct approach is to enqueue assets conditionally — only on pages or post types that actually display a map.

Understanding Tile Layers

OpenStreetMap vs CartoDB vs Custom Tiles

A tile layer is the background map imagery that Leaflet loads in square tiles as the user pans and zooms. For the university project, we used CartoDB’s light_all tile layer, which renders in soft gray tones that allow colored polygon overlays to stand out clearly.

L.tileLayer(
    'https://{s}.basemaps.cartocdn.com/rastertiles/light_all/{z}/{x}/{y}.png',
    {
        maxZoom: 20,
        attribution: '© OpenStreetMap contributors'
    }
).addTo(map);

Which Tile Layer to Choose and Why

Use OpenStreetMap tiles for development and low-traffic projects where detailed map data is important. Use CartoDB for production projects where visual cleanliness matters more than map detail. If your project has high traffic or commercial requirements, consider self-hosting tiles or using a paid tile service like Mapbox.

Common Pitfalls When Using Leaflet in WordPress

Asset Conflicts with Other Plugins or Themes

One of the most common problems when using Leaflet in WordPress is a conflict with another plugin or theme that also loads Leaflet — often a different version. When two versions of Leaflet are loaded on the same page, the second one overwrites the global L object, breaking whichever map initialized first.

Map Not Rendering Due to Container Height Issues

Leaflet requires its container element to have an explicit height set via CSS. If the container height is zero or undefined — which happens when height is set to 100% without a parent height defined — the map will initialize but render as a blank area. Always set a fixed pixel height directly to the map container element.

Summary and What Comes Next

Leaflet.js is the right foundation for a custom WordPress map plugin when cost, flexibility, and cross-site embedding are priorities. It is lightweight, well-documented, and supported by a rich ecosystem of plugins. Enqueue it via wp_enqueue_scripts, load it in the footer, and choose your tile layer based on your project’s visual requirements.

With Leaflet in place, the next step is designing the data structure that will store your maps and locations. The next article covers how to use Custom Post Types and meta fields to build a location data architecture that scales cleanly from one map to many.