<Polygon> Component

React component to display a Polygon on the map.

Usage

import React from 'react';
import {APIProvider, Map, Polygon} from '@vis.gl/react-google-maps';

const App = () => (
  <APIProvider apiKey={'Your API key here'}>
    <Map zoom={12} center={{lat: 53.54992, lng: 10.00678}}>
      <Polygon
        paths={[
          {lat: 53.54, lng: 10.0},
          {lat: 53.55, lng: 10.02},
          {lat: 53.56, lng: 10.01}
        ]}
        fillColor={'#0088ff'}
        fillOpacity={0.3}
        strokeColor={'#0088ff'}
        strokeWeight={2}
      />
    </Map>
  </APIProvider>
);

export default App;

Props

The PolygonProps interface extends the google.maps.PolygonOptions interface and includes all possible options available for a Polygon.

Controlled / Uncontrolled (for Editable Polygons)

The distinction between controlled and uncontrolled usage patterns is only relevant when the polygon is editable or draggable. When a polygon is editable, the Google Maps API automatically adds handles to the vertices on the map and handles all mouse events for those handles internally, allowing users to modify the shape directly.

// Uncontrolled - initial value only, users can edit freely
<Polygon
    defaultPaths={[[{lat: 53.5, lng: 10}, {lat: 53.6, lng: 10.1}, {
        lat: 53.5,
        lng: 10.2
    }]]}
    editable
/>

// Controlled - value always reflects props
<Polygon paths={paths} editable/>

When using controlled props with editable or draggable, you must use the onPathsChanged callback to sync state, otherwise the polygon will snap back to its original position:

const [paths, setPaths] = useState([
  [
    {lat: 53.5, lng: 10},
    {lat: 53.6, lng: 10.1},
    {lat: 53.5, lng: 10.2}
  ]
]);

<Polygon
  paths={paths}
  editable
  draggable
  onPathsChanged={newPaths =>
    setPaths(newPaths.map(p => p.map(pt => pt.toJSON())))
  }
/>;

Path Props

polygon: google.maps.Polygon

An existing google.maps.Polygon instance to use instead of creating a new one. When provided, all other props (paths, options, event handlers) will still be applied to this instance.

const polygonInstance = new google.maps.Polygon();

// Minimal usage - just add existing instance to the map
<Polygon polygon={polygonInstance}/>

// Apply additional props to the existing instance
<Polygon
    polygon={polygonInstance}
    fillColor={'#0088ff'}
    fillOpacity={0.3}
    onClick={(e) => console.log('clicked')}
/>

paths: Array<Array<google.maps.LatLng | google.maps.LatLngLiteral>>

The controlled paths of the polygon.

defaultPaths:

Array<Array<google.maps.LatLng | google.maps.LatLngLiteral>>

The initial paths of the polygon (uncontrolled).

// Simple polygon
<Polygon paths={[
    {lat: 53.54, lng: 10.0},
    {lat: 53.55, lng: 10.02},
    {lat: 53.56, lng: 10.01}
]}/>

// Polygon with hole
<Polygon paths={[
    // Outer path
    [{lat: 53.54, lng: 10.0}, {lat: 53.55, lng: 10.02}, {
        lat: 53.56,
        lng: 10.01
    }],
    // Inner path (hole)
    [{lat: 53.545, lng: 10.005}, {lat: 53.55, lng: 10.015}, {
        lat: 53.555,
        lng: 10.008
    }]
]}/>

encodedPaths: string[]

An array of encoded polyline strings. When provided, will be decoded and used as the paths. Takes precedence over the paths prop if both are specified.

<Polygon
  encodedPaths={['_p~iF~ps|U_ulLnnqC_mqNvxq`@', 'gg~iF~|s|UaaJhMcBxY']}
  fillColor={'#0088ff'}
  fillOpacity={0.3}
/>

note

When using encodedPaths, the geometry library will be automatically loaded.

Event Props

onClick: (e: google.maps.MapMouseEvent) => void

Called when the polygon is clicked.

onDrag: (e: google.maps.MapMouseEvent) => void

Called repeatedly while the polygon is being dragged.

onDragStart: (e: google.maps.MapMouseEvent) => void

Called when dragging of the polygon begins.

onDragEnd: (e: google.maps.MapMouseEvent) => void

Called when dragging of the polygon ends.

onMouseOver: (e: google.maps.MapMouseEvent) => void

Called when the mouse enters the polygon.

onMouseOut: (e: google.maps.MapMouseEvent) => void

Called when the mouse leaves the polygon.

onPathsChanged: (paths: google.maps.LatLng[][]) => void

Called when the paths are changed (via dragging or editing vertices).

Style Props

All styling options from google.maps.PolygonOptions are supported:

• fillColor: string
• fillOpacity: number
• strokeColor: string
• strokeOpacity: number
• strokeWeight: number
• geodesic: boolean - When true, edges of the polygon are interpreted as geodesic arcs

Behavior Props

• clickable: boolean - Whether the polygon handles mouse events
• draggable: boolean - Whether the polygon can be dragged
• editable: boolean - Whether the polygon can be edited
• visible: boolean - Whether the polygon is visible
• zIndex: number - The z-index of the polygon

Automatic Property Inference

The clickable, draggable, and editable properties are automatically inferred based on the presence of event handlers:

• clickable is automatically set to true when onClick is provided
• draggable is automatically set to true when onDrag, onDragStart, onDragEnd, or onPathsChanged is provided
• editable is automatically set to true when onPathsChanged is provided

This means you don't need to explicitly set these properties in most cases You can still explicitly set these properties to override the automatic inference, including setting them to false to disable the behavior even when handlers are present.

Extracting the Polygon Instance

You can access the underlying google.maps.Polygon instance via a ref:

const polygonRef = useRef<google.maps.Polygon>(null);

<Polygon
  ref={polygonRef}
  paths={[
    {lat: 53.54, lng: 10.0},
    {lat: 53.55, lng: 10.02},
    {lat: 53.56, lng: 10.01}
  ]}
/>;