React Google Maps Measure Tool

A comprehensive React TypeScript library for adding measurement tools to Google Maps using @vis.gl/react-google-maps.

Features

• 📏 Distance Measurement: Interactive polyline distance measurement with segment labels
• 📐 Area Measurement: Polygon area measurement with visual overlays
• 🎯 Interactive Markers: Clickable measurement points with customizable styling
• 🔄 Unit Support: Metric (m, km, sq m, sq km) and Imperial (ft, mi, sq ft, acres) units
• 🎨 Customizable Styling: Colors, stroke weights, fill opacity, and CSS classes
• 🪝 React Hooks: useMeasure hook for custom implementations
• 📱 TypeScript: Full type safety and IntelliSense support
• 🎛️ Individual Components: Use DistanceDisplay, AreaDisplay, and MeasureMarker separately
• 📊 Real-time Updates: Live measurement updates as you add/remove points
• 🗑️ Point Management: Add, remove, and undo measurement points

Installation

npm install react-google-maps-measure-tool

Peer Dependencies

This library requires the following peer dependencies:

npm install react react-dom @vis.gl/react-google-maps

CSS Import

Import the default styles in your application:

import 'react-google-maps-measure-tool/dist/styles.css';

Or import from source for customization:

import 'react-google-maps-measure-tool/src/styles/index.css';

Basic Usage

import React from 'react';
import { APIProvider, Map } from '@vis.gl/react-google-maps';
import { MeasureTool } from 'react-google-maps-measure-tool';
import 'react-google-maps-measure-tool/dist/styles.css';

function App() {
  return (
    <APIProvider apiKey="your-google-maps-api-key">
      <Map
        defaultCenter={{ lat: 37.7749, lng: -122.4194 }}
        defaultZoom={10}
        mapId="your-map-id"
      >
        <MeasureTool
          mode="distance"
          unit="metric"
          strokeColor="#FF0000"
          markerColor="#FF0000"
          onMeasureComplete={(result) => {
            console.log('Measurement:', result);
          }}
          style={{
            position: 'absolute',
            top: '10px',
            left: '10px',
          }}
        />
      </Map>
    </APIProvider>
  );
}

API Reference

MeasureTool Component

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | mode | 'distance' \| 'area' | 'distance' | Measurement mode | | unit | 'metric' \| 'imperial' | 'metric' | Unit system | | onMeasureComplete | (result: MeasureResult) => void | - | Called when measurement is completed | | onMeasureChange | (result: MeasureResult) => void | - | Called when measurement changes | | className | string | - | CSS class name | | style | React.CSSProperties | - | Inline styles | | strokeColor | string | '#4285F4' | Color for lines and polygon borders | | fillColor | string | '#4285F4' | Fill color for polygons | | markerColor | string | '#4285F4' | Color for measurement point markers |

useMeasure Hook

For custom implementations:

import { useMeasure } from 'react-google-maps-measure-tool';

function CustomMeasureTool() {
  const {
    points,
    isActive,
    currentResult,
    addPoint,
    removeLastPoint,
    removePointAtIndex,
    startMeasure,
    completeMeasure,
    clearMeasure,
  } = useMeasure({
    mode: 'distance',
    unit: 'metric',
    onMeasureComplete: (result) => console.log('Done:', result),
    onMeasureChange: (result) => console.log('Changed:', result),
  });

  // Your custom implementation
}

Types

interface MeasurePoint {
  lat: number;
  lng: number;
}

interface MeasureResult {
  distance?: number; // in meters
  area?: number; // in square meters
  points: MeasurePoint[];
}

type MeasureMode = 'distance' | 'area';
type MeasureUnit = 'metric' | 'imperial';

Examples

Distance Measurement

<MeasureTool
  mode="distance"
  unit="metric"
  strokeColor="#FF0000"
  markerColor="#FF0000"
  onMeasureComplete={(result) => {
    console.log(`Distance: ${result.distance} meters`);
  }}
/>

Area Measurement

<MeasureTool
  mode="area"
  unit="imperial"
  fillColor="rgba(255, 0, 0, 0.3)"
  strokeColor="#FF0000"
  markerColor="#FF0000"
  onMeasureComplete={(result) => {
    console.log(`Area: ${result.area} square meters`);
  }}
/>

Using Individual Components

import { DistanceDisplay, AreaDisplay, MeasureMarker } from 'react-google-maps-measure-tool';

// Display a distance line
<DistanceDisplay
  start={{ lat: 37.7749, lng: -122.4194 }}
  end={{ lat: 37.7849, lng: -122.4094 }}
  label="5.2 km"
  strokeColor="#0000FF"
  strokeWeight={3}
/>

// Display an area polygon
<AreaDisplay
  points={[
    { lat: 37.7749, lng: -122.4194 },
    { lat: 37.7849, lng: -122.4094 },
    { lat: 37.7949, lng: -122.4294 },
  ]}
  label="2.5 sq km"
  fillColor="rgba(0, 0, 255, 0.3)"
  strokeColor="#0000FF"
/>

// Display custom markers
<MeasureMarker
  position={{ lat: 37.7749, lng: -122.4194 }}
  label="Start Point"
  color="#0000FF"
  size={12}
  onClick={() => console.log('Marker clicked')}
/>

Advanced Usage with State Management

import React, { useState } from 'react';
import { MeasureTool, MeasureResult } from 'react-google-maps-measure-tool';

function AdvancedMeasureTool() {
  const [measurements, setMeasurements] = useState<MeasureResult[]>([]);
  const [currentMode, setCurrentMode] = useState<'distance' | 'area'>('distance');

  const handleMeasureComplete = (result: MeasureResult) => {
    setMeasurements(prev => [...prev, result]);
  };

  const clearAllMeasurements = () => {
    setMeasurements([]);
  };

  return (
    <div>
      <div style={{ marginBottom: '10px' }}>
        <button onClick={() => setCurrentMode('distance')}>Distance Mode</button>
        <button onClick={() => setCurrentMode('area')}>Area Mode</button>
        <button onClick={clearAllMeasurements}>Clear All</button>
      </div>
      
      <MeasureTool
        mode={currentMode}
        unit="metric"
        onMeasureComplete={handleMeasureComplete}
        strokeColor={currentMode === 'distance' ? '#FF0000' : '#00FF00'}
        fillColor={currentMode === 'area' ? 'rgba(0, 255, 0, 0.3)' : undefined}
      />
      
      <div>
        <h3>Completed Measurements: {measurements.length}</h3>
        {measurements.map((measurement, index) => (
          <div key={index}>
            {measurement.distance && `Distance: ${(measurement.distance / 1000).toFixed(2)} km`}
            {measurement.area && `Area: ${(measurement.area / 1000000).toFixed(2)} sq km`}
          </div>
        ))}
      </div>
    </div>
  );
}

Development

# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm test

# Lint code
npm run lint

License

MIT