title	description	author	ms.author	ms.date	ms.topic	ms.service	services	ms.custom
Image templates in the Azure Maps Web SDK \| Microsoft Azure Maps	Learn how to add image icons and pattern-filled polygons to maps by using the Azure Maps Web SDK. View available image and fill pattern templates.	stevemunk	v-munksteve	8/6/2019	how-to	azure-maps	azure-maps	codepen, devx-track-js

How to use image templates

Images can be used with HTML markers and various layers within the Azure Maps web SDK:

Symbol layers can render points on the map with an image icon. Symbols can also be rendered along a lines path.
Polygon layers can be rendered with a fill pattern image.
HTML markers can render points using images and other HTML elements.

In order to ensure good performance with layers, load the images into the map image sprite resource before rendering. The IconOptions, of the SymbolLayer, preloads a couple of marker images in a handful of colors into the map image sprite, by default. These marker images and more are available as SVG templates. They can be used to create images with custom scales, or used as a customer primary and secondary color. In total there are 42 image templates provided: 27 symbol icons and 15 polygon fill patterns.

Image templates can be added to the map image sprite resources by using the map.imageSprite.createFromTemplate function. This function allows up to five parameters to be passed in;

createFromTemplate(id: string, templateName: string, color?: string, secondaryColor?: string, scale?: number): Promise<void>

The id is a unique identifier you create. The id is assigned to the image when it's added to the maps image sprite. Use this identifier in the layers to specifying which image resource to render. The templateName specifies which image template to use. The color option sets the primary color of the image and the secondaryColor options sets the secondary color of the image. The scale option scales the image template before applying it to the image sprite. When the image is applied to the image sprite, it's converted into a PNG. To ensure crisp rendering, it's better to scale up the image template before adding it to the sprite, than to scale it up in a layer.

This function asynchronously loads the image into the image sprite. Thus, it returns a Promise that you can wait for this function to complete.

The following code shows how to create an image from one of the built-in templates, and use it with a symbol layer.

map.imageSprite.createFromTemplate('myTemplatedIcon', 'marker-flat', 'teal', '#fff').then(function () {

	//Add a symbol layer that uses the custom created icon.
	map.layers.add(new atlas.layer.SymbolLayer(datasource, null, {
		iconOptions: {
			image: 'myTemplatedIcon'
		}
	}));
});

Use an image template with a symbol layer

Once an image template is loaded into the map image sprite, it can be rendered as a symbol in a symbol layer by referencing the image resource ID in the image option of the iconOptions.

The following sample renders a symbol layer using the marker-flat image template with a teal primary color and a white secondary color.

Use an image template along a lines path

Once an image template is loaded into the map image sprite, it can be rendered along the path of a line by adding a LineString to a data source and using a symbol layer with a lineSpacingoption and by referencing the ID of the image resource in the image option of th iconOptions.

The following sample renders a pink line on the map and uses a symbol layer using the car image template with a dodger blue primary color and a white secondary color.

Tip

If the image template points up, set the rotation icon option of the symbol layer to 90 if you want it to point in the same direction as the line.

Use an image template with a polygon layer

Once an image template is loaded into the map image sprite, it can be rendered as a fill pattern in a polygon layer by referencing the image resource ID in the fillPattern option of the layer.

The following sample renders a polygon layer using the dot image template with a red primary color and a transparent secondary color.

Tip

Setting the secondary color of fill patterns makes it easier to see the underlying map will still providing the primary pattern.

Use an image template with an HTML marker

An image template can be retrieved using the altas.getImageTemplate function and used as the content of an HTML marker. The template can be passed into the htmlContent option of the marker, and then customized using the color, secondaryColor, and text options.

The following sample uses the marker-arrow template with a red primary color, a pink secondary color, and a text value of "00".

Tip

Image templates can be used outside of the map too. The getImageTemplate funciton returns an SVG string that has placeholders; {color}, {secondaryColor}, {scale}, {text}. Replace these placeholder values to create a valid SVG string. You can then either add the SVG string directly to the HTML DOM or convert it into a data URI and insert it into an image tag. For example:

//Retrieve an SVG template and replace the placeholder values.
var svg = atlas.getImageTemplate('marker').replace(/{color}/, 'red').replace(/{secondaryColor}/, 'white').replace(/{text}/, '').replace(/{scale}/, 1);

//Convert to data URI for use in image tags.
var dataUri = 'data:image/svg+xml;base64,' + btoa(svg);

Create custom reusable templates

If your application uses the same icon with different icons or if you are creating a module that adds additional image templates, you can easily add and retrieve these icons from the Azure Maps web SDK. Use the following static functions on the atlas namespace.

Name	Return Type	Description
`addImageTemplate(templateName: string, template: string, override: boolean)`		Adds a custom SVG image template to the atlas namespace.
`getImageTemplate(templateName: string, scale?: number)`	string	Retrieves an SVG template by name.
`getAllImageTemplateNames()`	string[]	Retrieves an SVG template by name.

SVG image templates support the following placeholder values:

Placeholder	Description
`{color}`	The primary color.
`{secondaryColor}`	The secondary color.
`{scale}`	The SVG image is converted to an png image when added to the map image sprite. This placeholder can be used to scale a template before it is converted to ensure it renders clearly.
`{text}`	The location to render text when used with an HTML Marker.

The following example shows how to take an SVG template, and add it to the Azure Maps web SDK as a reusable icon template.

