Custom map icons (sprites)

Every map can use its own set of icons for displaying points of interest, highway shields, etc. Set of icons and a file defining which icon should be used for what purpose are called sprites. All the icons are combined together in a single large image.

How to create a sprite

The easiest way to create your own sprites is to upload a .zip file containing SVG icons to the selected map on MapTiler Cloud.

On MapTiler Cloud, select a map, click on the three vertical dots icon and select here the Symbols link:

All the .svg files inside will be automatically converted together into the sprite images for use in a map.

Technical details for advanced users

The whole sprites consist usually of 4 files:

sprite.png - the image with all the icons. For example:

• sprite.json - file describing the names and positions of the icons in the image (the names are later important when modifying the style in the editor)

• sprite@2x.png and sprite@2x.json - the same as above, but in higher resolution (HiDPI/retina)

Manual creation of sprites using command-line tools

For creating the sprite, you can also use some command-line tools like Spritezero. Spritezero is a Node.js based library so for the installation you need to have Node.js and NPM installed. The current version of spritezero runs on Node 8 so you need to use this version e.g. via nvm (Node Version Manager).

Install Spritezero

nvm install 8
nvm use 8
npm install -g @mapbox/spritezero-cli

Spritezero creates sprite and JSON from SVG icons. You need to put all your icons into one folder and run Spritezero simply with one command which is pointing to this folder. We are running it twice because for the maps we are generating also retina version (twice magnified sprite). You need to upload both versions into MapTiler Cloud (4 files).

Use Spritezero

spritezero [output filename] [input directory]
spritezero [output filename]@2x [input directory] --retina

How to upload custom-created sprites to MapTiler Cloud

On MapTiler Cloud, select a map, click on the three vertical dots icon and select here the Symbols link:

Now you can upload the 4 files:

When all four files are uploaded, you can use them in the Advanced editor. Here you will be able to choose the icons from the new sprite set based on their identifiers.