# Tooltips and popups

_Last updated October 19, 2026_

> Show visitors more about a feature when they hover over it or click it, and make it worth their while.

> **Beta:** squidmaps is in beta. Features, the map spec and these docs may change without notice, and things may occasionally break. Export a copy of any map that matters to you, and tell us when something isn't right: use Beta feedback, or email support@squidmaps.io.

A map shows where things are. Its features' tooltips and popups say what
they are, and why they're on the map.

squidmaps has two interactions, built in and a little opinionated: a
**tooltip** when visitors hover over a feature, and a **popup** when they
click it. They're the ones people already know from maps across the web,
so there's nothing to wire up. You decide what each feature shows, and
squidmaps handles the rest, on desktops and phones, on your map's page and
wherever it's embedded.

Select a feature in the editor and you'll find its **Tooltip** and
**Popup** sections in the right panel. They work on the published map, so
use **Preview** to try them.

## Tooltips

A tooltip is a small label beside the pointer, there while visitors hover
over the feature. It shows the feature's name, so visitors can scan a busy
map without clicking everything.

Tooltips are off until you turn them on: check **Show a tooltip on hover**.
Pick its colors from the presets, or your own background and text colors.

```json
{
  "type": "Feature",
  "id": "area-1",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [-73.9564, 40.773816],
        [-73.9546, 40.773816],
        [-73.9546, 40.775184],
        [-73.9564, 40.775184],
        [-73.9564, 40.773816]
      ]
    ]
  },
  "properties": {
    "name": "Carl Schurz Park",
    "@tooltip": true,
    "@tooltip-background": "#2F8A4E",
    "@line-color": "#2F8A4E",
    "@fill-color": "#2F8A4E"
  }
}
```

With **Show a thumbnail of the first image in the tooltip**, a feature
with images shows a small picture too.

```json
{
  "type": "Feature",
  "id": "cafe",
  "geometry": {
    "type": "Point",
    "coordinates": [-73.9555, 40.7745]
  },
  "properties": {
    "name": "Café on the corner",
    "@images": [
      {
        "id": "6f1d2c1e-3b0a-4c55-9a59-1c4c7d0b2a01",
        "url": "https://squidmaps.io/examples/images/storefront",
        "original": "https://squidmaps.io/examples/images/storefront/large.webp",
        "width": 2560,
        "height": 1920,
        "bytes": 72608
      }
    ],
    "@tooltip": true,
    "@tooltip-thumbnail": true,
    "@tooltip-background": "#FFFFFF",
    "@tooltip-color": "#12312C",
    "@fill": "#D9664E",
    "@radius": 11,
    "@icon": "solid/mug-hot"
  }
}
```

> **Tip:** Phones have no hover, so tooltips are a shortcut, not a place for anything visitors must see. Put that in the popup.

## Popups

A popup opens when visitors click the feature, with its images, name and
description. Points can also offer a **Directions** link to the place, in
Google Maps.

Features have popups from the start, as long as they have something to
show. Choose its style in **Popup style**:

- **Card:** a card above the feature. The best fit for a sentence or two
  and a few images.
- **Panel:** a panel beside the map, or below it on phones, with room for a
  longer description and bigger images.
- **None:** nothing happens. For features that are context, not
  destinations, like a neighborhood's outline or a walking route.

### A card without images

A name and a sentence or two can be all a feature needs.

```json
{
  "type": "Feature",
  "id": "cafe",
  "geometry": {
    "type": "Point",
    "coordinates": [-73.9555, 40.7745]
  },
  "properties": {
    "name": "Café on the corner",
    "description": "Get the **cardamom bun**, and a seat by the window.",
    "@popup": "card",
    "@fill": "#D9664E",
    "@radius": 11,
    "@icon": "solid/mug-hot"
  }
}
```

### A card with images

Add images in the feature's **Images** section, and the card opens with
them. The first is its cover; visitors swipe or click through the rest,
and can open each one full size.

Click an image to open it, and write its **Alt text** below it: a short
description of what it shows. Visitors who use a screen reader hear it in
place of the image, once you publish.

```json
{
  "type": "Feature",
  "id": "cafe",
  "geometry": {
    "type": "Point",
    "coordinates": [-73.9555, 40.7745]
  },
  "properties": {
    "name": "Café on the corner",
    "description": "A tiny corner spot with six stools and a window counter. Get the **cardamom bun**, and a cortado.\n\nOpen 7am to 4pm, every day.",
    "@images": [
      {
        "id": "6f1d2c1e-3b0a-4c55-9a59-1c4c7d0b2a01",
        "url": "https://squidmaps.io/examples/images/storefront",
        "original": "https://squidmaps.io/examples/images/storefront/large.webp",
        "width": 2560,
        "height": 1920,
        "bytes": 72608
      },
      {
        "id": "6f1d2c1e-3b0a-4c55-9a59-1c4c7d0b2a02",
        "url": "https://squidmaps.io/examples/images/coffee",
        "original": "https://squidmaps.io/examples/images/coffee/large.webp",
        "width": 2560,
        "height": 1920,
        "bytes": 61214
      }
    ],
    "@popup": "card",
    "@directions": true,
    "@fill": "#D9664E",
    "@radius": 11,
    "@icon": "solid/mug-hot"
  }
}
```

### A panel

A panel slides in from the side, leaving the map in view. It suits
features with more to say: a few paragraphs, a list, several images.

```json
{
  "type": "Feature",
  "id": "park",
  "geometry": {
    "type": "Point",
    "coordinates": [-73.9555, 40.7745]
  },
  "properties": {
    "name": "Carl Schurz Park",
    "description": "A hilly park on the East River, with a promenade over the water.\n\n- Dog runs for big and small dogs\n- Benches along the river, in the shade\n- Gracie Mansion, the mayor's residence, at the north end",
    "@images": [
      {
        "id": "6f1d2c1e-3b0a-4c55-9a59-1c4c7d0b2a03",
        "url": "https://squidmaps.io/examples/images/park",
        "original": "https://squidmaps.io/examples/images/park/large.webp",
        "width": 2560,
        "height": 1920,
        "bytes": 60200
      }
    ],
    "@popup": "panel",
    "@fill": "#2F8A4E",
    "@radius": 12,
    "@icon": "solid/tree"
  }
}
```

## Making the most of popups

- **Write the description.** A popup that shows only the feature's name
  tells visitors nothing the tooltip didn't. Say why it's on the map: what
  to order, when it's open, what to look out for.
- **Add images.** A picture of the place helps visitors recognize it when
  they get there, and makes the map more inviting. Put your best one first:
  it's the cover. Give each one alt text, so everyone knows what it shows.
- **Format the description.** Descriptions are Markdown, so you can use
  **bold**, lists and links. Links open in a new tab, so the map stays
  where visitors left it.
- **Choose a style for how much there is to say.** A card for a line or two,
  a panel for more. Features of the same kind read best with the same style.
- **Turn off what isn't useful.** Set **None** for features visitors don't
  need to click, so a click on them doesn't open a card with nothing new in
  it.
- **Try it like a visitor.** Use **Preview**, on a desktop and a phone, and
  click around.

## In the map spec

Tooltips and popups are style properties, like colors, so they travel with
the feature: `@tooltip` and its options, `@popup` and `@directions`.

- [Features](https://squidmaps.io/docs/spec/features): Geometry, common properties, and how points, lines, areas, text and images are drawn.