List of image templates

This table lists all image templates currently available within the Azure Maps web SDK. The template name is above each image. By default, the primary color is blue and the secondary color is white. To make the secondary color easier to see on a white background, the following images have the secondary color set to black.

Symbol icon templates

:::row::: :::column span=""::: marker :::column-end::: :::column span=""::: marker-thick :::column-end::: :::column span=""::: marker-circle :::column-end::: :::column span=""::: marker-flat :::column-end::: :::row-end::: :::row::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::row-end:::

:::row::: :::column span=""::: marker-square :::column-end::: :::column span=""::: marker-square-cluster :::column-end::: :::column span=""::: marker-arrow :::column-end::: :::column span=""::: marker-ball-pin :::column-end::: :::row-end::: :::row::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::row-end:::

:::row::: :::column span=""::: marker-square-rounded :::column-end::: :::column span=""::: marker-square-rounded-cluster :::column-end::: :::column span=""::: flag :::column-end::: :::column span=""::: flag-triangle :::column-end::: :::row-end::: :::row::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::row-end:::

:::row::: :::column span=""::: triangle :::column-end::: :::column span=""::: triangle-thick :::column-end::: :::column span=""::: triangle-arrow-up :::column-end::: :::column span=""::: triangle-arrow-left :::column-end::: :::row-end::: :::row::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::row-end:::

:::row::: :::column span=""::: hexagon :::column-end::: :::column span=""::: hexagon-thick :::column-end::: :::column span=""::: hexagon-rounded :::column-end::: :::column span=""::: hexagon-rounded-thick :::column-end::: :::row-end::: :::row::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::row-end:::

:::row::: :::column span=""::: pin :::column-end::: :::column span=""::: pin-round :::column-end::: :::column span=""::: rounded-square :::column-end::: :::column span=""::: rounded-square-thick :::column-end::: :::row-end::: :::row::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::row-end:::

:::row::: :::column span=""::: arrow-up :::column-end::: :::column span=""::: arrow-up-thin :::column-end::: :::column span=""::: car :::column-end::: :::column span=""::: :::column-end::: :::row-end::: :::row::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::row-end:::

Polygon fill pattern templates

:::row::: :::column span=""::: checker :::column-end::: :::column span=""::: checker-rotated :::column-end::: :::column span=""::: circles :::column-end::: :::column span=""::: circles-spaced :::column-end::: :::row-end::: :::row::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::row-end:::

:::row::: :::column span=""::: diagonal-lines-up :::column-end::: :::column span=""::: diagonal-lines-down :::column-end::: :::column span=""::: diagonal-stripes-up :::column-end::: :::column span=""::: diagonal-stripes-down :::column-end::: :::row-end::: :::row::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::row-end:::

:::row::: :::column span=""::: grid-lines :::column-end::: :::column span=""::: rotated-grid-lines :::column-end::: :::column span=""::: rotated-grid-stripes :::column-end::: :::column span=""::: x-fill :::column-end::: :::row-end::: :::row::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::row-end:::

:::row::: :::column span=""::: zig-zag :::column-end::: :::column span=""::: zig-zag-vertical :::column-end::: :::column span=""::: dots :::column-end::: :::column span=""::: :::column-end::: :::row-end::: :::row::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::column span=""::: :::column-end::: :::row-end:::

Preloaded image icons

The map preloads a set of icons into the maps image sprite using the marker, pin, and pin-round templates. These icon names and their color values are listed in the table below.

icon name	color	secondaryColor
`marker-black`	`#231f20`	`#ffffff`
`marker-blue`	`#1a73aa`	`#ffffff`
`marker-darkblue`	`#003963`	`#ffffff`
`marker-red`	`#ef4c4c`	`#ffffff`
`marker-yellow`	`#f2c851`	`#ffffff`
`pin-blue`	`#2072b8`	`#ffffff`
`pin-darkblue`	`#003963`	`#ffffff`
`pin-red`	`#ef4c4c`	`#ffffff`
`pin-round-blue`	`#2072b8`	`#ffffff`
`pin-round-darkblue`	`#003963`	`#ffffff`
`pin-round-red`	`#ef4c4c`	`#ffffff`

Try it now tool

With the following tool, you can render the different built-in image templates in various ways and customize the primary and secondary colors and scale.

Next steps

Learn more about the classes and methods used in this article:

[!div class="nextstepaction"] ImageSpriteManager

[!div class="nextstepaction"] atlas namespace

See the following articles for more code samples where image templates can be used:

[!div class="nextstepaction"] Add a symbol layer

[!div class="nextstepaction"] Add a line layer

[!div class="nextstepaction"] Add a polygon layer

[!div class="nextstepaction"] Add HTML Makers

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Files

how-to-use-image-templates-web-sdk.md

how-to-use-image-templates-web-sdk.md

How to use image templates

Use an image template with a symbol layer

Use an image template along a lines path

Use an image template with a polygon layer

Use an image template with an HTML marker

Create custom reusable templates

List of image templates

Try it now tool

Next steps

Files

how-to-use-image-templates-web-sdk.md

Latest commit

History

how-to-use-image-templates-web-sdk.md

File metadata and controls

How to use image templates

Use an image template with a symbol layer

Use an image template along a lines path

Use an image template with a polygon layer

Use an image template with an HTML marker

Create custom reusable templates

List of image templates

Try it now tool

Next steps