> For the complete documentation index, see [llms.txt](https://docs.woohoo.dance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.woohoo.dance/ajax-filters/woohoo-map/leaflet-map.md).

# Leaflet map

A free, open-source alternative to Google Maps using Leaflet.js. No API key required.

**Overview**

The Leaflet Map element provides all the functionality of Woohoo Google Map without requiring a Google Maps API key. Uses OpenStreetMap tiles by default with multiple tile provider options.

**Content Settings**

**Locations:**

| Setting                       | Description                                                      |
| ----------------------------- | ---------------------------------------------------------------- |
| **Location Source**           | `Manual`, `Dynamic`, or `Dynamic-sync`                           |
| **Location Items**            | Repeater for manual locations (lat, lng, address, popup content) |
| **Post Type**                 | For dynamic mode                                                 |
| **Posts Limit**               | Maximum posts to display                                         |
| **Latitude/Longitude Fields** | ACF or meta field names                                          |
| **Address Field**             | For geocoding fallback                                           |
| **Custom Marker**             | Per-location marker image                                        |
| **Query Name**                | For dynamic-sync mode                                            |

**Clustering:**

| Setting               | Description                           |
| --------------------- | ------------------------------------- |
| **Enable Clustering** | Group nearby markers                  |
| **Cluster Radius**    | Pixels to group markers (default: 80) |
| **Medium Threshold**  | Point count for medium cluster        |
| **Large Threshold**   | Point count for large cluster         |

**Map Settings:**

| Setting                       | Description                                              |
| ----------------------------- | -------------------------------------------------------- |
| **Map Style**                 | Multiple tile providers (default, CartoDB, Stamen, etc.) |
| **Center Latitude/Longitude** | Initial map center                                       |
| **Zoom**                      | Initial zoom level (0-19)                                |
| **Fit All Markers**           | Auto-fit bounds to show all markers                      |
| **Bounds Padding**            | Padding around fitted bounds                             |
| **Max Zoom (fit bounds)**     | Prevent over-zooming when fitting                        |
| **Fit Bounds on Update**      | Re-fit when markers change                               |
| **Zoom Control**              | Show +/- buttons                                         |
| **Scroll Wheel Zoom**         | Enable mouse wheel zooming                               |

**Popup Settings:**

| Setting               | Description                |
| --------------------- | -------------------------- |
| **Show Close Button** | Display X on popups        |
| **Auto-pan to Popup** | Pan map to show full popup |

**Design Settings**

* Map size (width, height)
* Custom markers (image, active state, dimensions)
* Clustering colors (small, medium, large, text)
* Popup styling (width, background, borders, padding, typography)
* Spacing

**Tile Providers**

Multiple built-in map styles available:

* OpenStreetMap (default)
* CartoDB Positron (light)
* CartoDB Dark Matter
* Stamen Terrain
* Stamen Watercolor
* And more...

**Key Differences from Google Map**

| Feature          | Google Map           | Leaflet Map            |
| ---------------- | -------------------- | ---------------------- |
| API Key Required | Yes                  | No                     |
| Cost             | Paid after free tier | Free                   |
| Tile Provider    | Google               | OpenStreetMap + others |
| Geocoding        | Google               | Not built-in           |
| Street View      | Yes                  | No                     |

**Implementation**

```
1. Add Leaflet Map element to page
2. No API key configuration needed
3. Choose location source mode
4. Configure markers and styling
5. Works with Ajax Filter Main Query in dynamic-sync mode
```