Tooltips and popups

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.

{
  "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.

{
  "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"
  }
}

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.

{
  "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.

{
  "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.

{
  "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.