Customize map icons

Maps use icons to display points of interest (POIs), landmarks, road shields, and other features. These icons come in icon sets where all icons are visually consistent. You can either use our professionally prepared catalog sets, or create your own custom sets and use them across multiple maps.

This page explains how to customize and manage your map icons using our visual editor Map Designer. If you’re looking for a programmatic way to work with icons, check out icon code examples for MapTiler SDK JS.

Winter map with standard catalog icons (left) and with custom icons

Customize catalog icons

Catalog icons are our default map icons. When you customize our maps, you can customize the icons too:

1. In your MapTiler account, page Maps, click on the map you want to use. It can be any map including custom.

2. Under the map preview, click Customize. This opens the map in Map Designer.

3. Go to menu Layers and open the block and layer which contains the icon you want to customize. If you’re not sure which layer it is, click on the icon in the map and you’ll get a list of blocks and layers in that spot. The icon layer is typically at the top.

   

4. Adjust icon properties as needed: fill color, outline, opacity, size, and anchor (relative position of the icon and label). You can also swap the icon image with another one.

Prepare custom icons

For a fully custom map, you’ll typically need a complete set of custom icons, which you need to prepare in a graphic design program. This section explains the technical requirements for best results.

Size and count

To ensure map performance and compatibility with all devices, icon sets have the following constraints:

• Icon size: Maximum 256×256 px. For better downscaling and sharper rendering, we recommend to prepare icons in even-pixel dimensions (e.g. 24×24 px).
• Icon count: Maximum 500 icons per set.
• Total sprite size: The generated sprite sheet is the “canvas” for all your icons. Its size is the hard limit which cannot exceed 4096×4096 px.

Icon format

When preparing your icons, use vector (SVG) or raster (PNG) format:

Vector (SVG to SDF)

Vector icons are recommended for most map features. We save them in the SDF (Signed Distance Field) format, which is technically raster, but preserves the benefits of vector: the possibity to customize the icon’s fill color, outline, and size while maintaining sharp edges.

Vector icons must be monochrome. Color, outline and other properties are defined per map, which means that you can reuse a vector icon set across multiple maps and have it customized differently in each of them. Another benefit is that you can customize the icons along with their label.

Turn off customizability

You can choose to upload and use SVG icons but turn off the “customizable” (SDF) option. This makes the vector icon behave like a raster; it will preserve its original colors but cannot be recolored in the map editor.

Raster (PNG)

Raster icons are static images where the colors are already “baked” into the file. You cannot customize them in any way. Use the raster format for multicolored icons, photos, or complex patterns that need to stay exactly as they are.

Resolution

For high-res mobile or desktop screens, you can provide 2× or 3× resolution versions to ensure your icons don’t look blurry on modern devices. We also recommend to use this setting to preserve detailed, pixel-perfect design of large icons such as landmark images.

Manage your icons

To upload a new icon set or manage any of your custom sets, go to the icon set management. You can open it from any map:

1. In your MapTiler account, page Maps, click on the map you want to use. It can be any map including custom.

2. Under the map preview, click Customize. This opens the map in Map Designer.

3. Open the “hamburger” menu → Icon sets.

   

4. To add a new set, click the (+) plus button. You can upload icons individually or in a ZIP file.