Custom symbols: creating vector icons from svg files (sprites)

[daniel-j-h]

Hey folks, I started playing around with maplibre and protomaps and after learning about font glyphs my next step is sprites!

I'll document below what I have found out because it was not obvious to me.

---

Here's what we want to achieve: being able to put icons from iconsax (or any svg icon library) on the map as vector symbols (sdf). Vector symbols means we can style its properties like the color at runtime based on data or zoom level.

The icons I'm going for as an example for no particular reason; it's a zip file of svg files

• https://iconsax-react.pages.dev
• https://iconsax.io

Here's a direct download link for the zip file with iconsax svg files in it

https://codeload.github.com/rendinjast/iconsax-react/zip/refs/heads/master

Let's create a single directory with symbolic links to all svg files in the "bold" variant

mkdir svgs
cd svgs
find ../iconsax-react-master/icons/Bold/ -name '*.svg' -exec ln -s {} . ';'

We can then use spritezero from https://www.npmjs.com/package/@elastic/spritezero - the retina flag creates @2 files for high-density screens. Maplibre will request either the regular sprite or the high-density one automatically later on.

npx @elastic/spritezero-cli --sdf iconsax-bold svgs
npx @elastic/spritezero-cli --sdf --retina iconsax-bold@2x svgs

Put the four files (2x .png and 2x .json) on a static host, e.g. I'm using an S3 bucket here

aws s3 cp --cache-control 'public, max-age=30758400, immutable' iconsax-bold.png s3://../sprites/
aws s3 cp --cache-control 'public, max-age=30758400, immutable' iconsax-bold.json s3://../sprites/
aws s3 cp --cache-control 'public, max-age=30758400, immutable' [email protected] s3://../sprites/
aws s3 cp --cache-control 'public, max-age=30758400, immutable' [email protected] s3://../sprites/

In the frontend map code we add the sprite url to the map initialization

new maplibregl.Map({
  center: [.., ..],
  style: {
    version: 8,
    sprite: "PATH_TO_STATIC_HOST/iconsax-bold",
  },
});

Add a source and style it with a symbol from the sprite

https://maplibre.org/maplibre-style-spec/layers/#symbol

map.addSource("point", {
  type: "geojson",
  data: {
    type: "FeatureCollection",
    features: [
      {
        type: "Feature",
        geometry: {
          type: "Point",
          coordinates: [-9.056, 53.983],
        },
      },
    ],
  },
});

map.addLayer({
  id: "point",
  type: "symbol",
  source: "point",
  layout: {
    "icon-image": "location", // <- name corresponds to the original svg icon name
    "icon-size": 1.5,
  },
  paint: {
    "icon-color": "#2E7831",
    "icon-halo-color": "#ffffff",
    "icon-halo-width": 2,
  },
});

And there it is! 😍

Hope that helps!

Existing documentation

• https://maplibre.org/maplibre-style-spec/sprite/

[HarelM]

We just recently updated the sprite docs to be a bit more clear, it is in the style-spec repo, feel free to add more info there.

[mrflix]

Thanks for the write-up, @daniel-j-h. Note to others trying this out: spritezero currently contains a bug in its retina scaling when the svg files have a viewport attribute (which they most probably have). The retina-version will be cut off. Remove the viewport attributes from your svg files or install the fork with the fix: npm install "https://github.com/JinIgarashi/spritezero.git#issue-7"