Add a symbol layer to a map

A symbol can be connected up to a data source and used to render an icon and/or text at a given point. Symbol layers are rendered using WebGL and can be used to render large collections of points on the map. This layer can render a lot more point data on the map, with good performance, than what is achievable using HTML markers. However, the symbol layer doesn't support traditional CSS and HTML elements for styling.

Tip

Symbol layers by default will render the coordinates of all geometries in a data source. To limit the layer such that it only renders point geometry features set the filter property of the layer to ['==', ['geometry-type'], 'Point'] or ['any', ['==', ['geometry-type'], 'Point'], ['==', ['geometry-type'], 'MultiPoint']] if you want to include MultiPoint features as well.

The maps image sprite manager, which is used to load custom images used by the symbol layer supports the following image formats:

  • JPEG
  • PNG
  • SVG
  • BMP
  • GIF (no animations)

Add a symbol layer

To add a symbol layer to the map and render data, a data source first needs to be created and added the map. A symbol layer can then be created and passed in the data source to retrieve the data from. Finally, data needs to be added into the data source so that there is something to be rendered. The following code shows the code that should be added to the map after it has loaded to render a single point on the map using a symbol layer.

//Create a data source and add it to the map.
var dataSource = new atlas.source.DataSource();
map.sources.add(dataSource);

//Create a symbol layer to render icons and/or text at points on the map.
var layer = new atlas.layer.SymbolLayer(dataSource);

//Add the layer to the map.
map.layers.add(layer);

//Create a point and add it to the data source.
dataSource.add(new atlas.data.Point([0, 0]));

There are four different types of point data to that can be added to the map:

  • GeoJSON Point geometry - This object only contains a coordinate of a point and nothing else. The atlas.data.Point helper class can be used to easily create these objects.
  • GeoJSON MultiPoint geometry - This object contains the coordinates of multiple points but nothing else. The atlas.data.MultiPoint helper class can be used to easily create these objects.
  • GeoJSON Feature - This object consists of any GeoJSON geometry and a set of properties that contain metadata associated to the geometry. The atlas.data.Feature helper class can be used to easily create these objects.
  • atlas.Shape class is similar to the GeoJSON feature in that it consists of a GeoJSON geometry and a set of properties that contain metadata associated to the geometry. If a GeoJSON object is added to a data source it can easily be rendered in a layer, however, if the coordinates property of that GeoJSON object is updated, the data source and map don't change as there is no mechanism in the JSON object to trigger an update. The shape class provides functions for updating the data it contains, and when a change is made, the data source and map are automatically notified and updated.

The following code sample creates a GeoJSON Point geometry and passes it into the atlas.Shape class to make it easy to update. The center of the map is used initially to render a symbol. A click event is added to the map such that when it fires, the coordinates of where the mouse was clicked are used with the shapes setCoordinates function that updates the location of the symbol on the map.


Tip

By default, for performance, symbol layers optimize the rendering of symbols by hiding symbols that overlap. As you zoom in the hidden symbols become visible. To disable this feature and render all symbols at all times, set the allowOverlap property of the iconOptions options to true.

Add a custom icon to a symbol layer

Symbol layers are rendered using WebGL. As such all resources, such as icon images, must be loaded into the WebGL context. This sample shows how to add a custom icon to the map resources and then use it to render point data with a custom symbol on the map. The textField property of the symbol layer requires an expression to be specified. In this case, we want to render the temperature property but since it's a number, it needs to be converted to a string. Additionally we want to append the "°F" to it. An expression can be used to do this; ['concat', ['to-string', ['get', 'temperature']], '°F'].


Tip

The Azure Maps web SDK provides several customizable image templates you can use with the symbol layer. For more infromation, see the How to use image templates document.

Customize a symbol layer

The symbol layer has many styling options available. Here is a tool to test out these various styling options.


Tip

When you only want to render text with a symbol layer, you can hide the icon by setting the image property of the icon options to 'none'.

Next steps

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

See the following articles for more code samples to add to your maps: