Symbols (Vector-Based Icons)

  • Google Maps JavaScript API uses customizable, vector-based icons, called Symbols, to enhance markers and polylines.

  • Symbols are defined using SVG path notation and offer properties to control appearance, such as path, fill color, and scale.

  • Predefined symbols like circles and arrows are available through the SymbolPath class for easy integration.

  • Symbols can be animated along polylines to create dynamic visual effects, often using window.setInterval() for position updates.

  • Developers can leverage the icon property for markers and the icons[] array within PolylineOptions for polylines to implement symbols effectively.
  1. Introduction
  2. Properties of a symbol
  3. Predefined symbols
  4. Add a symbol to a marker
  5. Add a symbol to a polyline
  6. Animate a symbol

Introduction

A Symbol is a vector-based icon that can be displayed on a Marker or a Polyline object. The symbol's shape is defined by a path using SVG path notation. While path is the only required property, the Symbol object supports a variety of properties allowing you to customize visual aspects, such as the color and weight of the stroke and fill. See the list of properties.

Several predefined symbols are available via the SymbolPath class. See the list below.

Properties of a symbol

Note that the default behavior of a Symbol varies slightly depending upon whether it appears on a marker or a polyline. These variances are described in the list of properties below.

A Symbol supports the following properties:

  • path (required) is the path defining the shape of the symbol. You can use one of the predefined paths in google.maps.SymbolPath or define a custom path using SVG path notation. Note: Vector paths on a polyline must fit within a 22x22px square. If your path includes points outside this square, then you must adjust the symbol's scale property to a fractional value, such as 0.2, so that the resulting scaled points fit within the square.
  • anchor sets the position of the symbol relative to the marker or polyline. The coordinates of the symbol's path are translated left and up by the anchor's x and y coordinates respectively. By default, a symbol is anchored at (0, 0). The position is expressed in the same coordinate system as the symbol's path.
  • fillColor is the color of the symbol's fill (that is, the region bordered by the stroke). All CSS3 colors are supported except for extended named colors. For symbols on markers, the default is 'black'. For symbols on polylines, the default is the stroke color of the corresponding polyline.
  • fillOpacity defines the relative opacity (that is, lack of transparency) of the symbol's fill. The values range from 0.0 (fully transparent) to 1.0 (fully opaque). The default is 0.0.
  • rotation is the angle by which to rotate the symbol, expressed clockwise in degrees. By default, a symbol marker has a rotation of 0, and a symbol on a polyline is rotated by the angle of the edge on which it lies. Setting the rotation of a symbol on a polyline will fix the rotation of the symbol such that it will no longer follow the curve of the line.
  • scale sets the amount by which the symbol is scaled in size. For symbol markers, the default scale is 1. After scaling the symbol may be of any size. For symbols on a polyline, the default scale is the stroke weight of the polyline. After scaling, the symbol must lie inside a 22x22px square, centered at the symbol's anchor.
  • strokeColor is the color of the symbol's outline. All CSS3 colors are supported except for extended named colors. For symbols on markers, the default is 'black'. For symbols on a polyline, the default color is the stroke color of the polyline.
  • strokeOpacity determines the relative opacity (that is, lack of transparency) of the symbol's stroke. The values range from 0.0 (fully transparent) to 1.0 (fully opaque). For symbol markers, the default is 1.0. For symbols on polylines, the default is the stroke opacity of the polyline.
  • strokeWeight defines the weight of the symbol's outline. The default is the scale of the symbol.

Predefined symbols

The Maps JavaScript API provides some built-in symbols that you can add to markers or polylines via the SymbolPath class.

The default symbols include a circle and two types of arrows. Both forward and backward facing arrows are available. This is especially useful for polylines, because the orientation of a symbol on a polyline is fixed. Forward is considered to be in the direction of the terminus of the polyline.

You can modify the stroke or fill of the predefined symbols using any of the default symbol options.

The following predefined symbols are included:

Name Description Example
google.maps.SymbolPath.CIRCLE A circle.
google.maps.SymbolPath.BACKWARD_CLOSED_ARROW A backward-pointing arrow that is closed on all sides.
google.maps.SymbolPath.FORWARD_CLOSED_ARROW A forward-pointing arrow that is closed on all sides.
google.maps.SymbolPath.BACKWARD_OPEN_ARROW A backward-pointing arrow that is open on one side.
google.maps.SymbolPath.FORWARD_OPEN_ARROW A forward-pointing arrow that is open on one side.

