David Donachie's Website

Skip Navigation

Clickable imagemaps in Twine

Over on the excellent Twine Discord I see a lot of questions asking for the ability to "click somewhere on an image and go to some passage". This is a job for the HTML <map> element (generally known as an imagemap), which works in many of the main Twine formats (albeit with some different syntax).

What is an imagemap

An imagemap is a way to create clickable areas on a image in a web browser. Its format looks like this:

I won't go into depth about how to make <map> elements (MDN has you covered), but the example above would make a rectangle, 100px wide and 100px tall in top-left of the image, into a clickable area that takes you to SOME_PAGE.

Writing your own imagemaps by hand is a pain, luckily there are plenty of websites that make the process easier. I've been using maschek.hu for years, but there are plenty of choices. Some people swear by https://imagemap.org/ for example.

You can create your own imagemaps in your Twine stories and use them to link to passages, though no format has a ready-made macro for them.

Imagemaps in Twine

Sugarcube

Sugarcube allows you to turn any link into a passage link using data attributes. The data-passage attribute on a link, or <area>, turns it into a passage link. Here's a simple example you can try in your Twine story (images taken from Grophland.com).

Note that the <area> tags don't need href attributes, in fact they might prevent the passage links from working, so it's better not even to have empty ones. Wrapping the whole block in <<nobr>> will prevent blank lines inside the map (which won't be displayed, but are probably best off avoided).

Harlowe

Harlowe doesn't have attributes for passage navigation, but the way in which the (link:) macro works means that we can achieve much the same using some slightly clever formatting.

Again, we wrap the code to prevent linebreaks, in this case using Harlowe's { } tags.

Snowman

The Snowman format is much like Sugarcube's, except that you have to use Javascript to accomplish the passage transitions.

Chapbook

The Chapbook documentation doesn't mention it, but it actually uses data attributes to make passage links function in pretty much the same way as Sugarcube can, in this case data-cb-go. The following doesn't show an action cursor when you are over a clickable area, but otherwise works fine.

Styling Imagemaps

There is very little you can do to style an <area> tag. The browser hides it (and doesn't let it be shown) and won't style it even if you do show it. Normally the cursor becomes a pointer when you are over an area, but this depends on the presence of an href tag (which as discussed above will break passage navigation). The following is probably a good idea to add to your story CSS.

Imagemaps on Mobile

One objection to using imagemaps in Twine stories is that they rely on absolute pixel positioning, and as a result aren't very mobile friendly. If you resize the image (e.g. using max-width:100%) for mobile, then all the clickable areas will stop working.

On Grophland.com I've long handled this with a JQuery plugin called RWD ImageMaps. This plugin resizes the clickable areas as the image resizes, so that they always work no matter what the scale. In Twine formats that already include JQuery (like Sucarcube) you should be able to use the plugin as is (though you'll need to apply it to the passages where the maps are used). In other games you ought to be able to adapt the code to work, though I've not tried it.