Interactive Map
Display maps and more with annotations, filtering and interactivity.
Setting up your Airtable base
The Interactive Map action for Airtable pulls its data from an Airtable base for both the content of the map and the map graphics themselves.
The first step to setting up this Action Links is to duplicate the Interactive Map Template base to your own Airtable workspace. Open the template and click Copy base. You can find the ID for the base in the URL (it's the part that begins app) – you'll need to copy and paste this into the Base ID field when configuring your Link in the Action Links Manager (see below).
Levels
The Levels table is where you'll identify the different levels (i.e. floors or stories) of your map. You don't necessarily need to use the map to display a building, and so you may want to use the Levels functionality for another convention that users should be able to cycle up and down through.
name
The name to display for the level; this will display as the label in the corner of the map where users are able to move between labels.
number
The number of the level; this denotes the order in which levels will be displayed when a user cycles up or down using the controls in the map. The map will default to the level with number 0, successive levels should increase incrementally without skipping any numbers – if you need to jump a level, use the name to indicate this rather than jumper a number.
mapSvg
Column names must not be changed
Column names are used by Action Links to access the relevant data points via the Airtable API – it's therefore essential that you don't amend the column names. If you mistakenly change the names of any columns, check the tables in this documentation for the correct name. Note that these names are case sensitive, so keep an eye out for how lowercase and uppercase letters are used.
Content
The Content table is where you identify the interactive hotspots and associated content to display in the sidebar.
name
The name for the interactive item that you want to display in the sidebar list.
elementId
The id attribute of the interactive element in the SVG. Make sure you include all your interactive elements inside a containing element with an id attribute of interactive.
category
The category to group this content item in when displayed in the sidebar list.
image
Optionally, the URL for an image to display at the top of the content in the sidebar when this item is selected.
content
The content to display in the sidebar when this item is selected. Supports Airtable's native formatting, markdown and HTML.
levels
The Level record that's relevant to the content item.
Action settings
Base ID
The ID for the Airtable Base that contains the data for your interactive map. You can find this in the URL for the base – it's the part that begins with app, e.g. appA1B2C3e4f5g6.
Creating your map SVG
The Interactive Map action uses Scalable Vector Graphic (SVG) files as the background image and to identify areas of interactivity. Being a scalable vector format, SVG files can be very small in size, make it possible for users to zoom in and out without distorting the image, and enable additional interactivity. You can create SVG files in tools like Figma or Adobe Illustrator.
To add interactivity to your SVG you need to add a group with id interactive inside which you should include the elements that you want to make interactive, applying a separate id attribute to each. You can do this manually to an exported SVG file (by opening it in a programme like VS Code or Notepad), or within an image editing programme like Figma.
If you're using Figma, make sure the Include "id" attribute checkbox is checked in the SVG export settings:
This will set the id attribute of each element to the name you've set for the layer in Figma. It's important to make sure that your layers are all named differently (HTML doesn't support more than one element having the same id attribute), and that your layer names don't contain spaces (use camelCase or snake_case instead).
See below for more information about how to configure your SVG images to avoid issues with your interactive areas.
Here's an example SVG that's been configured with interactive areas – download the file and open it in a text editor to examine the elements and their id attributes:
Caching
Requests to get the data for your map can be quite slow as Action Links has to traverse both the 'Levels' and 'Content' tables of your Airtable base. To reduce load times for your users, Action Links caches your map data for 24 hours. To minimise scheduled processes for Links that are only accessed infrequently, the cached data is only refreshed when a user actually visits your Action Link after the existing cache has expired. As such, the first visit after the existing cache has expired will trigger Action Links to make the requests to Airtable to get the most recent data and refresh the cache before returning the data to the user's browser. Consequently, the first request to load your Action Link after the cache has expired may take slightly longer to complete.
If you have made a change to the data in Airtable that you want to pull through quicker, you can manually trigger the cache to expire from the edit page for the relevant Action Link.
Frequently Asked Questions
What perspective should I use for my map?
We recommend creating an isometric map – don't worry, they're not as hard to create as you might think. A few reasons they're great:
Perspective: They give the user a clearer perspective on a space – it's easier to judge the proportions of rooms and potential obstacles.
Wayfinding: Perspective makes it easier to understand routes through a space, and thus for users to find their way to a destination.
Labelling: Isometric maps create empty space along the diagonals for you to annotate your map without obscuring the contents of your map or needing to adjust text sizes to fit into cramped spaces.
Why are some of my interactive areas not transitioning smoothly when clicked?
This tends to be because the interactive SVG element (i.e. the element to which the id attribute has been applied) doesn't have an initial fill colour. Programmes like Figma and Adobe Illustrator sometimes make unexpected changes to the structure of the code they output (in this case, the code for the SVG you're exporting).
Sometimes they will output individual layers as singular <path> tags, and in other cases they'll output them as a series of paths grouped by a <g> tag. It isn't usually possible to tell from the GUI (graphical user interface) of the programme that this is likely to happen.
Action Links uses the id attribute of SVG elements to identify whether which elements should be interactive. For the colour transition to work correctly, the element with the relevant id attribute must have an initial fill colour to transition from. However, sometimes the software you've used to create the SVG will apply the fill colour to a child of the element with the id attribute instead of the attributed element itself.
To avoid this happening, we recommend keeping your interactive layers as simple as possible, grouping them altogether in a single group and ensuring each individual layer has a fill colour applied.
Why SVGs instead of a geospatial format like GeoJSON?
When developing this Action, we explored using a geospatial format for the map overlay layers (i.e. the buildings and their contents). Initially we developed the Map to use GeoJSON for each layer – we played with creating GeoJSON in some geospatial editors (including QGIS), but we were concerned that the learning curve involved in using such software might make things too difficult for our users. As a product, Action Links is meant to make things easier for users (both creators and consumers), and the benefits of using a geospatial format for the map data were deemed to be somewhat limited for the anticipated use cases of the Action.
Most geospatial map libraries are designed to render large quantities of data (i.e. spanning large distances on the map). This creates other limitations when it comes to displaying relatively small areas, as was our intention with the Interactive Map Action. The map contents would appear pixelated, or overlayed graphics would render awkwardly when scrolling.
SVGs, on the other hand, are much easier to create and edit in programmes like Figma and Illustrator, making them a much more accessible format for general users. Although they are perhaps less performant when used in the context of a geospatial map, our Interactive Map has been designed to work with relatively small areas (e.g. a building or small collection of buildings), rather than entire cities or countries and so any performance implications of using SVGs shouldn't be noticeable.
Last updated