Add a symbol to a marker

To display a vector-based icon on a marker, pass a Symbol object literal with the desired path to the marker's icon property. The following example uses SVG path notation to create a custom icon for a marker.

TypeScript

// This example uses SVG path notation to add a vector-based symbol
// as the icon for a marker. The resulting icon is a marker-shaped
// symbol with a blue fill and no border.

function initMap(): void {
  const center = new google.maps.LatLng(-33.712451, 150.311823);
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 9,
      center: center,
    }
  );

  const svgMarker = {
    path: "M-1.547 12l6.563-6.609-1.406-1.406-5.156 5.203-2.063-2.109-1.406 1.406zM0 0q2.906 0 4.945 2.039t2.039 4.945q0 1.453-0.727 3.328t-1.758 3.516-2.039 3.070-1.711 2.273l-0.75 0.797q-0.281-0.328-0.75-0.867t-1.688-2.156-2.133-3.141-1.664-3.445-0.75-3.375q0-2.906 2.039-4.945t4.945-2.039z",
    fillColor: "blue",
    fillOpacity: 0.6,
    strokeWeight: 0,
    rotation: 0,
    scale: 2,
    anchor: new google.maps.Point(0, 20),
  };

  new google.maps.Marker({
    position: map.getCenter(),
    icon: svgMarker,
    map: map,
  });
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// This example uses SVG path notation to add a vector-based symbol
// as the icon for a marker. The resulting icon is a marker-shaped
// symbol with a blue fill and no border.
function initMap() {
  const center = new google.maps.LatLng(-33.712451, 150.311823);
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 9,
    center: center,
  });
  const svgMarker = {
    path: "M-1.547 12l6.563-6.609-1.406-1.406-5.156 5.203-2.063-2.109-1.406 1.406zM0 0q2.906 0 4.945 2.039t2.039 4.945q0 1.453-0.727 3.328t-1.758 3.516-2.039 3.070-1.711 2.273l-0.75 0.797q-0.281-0.328-0.75-0.867t-1.688-2.156-2.133-3.141-1.664-3.445-0.75-3.375q0-2.906 2.039-4.945t4.945-2.039z",
    fillColor: "blue",
    fillOpacity: 0.6,
    strokeWeight: 0,
    rotation: 0,
    scale: 2,
    anchor: new google.maps.Point(0, 20),
  };

  new google.maps.Marker({
    position: map.getCenter(),
    icon: svgMarker,
    map: map,
  });
}

window.initMap = initMap;
index.js
View example

Try Sample

Add a symbol to a polyline

To display symbols on a polyline, set the icons[] property of the PolylineOptions object. The icons[] array takes one or more IconSequence object literals, with the following properties:

  • icon (required) is the symbol to render on the line.
  • offset determines the distance from the start of the line at which an icon is to be rendered. This distance may be expressed as a percentage of the line's length (for example, '50%') or in pixels (for example, '50px'). The default is '100%'.
  • repeat determines the distance between consecutive icons on the line. This distance may be expressed as a percentage of the line's length (for example, '50%') or in pixels (for example, '50px'). To disable repeating of the icon, specify '0'. The default is '0'.

With a combination of symbols and the PolylineOptions class, you have a lot of control over the look and feel of polylines on your map. Below are some examples of customizations you can apply.

Arrows

Use the IconSequence.offset property to add arrows to the start or end of your polyline.

// Define a symbol using a predefined path (an arrow)
// supplied by the Google Maps JavaScript API.
var lineSymbol = {
  path: google.maps.SymbolPath.FORWARD_CLOSED_ARROW
};

// Create the polyline and add the symbol via the 'icons' property.
var line = new google.maps.Polyline({
  path: [{lat: 22.291, lng: 153.027}, {lat: 18.291, lng: 153.027}],
  icons: [{
    icon: lineSymbol,
    offset: '100%'
  }],
  map: map
});

View example

Dashed lines

You can achieve a dashed line effect by setting the opacity of your polyline to 0, and overlaying an opaque symbol over the line at regular intervals.

// Define a symbol using SVG path notation, with an opacity of 1.
var lineSymbol = {
  path: 'M 0,-1 0,1',
  strokeOpacity: 1,
  scale: 4
};

