Google Maps - Symbols

Google Maps - Using Symbols

Symbols provide a way to use predefined vector paths (like circles or arrows) or custom SVG paths as icons for markers or decorations on polylines. They offer flexibility in styling and can scale without losing quality.

The `google.maps.Symbol` Interface

A symbol is defined by an object literal conforming to the google.maps.Symbol interface. Key properties include:

path: Defines the shape of the symbol. This can be:

- A predefined path from `google.maps.SymbolPath` (e.g., `CIRCLE`, `FORWARD_CLOSED_ARROW`).

- An SVG path string (e.g., `'M 0,0 L 10,10 Z'`).

scale: The amount by which to scale the symbol’s size (a number).
fillColor: Fill color (e.g., '#FF0000', 'blue').
fillOpacity: Fill opacity (0.0 to 1.0).
strokeColor: Border color.
strokeOpacity: Border opacity.
strokeWeight: Border thickness in pixels.
rotation: Angle of rotation in degrees (clockwise).
anchor: The position of the symbol relative to its LatLng coordinate (e.g., new google.maps.Point(0, 0) for top-left). Relevant when used as a marker icon.
labelOrigin: The origin of the label (if used) relative to the symbol’s anchor. Relevant for marker labels.

Predefined Symbol Paths (`google.maps.SymbolPath`)

The API provides several built-in vector paths:

CIRCLE: A circle.
FORWARD_CLOSED_ARROW: A solid forward-pointing arrow.
FORWARD_OPEN_ARROW: An open forward-pointing arrow (chevron).
BACKWARD_CLOSED_ARROW: A solid backward-pointing arrow.
BACKWARD_OPEN_ARROW: An open backward-pointing arrow.

You need to import SymbolPath from the core library: const { SymbolPath } = await google.maps.importLibrary("core");

Using Symbols as Marker Icons

Instead of providing a URL for the marker’s icon property, provide a Symbol object literal.

Example: Using a Backward Arrow Symbol for a Marker

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Symbol as Marker Icon</title>
    <style>#map { height: 400px; width: 100%; } html, body { height: 100%; margin: 0; padding: 0; }</style>
</head>
<body>
    <div id="map"></div>
    <script>
        async function initMap() {
            const mapCenter = { lat: 17.4330, lng: 78.4121 }; // Hyderabad area
            const { Map } = await google.maps.importLibrary("maps");
            const { Marker } = await google.maps.importLibrary("marker");
            const { SymbolPath } = await google.maps.importLibrary("core"); // Import SymbolPath

            const map = new Map(document.getElementById("map"), {
                zoom: 14,
                center: mapCenter,
                mapId: "DEMO_MAP_ID"
            });

            // Define the symbol
            const arrowSymbol = {
                path: SymbolPath.BACKWARD_CLOSED_ARROW,
                scale: 6,              // Make it larger
                fillColor: '#B40404',  // Dark red fill
                fillOpacity: 0.8,
                strokeColor: '#8A0808', // Darker border
                strokeWeight: 2,
                rotation: 0            // Pointing left (default)
            };

            // Create the marker using the symbol as its icon
            const marker = new Marker({
                position: mapCenter,
                map: map,
                icon: arrowSymbol,     // <-- Use the symbol object here
                title: 'Backward Arrow Symbol',
                draggable: true        // Make it draggable if desired
            });
        }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly&libraries=marker,core" async defer></script>
     <!-- Added libraries=marker,core -->
</body>
</html>

Expected Output: A map showing the Hyderabad area with a dark red, backward-pointing arrow marker at the center.

Animating Symbol Markers

Markers using symbols as icons can be animated just like regular markers using the animation property (DROP or BOUNCE).

Example: Adding Drop Animation to the Symbol Marker

Modify the marker creation in the previous example:

// ... inside initMap, after defining arrowSymbol ...
// Import Animation: const { Animation } = await google.maps.importLibrary("maps");

const marker = new google.maps.Marker({
    position: mapCenter,
    map: map,
    icon: arrowSymbol,
    title: 'Dropping Arrow Symbol',
    animation: google.maps.Animation.DROP // <-- Add animation
});

You would also need to import Animation from the maps library: const { Animation } = await google.maps.importLibrary("maps"); and add maps to the libraries in the script URL.

Expected Output: The arrow marker will appear to drop onto the map when loaded.

Using Symbols on Polylines

Symbols can be attached to polylines to indicate direction or add decoration. This is done using the icons property within PolylineOptions. The icons property takes an array of google.maps.IconSequence objects.

Key `IconSequence` Properties:

icon: The Symbol object to display.
offset: Distance from the start of the line where the symbol should appear (e.g., '0%', '50px', '100%').
repeat: Distance between repeated symbols along the line (e.g., '20px', '10%'). If set, the symbol repeats.
fixedRotation: If true, the symbol’s rotation is fixed relative to the screen; if false (default), it rotates with the line.

Example: Adding Arrows to a Polyline

<!DOCTYPE html>
<!-- ... head ... -->
<body>
    <div id="map"></div>
    <script>
        async function initMap() {
            const mapCenter = { lat: 40.7, lng: -74 }; // NYC area
            const { Map } = await google.maps.importLibrary("maps");
            const { SymbolPath } = await google.maps.importLibrary("core");

            const map = new Map(document.getElementById("map"), {
                zoom: 12,
                center: mapCenter,
                mapId: "DEMO_MAP_ID"
            });

            const pathCoords = [
                { lat: 40.71, lng: -74.01 }, { lat: 40.72, lng: -73.99 },
                { lat: 40.73, lng: -74.00 }, { lat: 40.74, lng: -73.98 }
            ];

            // Define the arrow symbol
            const arrowSymbol = {
                path: SymbolPath.FORWARD_OPEN_ARROW,
                scale: 3,
                strokeColor: '#0000FF',
                strokeWeight: 2
            };

            // Create the polyline with the arrow icon sequence
            const polyline = new google.maps.Polyline({
                path: pathCoords,
                strokeColor: '#FF0000',
                strokeOpacity: 0.8,
                strokeWeight: 2,
                map: map,
                icons: [{
                    icon: arrowSymbol,
                    offset: '50%', // Place one arrow at the midpoint
                }, {
                    icon: arrowSymbol,
                    offset: '0%',   // Start arrow
                    repeat: '100px' // Repeat every 100 pixels
                }]
            });
        }
    </script>
    <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly&libraries=core" async defer></script>
    <!-- Added libraries=core -->
</body>
</html>

Expected Output: A red polyline on the map with blue open arrows placed along it. One arrow is fixed at the 50% mark, and others repeat every 100 pixels starting from the beginning.

Custom SVG Paths

For complete control, you can define your symbol’s shape using SVG path notation in the path property.

const customSymbol = {
    path: 'M -5,0 L 5,0 L 0,5 Z', // Simple triangle SVG path data
    scale: 4,
    fillColor: 'green',
    fillOpacity: 1,
    strokeWeight: 1
};

This custom symbol can then be used as a marker icon or on a polyline just like the predefined ones.