1. [Introduction](https://developers.google.com/maps/documentation/javascript/symbols.md.txt#introduction) 2. [Properties of a symbol](https://developers.google.com/maps/documentation/javascript/symbols.md.txt#properties) 3. [Predefined symbols](https://developers.google.com/maps/documentation/javascript/symbols.md.txt#predefined) 4. [Add a symbol to a marker](https://developers.google.com/maps/documentation/javascript/symbols.md.txt#add_to_marker) 5. [Add a symbol to a polyline](https://developers.google.com/maps/documentation/javascript/symbols.md.txt#add_to_polyline) 6. [Animate a symbol](https://developers.google.com/maps/documentation/javascript/symbols.md.txt#animate) ## Introduction A [`Symbol`](https://developers.google.com/maps/documentation/javascript/reference.md.txt#Symbol) is a vector-based icon that can be displayed on a [`Marker`](https://developers.google.com/maps/documentation/javascript/markers.md.txt) or a [`Polyline`](https://developers.google.com/maps/documentation/javascript/shapes.md.txt#polylines) object. The symbol's shape is defined by a path using [SVG path notation](http://www.w3.org/TR/SVG/paths.html#PathData). 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](https://developers.google.com/maps/documentation/javascript/symbols.md.txt#properties). Several predefined symbols are available via the `SymbolPath` class. See the list [below](https://developers.google.com/maps/documentation/javascript/symbols.md.txt#predefined). ## 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`](https://developers.google.com/maps/documentation/javascript/reference.md.txt#SymbolPath) or define a custom path using [SVG path notation](http://www.w3.org/TR/SVG/paths.html#PathData). 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`](https://developers.google.com/maps/documentation/javascript/reference.md.txt#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. | ![](https://developers.google.com/static/maps/documentation/javascript/images/symbol_circle.png) | | `google.maps.SymbolPath.BACKWARD_CLOSED_ARROW` | A backward-pointing arrow that is closed on all sides. | ![](https://developers.google.com/static/maps/documentation/javascript/images/symbol_back_close.png) | | `google.maps.SymbolPath.FORWARD_CLOSED_ARROW` | A forward-pointing arrow that is closed on all sides. | ![](https://developers.google.com/static/maps/documentation/javascript/images/symbol_fore_close.png) | | `google.maps.SymbolPath.BACKWARD_OPEN_ARROW` | A backward-pointing arrow that is open on one side. | ![](https://developers.google.com/static/maps/documentation/javascript/images/symbol_back_open.png) | | `google.maps.SymbolPath.FORWARD_OPEN_ARROW` | A forward-pointing arrow that is open on one side. | ![](https://developers.google.com/static/maps/documentation/javascript/images/symbol_fore_open.png) | ## Add a symbol to a marker To display a vector-based icon on an [`AdvancedMarkerElement`](https://developers.google.com/maps/documentation/javascript/advanced-markers/overview.md.txt), use an [`SVG`](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/svg) XML element. The following example shows how to append an SVG XML element to an `AdvancedMarkerElement`. ### TypeScript ```typescript const parser = new DOMParser(); // A marker with a custom inline SVG. const pinSvgString = ''; const pinSvg = parser.parseFromString( pinSvgString, 'image/svg+xml' ).documentElement; const pinSvgMarker = new AdvancedMarkerElement({ position: { lat: 37.42475, lng: -122.094 }, title: 'A marker using a custom SVG image.', anchorLeft: '-50%', anchorTop: '-50%', }); pinSvgMarker.append(pinSvg); mapElement.append(pinSvgMarker); ``` ### JavaScript ```javascript const parser = new DOMParser(); // A marker with a custom inline SVG. const pinSvgString = ''; const pinSvg = parser.parseFromString( pinSvgString, 'image/svg+xml' ).documentElement; const pinSvgMarker = new AdvancedMarkerElement({ position: { lat: 37.42475, lng: -122.094 }, title: 'A marker using a custom SVG image.', anchorLeft: '-50%', anchorTop: '-50%', }); pinSvgMarker.append(pinSvg); mapElement.append(pinSvgMarker); ``` > [!NOTE] > Markers support the use of raster images as well as vector images. See [Create markers with graphics](https://developers.google.com/maps/documentation/javascript/advanced-markers/graphic-markers.md.txt). ## 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`](https://developers.google.com/maps/documentation/javascript/reference.md.txt#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'. > [!NOTE] > **Note:** If your polyline is geodesic (that is, if its `geodesic` property is set to `true`) the distances specified for both `offset` and `repeat` are calculated in meters by default. Setting either `offset` or `repeat` to a pixel value will cause the distances to be calculated in pixels on the screen. 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. ```javascript // 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](https://developers.google.com/maps/documentation/javascript/examples/overlay-symbol-arrow.md.txt) ### 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. ```javascript // 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](https://developers.google.com/maps/documentation/javascript/examples/overlay-symbol-dashed.md.txt) ### Custom paths Custom symbols allow you to add many different shapes to a polyline. ```javascript // 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](https://developers.google.com/maps/documentation/javascript/examples/overlay-symbol-custom.md.txt) ## 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 ```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; ``` > [!NOTE] > **Note:** Read the [guide](https://developers.google.com/maps/documentation/javascript/using-typescript.md.txt) on using TypeScript and Google Maps. ### JavaScript ```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; ``` > [!NOTE] > **Note:** The JavaScript is compiled from the TypeScript snippet. [View example](https://developers.google.com/maps/documentation/javascript/examples/overlay-symbol-animate.md.txt)