Skip to content

Measure

Measure distances and areas on the map — distance lines, freehand lines, polygon areas, and freehand areas — with live totals, on-map segment + total labels, and a measurements list. Built on @mapbox/mapbox-gl-draw and Turf.js.

  • id: measure
  • Surfaces: top-bar (the UI is too large for a map-corner pop-out)

Place it

topBarWidgets: [{ widgetName: 'measure' }],

Behavior

  • Pick a tool, then click to measure; the running total updates live.
  • Per-feature total labels (and optional per-edge segment labels) render on the map.
  • A measurements list lets you review and clear individual measurements.
  • Each control's initial state comes from config; the user can change it at runtime, and changes persist across close/reopen for the page session.

Configuration — settings.measure

measure: {
  persistOnClose: false,
  showTotal: true,
  showEdgeLabels: false,
  defaultLinearUnit: 'kilometers',
  defaultAreaUnit: 'square-kilometers',
  precision: 2,
  // linearUnits: ['kilometers', 'miles', 'meters'],
  // areaUnits: ['square-kilometers', 'square-miles', 'acres'],
},
Field Type Default Description
persistOnClose boolean false Keep finished measurements on the map after closing the widget (they rehydrate when reopened); when true, they stay as a static overlay
showTotal boolean true Show the per-feature total length/area label
showEdgeLabels boolean false Show per-edge segment length labels
defaultLinearUnit 'miles' \| 'kilometers' \| 'meters' \| 'feet' \| 'yards' 'kilometers' Starting distance unit
defaultAreaUnit 'acres' \| 'square-miles' \| 'square-kilometers' \| 'square-meters' \| 'square-feet' \| 'hectares' 'square-kilometers' Starting area unit
precision number 2 Decimal places on readouts + map labels
linearUnits LinearUnit[] all Restrict + order the distance-unit dropdown
areaUnits AreaUnit[] all Restrict + order the area-unit dropdown