Constructor
Optionaloptions: MeasureControlOptions
Plugin control options
Protected_Protected Optional_Protected_Protected OptionalcontrolProtecteddefaultProtectedeventsProtected OptionalmapProtectedmodeProtectedoptionsProtected OptionalterradrawThe precision of area value. Using setter to override the value if you want.
Default is undefined. If undefined is set, the unit is converted automatically based on the value.
For metric system:
For imperial system:
If a specific unit is specified (e.g., 'square meters', 'square kilometers', 'ares', 'hectares', 'square feet', 'square yards', 'acres', 'square miles'), the value is always returned in that unit.
Custom conversion function can be also set to this property.
The function receives the area value in square meters and should return an object with area and unit properties.
An example of custom conversion function:
const customConversion: AreaUnitCallBackType = (valueInSquareMeters) => {
if (valueInSquareMeters >= 1000) {
return { area: valueInSquareMeters / 1000, unit: 'km²' };
} else {
return { area: valueInSquareMeters, unit: 'm²' };
};
control.areaUnit = customConversion;
The flag of whether computing elevation. Default is false. Using setter to override the value if you want.
ProtectedcssCSS prefix for the control buttons. Default is empty string
The precision of distance value. It will be set different value when distance unit is changed. Using setter to override the value if you want.
Default is undefined. If undefined is set, the unit is converted automatically based on the value.
For metric system:
For imperial system:
If a specific unit is specified (e.g., 'km', 'm', 'cm', 'mi', 'ft', 'in'), the value is always returned in that unit.
Custom conversion function can be also set to this property.
The function receives the distance value in meters and should return an object with distance and unit properties.
An example of custom conversion function:
const customConversion: DistanceUnitCallBackType = (valueInMeter) => {
if (valueInMeter >= 1000) {
return { distance: valueInMeter / 1000, unit: 'km' };
} else {
return { distance: valueInMeter, unit: 'm' };
};
};
control.distanceUnit = customConversion;
Get/Set font glyph for measure control layers
As default, this maesure control uses maplibre's default font glyphs(Open Sans Regular,Arial Unicode MS Regular) described at https://maplibre.org/maplibre-style-spec/layers/#text-font
If you are using your own maplibre style or different map privider, you probably need to set the font glyphs to match your maplibre style.
Font glyph availability depends on what types of glyphs are supported by your maplibre style (e.g., Carto, Openmap tiles, Protomap, Maptiler, etc.) Please make sure the font glyphs are available in your maplibre style.
Usage:
const drawControl = new MaplibreMeasureControl()
drawControl.fontGlyphs = ['Open Sans Italic']
map.addControl(drawControl)
Get/Set font glyph for the TextMode label layer ({prefix}-text-labels).
As default, the TextMode label uses sans-serif so it is not constrained by the
glyphs available in your maplibre style. See https://maplibre.org/maplibre-style-spec/layers/#text-font
If you are using your own maplibre style or a different map provider, you probably need to set the font glyphs to match glyphs available in your maplibre style.
Font glyph availability depends on what types of glyphs are supported by your maplibre style (e.g., Carto, Openmap tiles, Protomap, Maptiler, etc.). Please make sure the font glyphs are available in your maplibre style.
Usage:
const drawControl = new MaplibreTerradrawControl({ modes: ['text'] })
drawControl.fontGlyphs = ['Open Sans Italic']
map.addControl(drawControl)
get the state of whether the control is expanded or collapsed
set the state of the control either expanded or collapsed.
terradraw mode will be reset if the state is changed.
either expanded or collapsed event is dispatched when changed
Measure unit symbols. If you want to change the default symbol, please overwrite the symbol by this option.
The unit of measurement can be metric or imperial. Default is metric. The measuring result will be recalculated once new value is set
Show delete confirmation popup when deleting features if true. Default is false
Set show delete confirmation popup when deleting features if true. Default is false
Activate Terra Draw to start drawing
ProtectedaddProtectedaddAdd Text Label Terradraw Features to the map
Optionalstyles: TextModeStylingProtectedapplyApply the given font glyphs to the provided symbol layer specs and, when they already
exist on the map, to their live layers via setLayoutProperty.
Shared by subclasses (e.g. MaplibreMeasureControl, MaplibreValhallaControl) so their
fontGlyphs setters can reuse the same layer-update logic.
font glyph names to apply as text-font
symbol layer specs to update (undefined entries are skipped)
clean maplibre style to filter only for terradraw related layers or without them. If options are not set, returns original style given to the function.
This can be useful incase users only want to get terradraw related layers or without it.
Usage:
cleanStyle(map.getStyle, { excludeTerraDrawLayers: true})
cleanStyle(map.getStyle, { onlyTerraDrawLayers: true})
maplibre style spec
Optionaloptions: { excludeTerraDrawLayers?: boolean; onlyTerraDrawLayers?: boolean }
OptionalexcludeTerraDrawLayers?: booleanreturn maplibre style without terradraw layers and sources
OptionalonlyTerraDrawLayers?: booleanreturn maplibre style with only terradraw layers and sources
ProtectedclearClear GeoJSON feature related to extended control such as measure and valhalla by TerraDraw feature ID
the array of source ID to delete
the array of feature ID. Optional, if undefined, delete all labels for source
void
ProtectedclearRemove the {prefix}-text-labels symbol layer and the {prefix}-text
GeoJSON source from the map.
Called when all features are deleted via handleDeleteAllFeatures.
ProtectedcreateCreate (or refresh) the MapLibre GL symbol layer used to render committed
text labels from TerraDrawTextMode.
Called automatically by onAdd when the text mode is active, and
again after every TerraDraw finish event so newly committed labels appear
immediately.
properties.mode === 'text' and properties.text is non-empty).{prefix}-text GeoJSON source already exists, calls setData
to update it in place (no layer teardown/rebuild).{prefix}-text-labels symbol layer with defaults for
text-field, text-size, text-font, text-color, and text-halo-*.map.moveLayer('{prefix}-text-labels') to ensure the symbol
layer renders above all other TerraDraw layers.The {prefix} comes from adapterOptions.prefixId (default 'td'),
so with the default prefix the layer id is td-text-labels.
The MapLibre GL Map instance.
Optionalstyles: TextModeStyling
Optional style overrides forwarded to the MapLibre symbol layer.
Deactivate Terra Draw to stop drawing
ProtecteddeleteProtecteddispatchDispatch an event. Pass the current snapshot of features and mode
event type
Optionalargs: { [key: string]: unknown }
additional arguments
Get the default control position
default control position. Default is 'top-right'
get GeoJSON features
If true, returns only selected features. Default is false.
FeatureCollection in GeoJSON format
Get the Terra Draw instance. For the Terra Draw API, please refer to https://terradraw.io/#/api
Terra Draw instance with additional extensions for the plugin control
ProtectedgetResolve text mode styles by merging defaults and user overrides.
ProtectedhandleDelete all features from the store
ProtectedhandleDelete selected features from the store
ProtectedhandleDownload button click event handler
ProtectedhandleHandle the history event from TerraDraw to update undo/redo button states
HistoryEvent from TerraDraw
ProtectedhandleHandle mode change operations that should be executed after setMode is called
The active mode name
The Terra Draw instance
The result of the setMode operation
add the plugin control to maplibre
Maplibre Map object
HTML Element
Remove the plugin control from maplibre
void
Recalculate area and distance in TerraDraw snapshot
if you use addFeatures to restore GeoJSON features to TerraDraw, this recalc method needs to be called to re-measure again.
For example, the below code is an example usage.
drawInstance?.addFeatures(initData);
map?.once('idle', ()=>{
drawControl.recalc()
})
Reset active mode to back to render mode
ProtectedresetRestore the default paint properties on the {prefix}-text-labels layer
after a text feature is deselected.
Resets text-color, text-halo-color, and text-halo-width from
TextModeStyling defaults. Also refreshes the GeoJSON source to clear
the TerraDraw selected flag from the feature data.
Called automatically on terradraw.on('deselect').
ProtectedselectApply highlighted styles to the {prefix}-text-labels layer when a text
feature is selected via TerraDrawSelectMode.
Refreshes the GeoJSON source so the TerraDraw selected property is
current, then sets data-driven text-size and text-halo-color expressions
that make the selected label slightly larger and give it a white halo.
If the selected feature is not a text feature, delegates to
resetTextLabelLayer instead.
Called automatically on terradraw.on('select').
The TerraDraw feature ID that was selected.
ProtectedshowShow delete confirmation dialog.
Callback function that will be invoked when the user confirms deletion by clicking the "Delete" button in the dialog; typically used to delete all features before the dialog is closed.
Optional dialog title. Defaults to 'Delete All Features'.
Optional dialog message. Defaults to 'Are you sure you want to delete all features?'.
ProtectedsyncSynchronize button states with the current Terra Draw mode
The active mode name
ProtectedtoggleToggle the state of buttons when there is no features
ProtectedtoggleToggle the state of delete-select button
ProtectedtoggleToggle editor control
Maplibre GL Terra Draw Measure Control