SVG Icon Custom Metadata
Using Mapbox Studio, you can create map styles that include vector icons defined in SVG format. By adding custom Mapbox metadata to your SVG files, you can enable advanced features that make your icons more flexible when rendered as part of a symbol layer. This metadata enables:
- Stretchable areas (x and y): Make parts of your icon stretch to fit dynamic content (e.g., price callouts, shields)
- A Content area: Define where text or other content should be placed
- Parameters: Allow dynamic styling (such as color) via style expressions
SVG icons with Mapbox custom metadata can only be added to a style via Mapbox Studio. Support for adding SVG icons to a style at runtime is planned for future releases of Mapbox GL JS and the mobile maps SDKs.
Uploading SVG icons to Mapbox Studio
When creating a custom style in Mapbox Studio, you can upload SVGs to use as marker images. Each image is added to your style's iconset and is available for use in symbol layers. Keep the following concepts in mind when working with SVGs in Mapbox Studio:
- SVG icons can only be added to a style in Mapbox Studio; they cannot be added programmatically at runtime using Mapbox GL JS or the mobile maps SDKs.
- Mapbox metadata is not required to use SVG icons, but if present, it enables advanced features like stretchable areas and dynamic parameters such as color changes.
symbollayers can use either text, icons, or both. When using SVG icons with metadata, you can leverage the defined stretchable areas and parameters to create flexible and dynamic map symbols.- By specifying parameters in your SVGs, you can show the same SVG with different colors based on style expressions, reducing the need to load multiple icon images.
You can iterate on your SVG metadata by editing your SVG in a text editor and re-uploading it to Mapbox Studio to see the changes reflected in your style. Uploads with the same filename will overwrite the existing icon in the style. The updated SVG will be visible immediately in Mapbox Studio, but may take some time to propagate after style change are published.
Defining Stretchable Areas and Content Area
Stretchable areas metadata allow parts of your icon to expand or contract to accommodate varying content sizes, such as text labels.
For example, map below shows four point features visualized with a symbol layer and a stretchable icon that adapts to different text lengths.
To make your icon stretchable and define where content (like text) should appear, add <m:stretch-x-areas>, <m:stretch-y-areas>, and <m:content> elements inside <m:metadata>. All Mapbox custom metadata elements require the xmlns:m="https://www.mapbox.com" namespace declaration in the root <svg> element.
By defining x and y stretchable areas, you specify which parts of the icon can stretch:
- Areas of the icon in an x stretchable area will stretch horizontally.
- Areas in a y stretchable area will stretch vertically.
- Areas that fall in both an x and y stretchable area will stretch in both directions.
This allows you to create icons that can adapt to different content sizes without distorting important visual elements of the icon.
In the diagram above, the blue areas show horizontal stretchable regions, the green area shows a vertical stretchable region, and the yellow areas show where they intersect (stretching in both directions). The red dashed box shows the content area where text or other content would be placed. The rounded corners and the pointer triangle are outside all stretchable areas, so they stay fixed.
| Element | Description |
|---|---|
<m:stretch-x-areas> | Container for one or more horizontal stretchable regions. |
<m:stretch-x-area /> | Defines a specific horizontal region that can be stretched. Attributes: m:left (x-position), m:width (width of stretchable region). |
<m:stretch-y-areas> | Container for one or more vertical stretchable regions. |
<m:stretch-y-area /> | Defines a specific vertical region that can be stretched. Attributes: m:top (y-position), m:height (height of stretchable region). |
<m:content /> | Defines the area for text or other content. Attributes: m:left, m:top, m:width, m:height. Defaults to the whole image if not specified. |
Important constraints:
- All areas must be positioned inside the image boundaries and use only integer coordinates.
- The
contentarea (which defaults to the whole image if not specified) must overlap with at least one horizontal stretchable area and at least one vertical stretchable area for the icon to stretch properly.
In the example above, the SVG added to the style is a 60 by 40 oval, but stretches horizontally to accommodate any length of text by using custom metadata:
The content area is defined to exclude the rounded left and right edges of the icon, and a horizontal stretchable area is defined in the center 20 pixels of the icon. This allows the icon to stretch horizontally while without distorting the rounded edges. The diagram below illustrates the stretchable x-area (blue) and content area (dashed red) overlaid on the original icon:
<svg width="60" height="40" fill="none"
xmlns="http://www.w3.org/2000/svg"
xmlns:m="https://www.mapbox.com">
<m:metadata>
<m:stretch-x-areas>
<m:stretch-x-area m:left="20" m:width="20" />
</m:stretch-x-areas>
<m:content m:left="20" m:top="0" m:width="20" m:height="40" />
</m:metadata>
<path d="M 20 0 L 40 0 A 20 20 0 0 1 40 40 L 20 40 A 20 20 0 0 1 0 20 A 20 20 0 0 1 20 0 Z" fill="#800080" />
</svg>
Making icons stretch with icon-text-fit
To make your icon stretch according to the defined stretchable areas, set the icon-text-fit property in your symbol layer. Valid values are "width", "height", or "both".
"icon-text-fit": "width"
icon-text-fit can be also used without defining stretchable areas. In that case, the entire icon will be scaled to fit the text or content, which may be less visually appealing.
Adding parameters for dynamic styling
Parameters allow you to override specific values in your SVG icons dynamically through style expressions. The image below shows the same flag icon rendered in different colors by using parameters.
To allow dynamic styling (such as changing color), add a <m:parameters> section with one or more <m:parameter> elements. Each parameter uses the m:value attribute to define the default value in the SVG, which can be overridden by style expressions in Mapbox Studio. All Mapbox custom metadata elements require the xmlns:m="https://www.mapbox.com" namespace declaration in the root <svg> element.
| Element | Description |
|---|---|
<m:parameters> | Container for one or more parameter definitions. |
<m:parameter /> | Defines a specific parameter that can be overridden. Attributes: m:type (e.g., "color"), m:name (parameter name), m:value (default value to match in SVG). |
To use a parameter, set the m:value attribute to match a value used in your SVG markup. In the example below, all instances of #0057e0 in the SVG will be replaced with the parameter provided as fill_color in a symbol layer.
<svg width="40" height="40" viewBox="0 0 40 40" fill="none"
xmlns="http://www.w3.org/2000/svg"
xmlns:m="https://www.mapbox.com">
<m:metadata>
<m:parameters>
<m:parameter m:type="color" m:name="fill_color" m:value="#0057e0"/>
</m:parameters>
</m:metadata>
<ellipse cx="20" cy="20" rx="18" ry="18" fill="#0057e0" />
</svg>
Using parameters in style expressions
You can use parameters when defining the icon-image property in your symbol layer to dynamically change aspects of the SVG. The following example sets the fill_color parameter to green:
"icon-image": [
"image",
"oval",
{
"params": {
"fill_color": "#00FF00"
}
}
]
Assuming the data source has a property icon-fill-color that defines the desired color, you could also use a data-driven expression:
"icon-image": [
"image",
"oval",
{
"params": {
"fill_color": ["get", "icon-fill-color"]
}
}
]
See a complete example of adding a symbol layer that uses custom SVG parameters for dynamic icon styling in a web application.