// Create the polyline, passing the symbol in the 'icons' property.
// Give the line an opacity of 0.
// Repeat the symbol at intervals of 20 pixels to create the dashed effect.
var line = new google.maps.Polyline({
  path: [{lat: 22.291, lng: 153.027}, {lat: 18.291, lng: 153.027}],
  strokeOpacity: 0,
  icons: [{
    icon: lineSymbol,
    offset: '0',
    repeat: '20px'
  }],
  map: map
});

View example

Custom paths

Custom symbols allow you to add many different shapes to a polyline.

// Define the custom symbols. All symbols are defined via SVG path notation.
// They have varying stroke color, fill color, stroke weight,
// opacity and rotation properties.
  var symbolOne = {
    path: 'M -2,0 0,-2 2,0 0,2 z',
    strokeColor: '#F00',
    fillColor: '#F00',
    fillOpacity: 1
  };

  var symbolTwo = {
    path: 'M -1,0 A 1,1 0 0 0 -3,0 1,1 0 0 0 -1,0M 1,0 A 1,1 0 0 0 3,0 1,1 0 0 0 1,0M -3,3 Q 0,5 3,3',
    strokeColor: '#00F',
    rotation: 45
  };

  var symbolThree = {
    path: 'M -2,-2 2,2 M 2,-2 -2,2',
    strokeColor: '#292',
    strokeWeight: 4
  };

  // Create the polyline and add the symbols via the 'icons' property.
  var line = new google.maps.Polyline({
    path: [{lat: 22.291, lng: 153.027}, {lat: 18.291, lng: 153.027}],
    icons: [
      {
        icon: symbolOne,
        offset: '0%'
      }, {
        icon: symbolTwo,
        offset: '50%'
      }, {
        icon: symbolThree,
        offset: '100%'
      }
    ],
    map: map
  });

View example

Animate a symbol

You can animate a symbol along a path by using the DOM's window.setInterval() function to change the offset of the symbol at fixed intervals.

TypeScript

// This example adds an animated symbol to a polyline.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      center: { lat: 20.291, lng: 153.027 },
      zoom: 6,
      mapTypeId: "terrain",
    }
  );

  // Define the symbol, using one of the predefined paths ('CIRCLE')
  // supplied by the Google Maps JavaScript API.
  const lineSymbol = {
    path: google.maps.SymbolPath.CIRCLE,
    scale: 8,
    strokeColor: "#393",
  };

  // Create the polyline and add the symbol to it via the 'icons' property.
  const line = new google.maps.Polyline({
    path: [
      { lat: 22.291, lng: 153.027 },
      { lat: 18.291, lng: 153.027 },
    ],
    icons: [
      {
        icon: lineSymbol,
        offset: "100%",
      },
    ],
    map: map,
  });

  animateCircle(line);
}

// Use the DOM setInterval() function to change the offset of the symbol
// at fixed intervals.
function animateCircle(line: google.maps.Polyline) {
  let count = 0;

  window.setInterval(() => {
    count = (count + 1) % 200;

    const icons = line.get("icons");

    icons[0].offset = count / 2 + "%";
    line.set("icons", icons);
  }, 20);
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

JavaScript

// This example adds an animated symbol to a polyline.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 20.291, lng: 153.027 },
    zoom: 6,
    mapTypeId: "terrain",
  });
  // Define the symbol, using one of the predefined paths ('CIRCLE')
  // supplied by the Google Maps JavaScript API.
  const lineSymbol = {
    path: google.maps.SymbolPath.CIRCLE,
    scale: 8,
    strokeColor: "#393",
  };
  // Create the polyline and add the symbol to it via the 'icons' property.
  const line = new google.maps.Polyline({
    path: [
      { lat: 22.291, lng: 153.027 },
      { lat: 18.291, lng: 153.027 },
    ],
    icons: [
      {
        icon: lineSymbol,
        offset: "100%",
      },
    ],
    map: map,
  });

  animateCircle(line);
}

// Use the DOM setInterval() function to change the offset of the symbol
// at fixed intervals.
function animateCircle(line) {
  let count = 0;

  window.setInterval(() => {
    count = (count + 1) % 200;

    const icons = line.get("icons");

    icons[0].offset = count / 2 + "%";
    line.set("icons", icons);
  }, 20);
}

window.initMap = initMap;
index.js
View example

Try Sample