---
title: "How to add an interactive button to a custom popup"
description: "Add a button to a custom popup that opens a per-feature web page, such as a Wikipedia article, or starts an email, a phone call, or a text message."
seo:
  title: "Add an interactive button to a popup"
sidebar:
  label: "Add an interactive button"
---

An interactive button opens a web page for the current feature, or starts an email, a phone call, or a text message. Examples include `View on Wikipedia`, `Open booking`, and `Email this office`. Click `Set link` in the popup editor, tick `Display as button`, choose the `Link type`, and set a label plus a target like `https://en.wikipedia.org/wiki/{wikipedia_slug}`. The button cannot run scripts or map actions, and it uses raw attribute values. If the source attribute is not set, the placeholder stays in the link, so wrap the button in a [conditional](/docs/configuring-popups/add-conditional-content-to-popup) when some features won't have a target.

**[See it on an example map](https://mangomap-staging.com/examples-staging/maps/y4h0ctdr/popup-media-logic-lab)**

Open the Popup Media & Logic Lab. In the legend, turn on `Sites — Links` and turn off `Sites — Default`. Click a site. Its popup ends with a `View on Wikipedia` button.

## Before you start

- The popup type must be `Custom`. See [How to write a custom popup template](/docs/configuring-popups/write-custom-popup-template).
- For per-feature button targets, the layer must have an attribute that holds a full URL, or a part of one such as an ID, an email address, or a phone number.

## Insert a button

1. In the Custom popup editor, place the cursor where you want the button.
2. Click `Set link` in the toolbar. The `Add Link` dialog opens.
3. Tick `Display as button`. The dialog title changes to `Add Button`.
4. Choose the `Link type`.
5. Fill in the fields.
6. Click `Add Button`.

<img src="/_assets/configuring-popups/add-interactive-buttons-to-popup--dialog.png" alt="Add Button dialog with Link type set to Web link, https://en.wikipedia.org/wiki/{wikipedia_slug} in URL, View on Wikipedia in Button Text, Open in new tab and Display as button ticked, Size Medium, Colour Primary, Variant Contained, and a preview of the button" width="1600" height="960" />

The dialog has these fields:

- `Link type` — `Web link`, `Email`, `Phone`, or `SMS`. Default: `Web link`. The next field changes to match it. For the email, phone, and text message types, see [How to add an email link to a custom popup](/docs/configuring-popups/add-email-links-to-popup) and [How to add a call or message link to a custom popup](/docs/configuring-popups/add-call-or-message-links-to-popup).
- `URL`, `Email address`, or `Phone number` — the button's target. Required. While it is empty, the `Add Button` or `Update Button` button changes to `Remove Button`. To insert a `{field_name}` variable from the layer's attributes, click `Insert simple variable` at the end of the field.
- `Subject` and `Body` — shown only for `Email`. The email's subject and message. Both accept `{field_name}` variables.
- `Button Text` — the label viewers see. Supports `{field_name}` variables for per-feature labels.
- `Open in new tab` — checkbox, shown only for `Web link`. Ticked by default on a new button. When ticked, the page opens in a new browser tab so the map stays open. When cleared, the page replaces the map in the current tab.
- `Display as button` — checkbox. When ticked, the item is a styled button and the styling fields appear.

When `Display as button` is ticked, three styling fields appear:

- `Size` — `Small`, `Medium`, or `Large`. Default: `Medium`.
- `Colour` — `Primary`, `Secondary`, `Success`, `Error`, `Warning`, `Info`. Default: `Primary`.
- `Variant` — `Contained`, `Outlined`, or `Text`. Default: `Contained`.

A `Preview` panel shows the button before you insert it.

Use a clear action label: `View on Wikipedia`, `Open booking`, `View source`, `Download report`.

## If you want a plain text link instead

Leave `Display as button` cleared. The text field is then `Link Text (optional)`, and there are no styling fields. If you leave `Link Text (optional)` empty, the link itself becomes the link text. Click `Add Link` to insert it.

## Edit an inserted button

The editor treats a button as one block, so you can't type into it. Change its label and settings in the dialog:

1. Click the button in the editor. A small menu appears above it.
2. Click `Edit`. The `Edit Button` dialog opens with the current values.
3. Change the fields you need.
4. Click `Update Button`.

The same menu has `Visit` and `Unlink`. `Visit` opens a web link in a new tab, or starts the email, call, or text message on your own device. It does not fill in variables, so a target with `{field_name}` opens with the variable name in it. `Unlink` deletes the button.

## Align the button

Click the button in the editor, then pick `Align left`, `Align centre`, `Align right`, or `Justify` in the menu above it.

## Use variables in the URL

If the layer has an attribute holding the full URL, reference it directly:
```text
{wikipedia_url}
```
If the layer has only a slug or ID, build the URL pattern:
```text
https://en.wikipedia.org/wiki/{wikipedia_slug}
```
If each feature has its own PDF, such as a permit or a report, build the PDF's address the same way:
```text
https://example.com/reports/{report_id}.pdf
```
Variables in the URL substitute per feature. Each feature's button opens its own target. Variables work the same way in `Email address`, `Subject`, `Body`, and `Phone number`.

## Use variables in the label

You can put variables in the label too:
```text
View {name} on Wikipedia
```
Each feature's button shows its own label. Useful when the action depends on the feature's name or category.

## Pick the right colour and variant

The `Colour` options match standard interface tones:

- `Primary` — main action; use sparingly so it stands out.
- `Secondary` — supporting action.
- `Error` — destructive action; rare in popups.
- `Success` — positive confirmation.
- `Info` — informational; matches the help tone.
- `Warning` — cautionary.

`Variant` controls fill style:

- `Contained` — solid filled button. Most prominent.
- `Outlined` — bordered button with a transparent fill. Quieter.
- `Text` — text only, no border. Minimal.

Pick `Contained` for the primary action of the popup; `Text` for secondary links that shouldn't compete for attention.

## Open in a new tab vs. same tab

The `Open in new tab` checkbox controls where a `Web link` button opens its page.

For external links, leave `Open in new tab` ticked so viewers keep their map. Clear it only when the button is meant to take the viewer away from the map.

`Email`, `Phone`, and `SMS` buttons have no `Open in new tab` checkbox. They start the email, call, or text message in the viewer's app, and the map stays open.

## A button replaces the map instead of opening a new tab

Popup buttons follow the `Open in new tab` setting. Some older buttons have `Open in new tab` cleared, so they now open their page in the same tab, and the page replaces the map.

To fix a button:

1. Click the button in the editor.
2. Click `Edit`.
3. Tick `Open in new tab`.
4. Click `Update Button`.
5. Click `Save Changes`.

## What happens when the target is malformed

A button works only when its target is one of these:

- A web address that starts with `http://` or `https://`, or a domain such as `example.com`
- An email, phone, or text message link
- A path on the same site, such as `/about`

Any other target does nothing when clicked.

A target with a variable that is not set keeps the placeholder, so the button can open a broken target. To avoid showing buttons that lead somewhere unexpected, wrap the button in a [conditional](/docs/configuring-popups/add-conditional-content-to-popup) keyed on the source attribute being non-null.

## Save the popup

After configuring the button, click `Save Changes` at the bottom right of the editor. Verify by clicking a feature on the map. The button shows your label, and clicking it opens the right target for that feature.

## Related

- [How to write a custom popup template](/docs/configuring-popups/write-custom-popup-template)
- [How to add dynamic content to a custom popup](/docs/configuring-popups/add-dynamic-content-to-popup)
- [How to insert attribute values into a custom popup](/docs/configuring-popups/insert-attribute-values-into-popup)
- [How to show or hide content based on a feature's attributes](/docs/configuring-popups/add-conditional-content-to-popup)
- [Popup tab controls](/docs/configuring-popups/popup-reference)