---
title: "How popups work in MangoMap"
description: "The four popup types, how popups take labels and formats from the Format tab, where viewers see them, and why raster and WMS layers have no Popup tab."
sidebar:
label: "How popups work"
---
This page explains each popup type and how popups use layer attribute formatting. Read it before you configure a complex layer.
## The Popup tab in one sentence
The `Popup` tab sets what viewers see when they click a map feature. The same settings apply to every feature, with each feature's values filled in where needed.
## The four popup types
The first control on the Popup tab is the `Type` dropdown. It has four options:
- **`None`** — popups are disabled. Clicking a feature does nothing.
- **`Default`** — MangoMap renders an automatic list of every visible attribute on the layer. The list, the labels, the formatting, and the order all come from the `Format` tab. There are no controls on the Popup tab beyond the type and an optional `Title`. New layers start with this type.
- **`Custom`** — you design the popup in a rich-text editor. Embed field values, format text, add images, tables, charts, conditionals, equations, and interactive buttons.
- **`Calculator`** — viewers fill in a form, and a formula combining their inputs with feature attributes computes a result. Useful for fertiliser-per-hectare or travel-time style popups.
Each layer has its own type. Layers on the same map can use different types.
If you are not sure which type to pick, answer three questions about the layer:
## How popups interact with the Format tab
The `Format` tab controls three things per attribute: the **alias** (display label), the **format** (how the value displays — `12,345.68`, `$12,345.68`, `9 May 2026`, etc.), and **visibility** (whether the attribute appears in the default popup at all).
- **Default popups** show only attributes whose visibility eye is on, labelled by their alias, formatted by their format config. Attributes that hold an image URL are the exception: they show as images at the top of the popup even when hidden.
- **Custom popups** substitute `{field_name}` variables using the underlying field name, not the alias. Hidden attributes still resolve in `{field_name}` references — the visibility toggle only governs the _default_ popup.
- **Calculator popups** use the same field-name variables in the title and the formula. The description takes no variables. Variables in the title and the formula format the same way as in Custom popups.
The diagram shows which Format tab settings each popup type uses:
If a popup looks wrong, check the Format tab first — see [Attribute formatting overview](/docs/formatting-attributes).
## Where popups appear
Popups render in:
- The popup panel on the right of the map, when a viewer clicks or taps a feature. Popups only load on click or tap; there's no hover-to-show behaviour.
- The same panel shows `Details could not be loaded` and a `Try again` button when MangoMap finds the feature but cannot load its values. See [A popup says “Details could not be loaded”](/docs/configuring-popups/troubleshoot-popup-details-not-loaded).
- The print and export popup overlay — popups in printed maps and PDFs.
## Variable substitution
Custom popups support two kinds of inline values. The unified `Title` field, for any non-`None` type, supports only `{field_name}`.
- `{field_name}` — substitutes the feature's value for that attribute, formatted via the Format tab. In Custom and Calculator popups, missing or empty values render as blank, not `NULL`.
- Equations — evaluate a small expression (arithmetic and numeric functions), such as `{population} / {area}`, and show the result. Same syntax as the Calculator's formula. Equations use each attribute's raw value, not the format from the Format tab.
Insert both from the editor toolbar. Insert an equation with `Insert equation`.
## HTML sanitisation
An iframe must use an `https://` address on another site: MangoMap removes one with an `http://` address, a MangoMap page, or a page on the map's own site. A video player needs an `https://` file address. See [How to embed an iframe in a custom popup](/docs/configuring-popups/embed-iframe-in-popup).
Links and buttons get one more check, after the variables are filled in. The target must be a web address, an email, phone, or text message link, or a path on the same site. Any other kind of link shows as plain text, or as a button that does nothing.
## Why raster and WMS layers don't have a Popup tab
Raster and WMS layers don't carry per-feature attributes on the MangoMap side. There's no clickable feature, no attribute table to render in a popup, and no `{field_name}` to substitute. The `Popup` tab is hidden for these layer types — only the `Details` tab appears.
To add clickable points over a raster basemap, use a vector layer.
## Common confusions
**"My popup shows blank for a field that has data."** The variable name doesn't match a field on the layer. Variable names are exact field names. If the field exists but the value is empty, that also renders blank in Custom and Calculator popups.
**"I changed the alias on the Format tab but my custom popup still shows the old name."** The custom popup uses the literal text you typed into the editor. The `{field_name}` variable substitutes the _value_, not the label — so if you typed `Population:` next to a `{population}` variable, only the value updates when you change the alias. Edit the label text in the popup template directly.
**"Calculator popup users don't see the Calculate button."** The button text is configured in Step 1 of the Calculator wizard. The default is `Calculate`. If users see no button at all, check that all three steps were completed and the popup was saved.
## Related
- [Popup tab controls](/docs/configuring-popups/popup-reference)
- [How attribute formatting works in MangoMap](/docs/formatting-attributes/concepts-attribute-formatting)
- [How to use the default popup](/docs/configuring-popups/use-default-popup)
- [How to write a custom popup template](/docs/configuring-popups/write-custom-popup-template)
- [How to build a calculator popup](/docs/configuring-popups/build-a-calculator-popup)
---