The TerraDrawTextMode allows users to place, edit, and drag freeform text labels on a MapLibre GL map. It creates Point GeoJSON features with a text property. The MaplibreTerradrawControl automatically renders these as a symbol layer using MapLibre's native text styling.
Interaction Model
| Gesture | Behaviour |
|---|
| Click on the map | Opens a textarea popup at the clicked location. |
| Enter (or Submit button) | Commits the label as a Point feature with a text property. Calls onTextCommit and fires the TerraDraw finish event. |
| Shift+Enter | Inserts a newline without committing. |
| Escape (in popup) | Dismisses the popup and deletes the uncommitted feature. |
| Click outside open popup | Commits any typed text, or dismisses if empty. |
| Click near existing label | Opens the textarea pre-filled with existing text (requires editable: true). |
| Drag a committed label | Handled by TerraDrawSelectMode when flags.text.feature.draggable is true. |
Implementation Example
import { MaplibreTerradrawControl, TerraDrawTextMode } from '@watergis/maplibre-gl-terradraw';
const control = new MaplibreTerradrawControl({
modes: ['text', 'select', 'delete'],
modeOptions: {
text: new TerraDrawTextMode({
editable: true,
placeholder: 'Add a label…',
styles: {
textColor: '#1a1a1a',
textSize: 14,
textSelectedSize: 16,
textHaloColor: '#ffffff',
textHaloWidth: 2,
textSelectedHaloColor: '#E0B03F'
},
onTextCommit: (id, text) => console.log(`${id}: ${text}`),
}),
},
});
map.addControl(control, 'top-right');
import { MaplibreTerradrawControl, TerraDrawTextMode } from '@watergis/maplibre-gl-terradraw';
const control = new MaplibreTerradrawControl({
modes: ['text', 'select', 'delete'],
modeOptions: {
text: new TerraDrawTextMode({
editable: true,
placeholder: 'Add a label…',
styles: {
textColor: '#1a1a1a',
textSize: 14,
textSelectedSize: 16,
textHaloColor: '#ffffff',
textHaloWidth: 2,
textSelectedHaloColor: '#E0B03F'
},
onTextCommit: (id, text) => console.log(`${id}: ${text}`),
}),
},
});
map.addControl(control, 'top-right');
