> For the complete documentation index, see [llms.txt](https://wpmaps-docs.mapster.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wpmaps-docs.mapster.me/mapster-wp-maps-v2/the-mapmaker/popups.md).

# Popups

Popups are information panels that appear when a user interacts with a feature on your map. The system has two parts that work together:

* **Popup Templates** — reusable design layouts you create once and assign to features. These control the visual structure (colors, layout, which elements appear).
* **Popup Content** — the actual text, images, and settings you enter per feature.

## Enabling a Popup

Select any feature in the Mapmaker. In the right panel, open the **Interactivity** section. Turn on **Popup Enabled** to activate the popup for that feature.

Once enabled, choose how it opens:

* **Open on Click** — the popup appears when the user clicks the feature
* **Open on Hover** — the popup appears when the cursor moves over the feature. You can also enable **Keep popup open when hovering** to prevent it from closing when the cursor moves away.

### Direct Link Instead of Popup

If you'd rather have a click on the feature navigate directly to a URL instead of opening a popup, enable **Link on Marker Click** and enter the destination URL. You can choose whether it opens in the same tab or a new one.

## Setting Popup Content

With the popup enabled, an additional **Popup** section appears in the right panel. This is where you set the content for this specific feature.

### Design

Click **Select Design** to choose a Popup Template. A modal will open showing previews of all your existing templates — click **Use Popup Template** to apply one, or click **Add New** to create a new template (this opens the Popup Templates editor in a new tab).

> **Note:** A popup must have a template selected to display. If no template is selected, the popup won't appear even when enabled.

### Content Fields

* **Header Text** — the popup's title. Appears in whatever position the template designates for a header.
* **Body** — a rich text / HTML editor for the main popup content. Supports full HTML.
* **Button Text** — the label for the popup's call-to-action button.
* **Render Shortcodes** <sup>Pro</sup> — when enabled, WordPress shortcodes in the body content will be processed server-side and rendered. This may slightly increase load time.

### Media

Switch between **Featured Image** and **Gallery** tabs to add images to the popup. Featured Image is a single image; Gallery is a set of images displayed as a carousel.

### Dynamic Content <sup>Pro</sup>

You can use feature property values in your popup text using curly brace syntax. This works in the Header, Body, and Button Text fields.

For properties created using the built-in meta field creator, use curly brace syntax as follows:

```
This location's category is {category}.
The elevation is {elevation} meters.
```

The property name inside the braces must match a custom property on the feature. Properties are visible and editable on any feature in the classic editor under "Custom Properties".

If you use ACF to manage your custom fields, you can use a special syntax for ACF using the field ID shown in ACF.

```
This location's category is {acf.field_randomstring}.
The elevation is {acf.field_name} meters.
```

You can find these field IDs in your ACF interface as below.

<figure><img src="/files/KDbD5Ca1iAVFLmbx3AJb" alt=""><figcaption></figcaption></figure>

## Popup Options

In the bottom section of the Popup panel:

* **Open on Load** — the popup opens automatically when the page loads, without the user needing to click. Useful for drawing attention to a featured location.
* **Always Open** <sup>Pro</sup> — when combined with Open on Load, keeps the popup permanently visible. It cannot be closed by the user.

**Button Click** — controls what happens when the button in the popup is pressed:

* **To Feature Post** — navigates to the feature's WordPress post page
* **To URL** — navigates to a custom URL you specify
* **Open modal** <sup>Pro</sup> — opens a larger modal overlay with additional content (see below)
* **Open Google Directions** — opens Google Maps directions to the feature's coordinates
* **Do nothing** — the button appears but takes no action (useful for display-only purposes)

For To Feature Post, To URL, and Open Google Directions, you can enable **Open in New Tab**.

### Modal Content <sup>Pro</sup>

If you choose **Open modal** for the button action, a WYSIWYG editor appears where you can enter the modal's content. This is a good place for additional detail, images, or embedded shortcodes that won't fit neatly in the popup itself.

## Sidebar Display

If you've enabled **Show popups in sidebar** in [Map Settings → Interactivity](/mapster-wp-maps-v2/the-mapmaker/map-settings.md#interactivity), popup content will appear in a sidebar panel beside the map rather than floating over it. All the content and options above work the same way.

## Popup Templates

Popup Templates are created and managed as their own post type in WordPress, under **Maps > Popup Templates** in your admin menu. Each template defines the visual layout — which elements appear, in what order, and how they're styled.

You can create a new template from the Popup Templates list, or jump directly from the **Select Design** modal inside the Mapmaker. The plugin comes with several ready-made templates to get you started.

<figure><img src="/files/67HW0eqJ83rOwTdMCKZN" alt=""><figcaption></figcaption></figure>

For full details on building and customizing popup templates, see the [Popup Templates documentation](https://github.com/mapstertech/mapster-wp-maps-docs/tree/main/v1/popups/popup-templates/introduction.md).

> **Note:** Popup template creation and editing is currently managed outside the Mapmaker, in the classic WordPress editor. This is being updated — a native template editor inside the Mapmaker is planned for a future release.