How To Add Images to Maps with TileMill’s SVG Support


3 min read

Image support in TileMill, our open source map design tool, allows you to add custom SVG markers for point data, letting you create unique aesthetics on maps like the one we made on our homepage. I recently started using this feature on project and wanted to demonstrate how adding SVG images works in the context of one of Thanksgiving’s pressing issues — worldwide turkey production. Turkey SVG Map Edit

The data comes from the Food and Agriculture Organization’s open data portal FAOSTAT, listing out the top 20 producers of turkeys in metric tons of turkey meat.

To add images like this to your map the first step is to save them someplace in your file system that TileMill has access to. I find it easiest to keep images in a subfolder of the relevant TileMill project directory, which by default this is ~/Documents/MapBox/project/your-project-name. Create a folder there (let’s call it: images), drop in your SVG file, and then head over TileMill.

Next add a point-file style to your points layer that references the image:

`#turkey {
  point-file: url(images/turkey.svg);

You’ll likely want your image to scale based on zoom level. Using the point-transform symbolizer, you can invoke any SVG transform function, including “scale”. Don’t forget to add quotes around your function — these are required by Carto, TileMill’s map styling language.

`#turkey {
  [zoom=3] { point-transform:"scale(.5)";}
  [zoom=4] { point-transform:"scale(1)";}
  [zoom=5] { point-transform:"scale(2)";}
  point-file: url(images/turkey.svg);

Entering a value of 1 will display your image at it’s original size, while a value of 0.5 will display an image at 50% of the images original dimensions. Entering only one value maintains your image’s relative dimensions, but if you wanted to stretch your image by doubling the width while maintaing the same height, you could enter


where the first value multiplies the x dimension (width), and the second the y dimension (height).

Suppose you have your point image correctly scaled, but it’s is not quite in the right place. With CSV and GeoJSON support in the TileMill, it’s not hard to go in and manually change coordinates, but this is clumsy and requires a lot of clicking. For an easier fix, we can turn again to the point-transform symbolizer, with which we can call the “translate” function.


This will move the image to the right 20 pixels and up 40 pixels.

And you’re done! You can read more about SVG transforms on W3, and find documentation on other map styling tricks in TileMill at

If you are experimenting with map making over the long holiday weekend, check out this week’s TileMill release. It’s now easy to share maps on MapBox Hosting in just a few clicks and the service is free for seven days, so give it a try. You can download TileMill here.

What we're doing.