@element-editor/react@element-editor/react

npm install @element-editor/react maplibre-gl

import '@element-editor/react/style.css'

import { ElementEditor } from '@element-editor/react'

<div style={{ width: '100%', height: '600px' }}>
  <ElementEditor onChange={(data) => console.log(data)} />
</div>

import { ElementEditor, type FeatureStyle, type GeoJSONFeature } from '@element-editor/react'

// Module-level, so it stays stable across renders.
const byStatus = (f: GeoJSONFeature): FeatureStyle | null =>
  f.properties.status === 'done' ? { color: '#16a34a' } : null

<ElementEditor featureColor="#00a2f0" getFeatureStyle={byStatus} />

interface ElementEditorRef {
  /** Returns the current FeatureCollection. `_validation` is stripped. */
  getFeatureCollection: () => FeatureCollection
  /** One feature by id, as getFeatureCollection() would return it (hidden ones too); null if unknown. */
  getFeature: (id: string) => GeoJSONFeature | null
  /**
   * Replaces all data (like importGeoJSON(data, 'replace')). Fires onChange (and onFeatureAdd /
   * onFeatureDelete) and is one undo step, unless options say otherwise: { silent: true } for
   * data loaded from your backend, { undoable: false } to also clear the undo history.
   */
  setFeatureCollection: (data: FeatureCollectionInput, options?: SetFeatureCollectionOptions) => void
  /** Returns the current FeatureCollection serialised as GeoJSON text. */
  exportGeoJSON: () => string
  /** Triggers a `features.geojson` file download. */
  exportAs: (format: 'geojson') => void
  /**
   * Imperatively load a FeatureCollection. `mode` defaults to `'replace'`.
   * One undo step: undo restores the previous features, schemas and groups (no file backup).
   * Returns counts of skipped (unsupported geometry) / duplicate (repeated id) /
   * truncated (capped by the internal 50,000-feature limit) features.
   */
  importGeoJSON: (
    raw: FeatureCollectionInput | unknown,
    mode?: 'replace' | 'merge',
  ) => ImportResult
  /**
   * Adds a feature; returns it as stored (with its `id`: a missing one gets a UUID), or `null`
   * when nothing was added (invalid geometry, id already used, `maxFeatures` reached). Goes on
   * top of the layer list; the selection is left alone; `groupId` is kept if the group exists.
   */
  addFeature: (feature: GeoJSONFeatureInput, options?: MutationOptions) => GeoJSONFeature | null
  /**
   * Updates one feature. A patch may set `properties` (replaces the object), `geometry`,
   * `schemaId` or `hidden`; other keys are ignored; the feature is re-validated.
   * Returns `false` (nothing changed) for an unknown id or a malformed patch.
   */
  updateFeature: (id: string, patch: FeaturePatch, options?: MutationOptions) => boolean
  /**
   * `updateFeature` for many features in one commit: one store update, one onChange,
   * onFeatureUpdate once per feature whose geometry or properties changed, one undo step.
   * Unknown ids and malformed patches are skipped.
   */
  updateFeatures: (updates: { id: string; patch: FeaturePatch }[], options?: MutationOptions) => void
  /** Removes features in one undo step; returns how many were removed (unknown ids are skipped). */
  removeFeatures: (ids: string[], options?: MutationOptions) => number
  /** Ids of the selected features (a copy). */
  getSelection: () => string[]
  /**
   * Replaces the selection (`[]` clears it) and fires onSelectionChange. Unknown ids, group ids
   * and hidden features are left out. `fit: true` fits the map to the selected features.
   */
  select: (ids: string[], options?: { fit?: boolean }) => void
  /**
   * Turns a drawing tool on, like its toolbar button (another tool's unfinished shape is
   * discarded); `null` turns the active tool off. Returns `false` when the tool isn't available:
   * unknown or 'search', left out by `tools`, `maxFeatures` reached, or `readonly`
   * (every tool but 'measure').
   */
  setTool: (tool: DrawTool | null) => boolean
  /** The tool that is on (as setTool takes it), or null. Shape operations (cut, buffer, …) aren't tools: null. */
  getTool: () => DrawTool | null
  /** Whether undo() / redo() would change something. */
  canUndo: () => boolean
  canRedo: () => boolean
  /**
   * Validates every feature against its schema (required fields, number min / max) and its
   * geometry (zero-area polygons). Changes nothing, calls no callback. submit() runs the same check.
   */
  validate: () => ValidationReport
  /**
   * The map instance (`maplibregl.Map` / `L.Map`), or `null` until it has mounted (the MapLibre
   * drop-in creates it once its basemap style has loaded). Prefer the `basemap` prop or
   * `setBasemap()` to switch styles: they keep your layers. After your own `map.setStyle()`
   * Element restores its own layers.
   */
  getMap: () => maplibregl.Map | null   // L.Map | null on '@element-editor/react/leaflet'
  /** The current basemap, as passed in `basemap` / `basemaps` (`'auto'` stays `'auto'`). */
  getBasemap: () => BasemapInput         // RasterBasemap | 'osm' on '/leaflet'
  /**
   * Switches the basemap like a user pick, except that it isn't remembered for the next visit.
   * Fires `onBasemapChange`. With a controlled `basemap` it only fires `onBasemapChange`.
   */
  setBasemap: (basemap: BasemapInput) => void
  /**
   * Flies the map to `center` (`[lng, lat]`, GeoJSON order). Defaults `zoom` to 15.
   * The older `flyTo([lat, lng], zoom?)` tuple form is deprecated: it still works and
   * logs a one-time dev warning.
   */
  flyTo: (options: { center: [number, number]; zoom?: number }) => void
  /** Sets the map zoom (no animation, clamped to min/max), keeping the current center. Returns `false` if the map isn't ready yet (nothing happened). */
  setZoom: (zoom: number) => boolean
  /**
   * Fits the map to a bbox tuple `[minLng, minLat, maxLng, maxLat]` or a list
   * of `[lng, lat]` points. No-op when the map controller isn't ready yet.
   */
  fitBounds: (target: [number, number][] | [number, number, number, number]) => void
  /**
   * Validates all features (as validate() does). Invalid: calls onValidationError with the errors
   * keyed by feature id and returns false (onSubmit is not called). Valid: calls onSubmit and returns true.
   */
  submit: () => boolean
  undo: () => void
  redo: () => void
  clearSelection: () => void
}

// What updateFeature(s) may change on a feature (exported from @element-editor/core).
type FeaturePatch = Partial<Pick<GeoJSONFeature, 'properties' | 'geometry' | 'schemaId' | 'hidden'>>

interface MutationOptions {
  // Default true: one undo step, like the same edit by the user. false (e.g. applying a change
  // from your server): no undo step, and the change is also written into the undo/redo history,
  // so the user undoing an earlier edit doesn't revert it.
  undoable?: boolean
}

interface SetFeatureCollectionOptions {
  // Default false: the load fires onChange / onFeatureAdd / onFeatureUpdate / onFeatureDelete like any
  // change. true: it doesn't (load-from-backend → save-in-onChange won't write the data straight
  // back). onSelectionChange still fires when the load clears a selection.
  silent?: boolean
  // Default true: one undo step. false: no undo step, and the undo/redo history is cleared.
  undoable?: boolean
}

interface ValidationReport {
  valid: boolean                     // no feature has an error
  errors: Record<string, string[]>   // messages per feature id (only features with errors), as onValidationError gets them
}

interface ImportResult {
  skipped: number      // features with unsupported geometry types (or geometry: null)
  duplicates: number   // features whose `id` repeated an earlier one (in 'merge' mode, also ids already in the editor)
  truncated: boolean   // import was capped by the internal 50,000-feature safety limit
}

import { useRef } from 'react'
import { ElementEditor, type ElementEditorRef } from '@element-editor/react'

const ref = useRef<ElementEditorRef>(null)

<ElementEditor ref={ref} />

// Read:
const data = ref.current?.getFeatureCollection()
const text = ref.current?.exportGeoJSON()
ref.current?.exportAs('geojson')          // triggers file download

// Write:
ref.current?.setFeatureCollection(newData)             // replace, no merge; fires onChange
ref.current?.setFeatureCollection(fromServer, { silent: true })  // no onChange: don't save it straight back
ref.current?.importGeoJSON(newData)                    // replace
const result = ref.current?.importGeoJSON(extra, 'merge')
console.log(result)  // { skipped, duplicates, truncated }

// Single features:
const f = ref.current?.addFeature({ type: 'Feature', geometry: { type: 'Point', coordinates: [2.35, 48.86] }, properties: { name: 'Paris' } })
ref.current?.updateFeature(f!.id, { properties: { name: 'Paris, FR' } })
ref.current?.removeFeatures([f!.id])                   // → 1

// Batch edits: one commit and one undo step for the lot, instead of one per
// feature (and a 25-step undo that would only reach the last 25).
ref.current?.updateFeatures(ids.map((id) => ({ id, patch: { properties: { ...propsOf(id), status: 'done' } } })))

// Changes from your server: not undoable, and kept when the user undoes their own edits.
ref.current?.updateFeature(id, { properties: serverProps }, { undoable: false })

// Map:
ref.current?.flyTo({ center: [2.35, 48.86], zoom: 12 })  // [lng, lat]
ref.current?.setZoom(15)
ref.current?.fitBounds([2.17, 48.70, 2.50, 48.90])     // bbox tuple
ref.current?.fitBounds([[2.35, 48.85], [-0.1, 51.5]])  // or [lng, lat] points
// flyTo, fitBounds and select({ fit: true }) frame the target in the part of the map that panels
// (layers sidebar, docked GeoJSON inspector, data table) leave visible, so map.getCenter() can differ.

// History / selection / tools:
ref.current?.undo()
ref.current?.redo()
ref.current?.canUndo()                                 // false when there is nothing to undo
ref.current?.getFeature('a')                           // the feature, or null
ref.current?.getTool()                                 // 'polygon' | … | null
ref.current?.select(['a', 'b'], { fit: true })        // select and zoom to them
ref.current?.getSelection()                            // ['a', 'b']
ref.current?.clearSelection()
ref.current?.setTool('polygon')                        // false if unavailable
ref.current?.setTool(null)                             // exit the tool

// The map itself (null until mounted):
ref.current?.getMap()?.on('moveend', save)

// Check without submitting (no callbacks):
const { valid, errors } = ref.current!.validate()      // errors: { [featureId]: string[] }
if (!valid) ref.current?.select(Object.keys(errors), { fit: true })

// Validation gate:
if (ref.current?.submit()) {
  // onSubmit fired
} else {
  // onValidationError fired
}

import { getFeatureCollectionBBox } from '@element-editor/core'

function onImport(fc) {
  ref.current?.importGeoJSON(fc, 'replace')
  const bbox = getFeatureCollectionBBox(fc)
  if (bbox) ref.current?.fitBounds(bbox)
}

<ElementEditor defaultBasemap="terrain" />                // start on Terrain
<ElementEditor basemap={bm} onBasemapChange={setBm} />    // controlled by your app
<ElementEditor basemaps={['auto', 'dark', 'osm']} />      // fewer choices
<ElementEditor basemaps={false} basemap={{ style: 'https://example.com/style.json' }} />  // your own style, no picker

npm install @element-editor/react @element-editor/adapter-leaflet leaflet react-leaflet

import { ElementEditor } from '@element-editor/react/leaflet'
import '@element-editor/react/leaflet/style.css'

<ElementEditor
  basemaps={[
    'osm',
    { id: 'esri', label: 'Satellite', url: 'https://server.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}', attribution: '© Esri' },
  ]}
/>

<ElementEditor
  initialData={parcels}
  initialView="data"                       // or { center: [14.42, 50.09], zoom: 12 } / { bounds: [w, s, e, n] }
  mapOptions={{ maxZoom: 19, pitch: 30 }}  // MapLibre options; L.MapOptions on /leaflet
  onMapReady={(map) => {
    map.addSource('districts', { type: 'geojson', data: '/districts.geojson' })
    map.addLayer({ id: 'districts', type: 'line', source: 'districts' }, 'elm-features-fill') // under Element's features
  }}
/>

interface ElementEditorConfig {
  /** Color theme. Default: 'system' (follows OS preference). */
  mode?: 'light' | 'dark' | 'system'

  /**
   * Brand accent: any CSS colour ('#ea580c', 'rebeccapurple', 'oklch(…)').
   * The whole primary 50…950 scale is derived from it. Applied as
   * `--elm-accent` on the editor root and on ElementEditor's portals; updates live.
   * Default: undefined (blue). `<ElementEditor accentColor>` wins over this.
   */
  accentColor?: string

  /**
   * Default colour of every feature (polygon outline + fill, line, point): any
   * CSS colour. Opacity and weight keep their defaults. `getFeatureStyle` (per
   * key) and the selected look win over it, hover keeps it. Updates live.
   * Default: undefined (slate #475569). `<ElementEditor featureColor>` wins over this.
   */
  featureColor?: string

  /** Which drawing tools are available. Default: 'all'. */
  tools?: DrawTool[] | 'all'

  /**
   * Namespace for everything this editor remembers in localStorage: `elm_theme`
   * becomes `elm_<persistKey>_theme`, and so on. Give each editor on an origin
   * its own key. Default: undefined (the shared `elm_*` keys).
   */
  persistKey?: string

  /** false: read and write nothing in localStorage. Default: true. */
  persist?: boolean

  /**
   * Every third-party server this editor talks to, per editor. Omitted keys keep the default;
   * `false` turns a service off (and hides what needs it). See the
   * [Third-party services and self-hosting](../guides/third-party-services) guide.
   */
  network?: {
    vectorTiles?: NetworkSource   // built-in vector basemaps (OpenMapTiles schema). Default: OpenFreeMap
    dem?: NetworkSource           // hillshade elevation (terrarium). Default: Mapterhorn
    osmRaster?: NetworkSource     // the 'osm' raster basemap (both engines). Default: tile.openstreetmap.org
    glyphs?: string               // glyph URL template (Noto Sans Regular/Bold/Italic). Default: OpenFreeMap
    sprite?: string               // absolute sprite URL prefix. Default: jsDelivr copy of the adapter's
    overpass?: false | { endpoint?: string; timeoutMs?: number }          // the Picker's OSM lookups
    routing?: false | { provider?: 'ors' | 'osrm'; url?: string; apiKey?: string; attribution?: string } // Route tool. Default: OSRM demo (car-only, not for production)
    nominatim?: false | { url?: string; email?: string; attribution?: string } // search box
    fetch?: typeof fetch          // every request Element makes itself (Overpass, routing, search)
  }
  // NetworkSource: a URL (tile template with {z}, else TileJSON) or MapLibre source fields
  // merged over the built-in source ({ tiles?, url?, attribution?, encoding?, maxzoom?, … }).

  /** UI element visibility. All default to true. */
  ui?: {
    /** Drawing hints in the active toolbar (e.g. "Click and drag to size"). */
    hints?: boolean
    /** Data table panel (spreadsheet view of all features). */
    dataTable?: boolean
    /** Layers / features list panel. */
    layerList?: boolean
    /** Schema editor button. */
    schemaEditor?: boolean
    /** GeoJSON editor button. */
    geojsonEditor?: boolean
    /**
     * Open the GeoJSON inspector on mount, in the user's last Dock/Undock
     * mode (docked beside the map by default; 'docked' means the same as
     * true). Initial state only: the user's toggles win afterwards. Doesn't
     * take keyboard focus. Ignored when geojsonEditor is false. Default: false.
     */
    geojsonEditorOpen?: boolean | 'docked'
    /** Editor settings button. */
    settings?: boolean
    /** "Fit all features" zoom button. */
    zoomToAll?: boolean
    /** Click-to-edit zoom level indicator. Default: true. */
    zoomIndicator?: boolean
    /** "Fly to my location" geolocation button. Default: true. */
    locateButton?: boolean
    /**
     * Keyboard shortcuts.
     * `false` — disable shortcuts entirely and hide the shortcuts button.
     * `{ enabled, show, mapZoom }` — fine-grained.
     * Default: `{ enabled: true, show: true, mapZoom: false }`.
     *
     * `mapZoom`: when true, intercepts Cmd/Ctrl + (`+`/`=`) and Cmd/Ctrl + (`-`)
     * to zoom the map in/out by one level. Only fires while the cursor is over
     * the editor and no input is focused, so it doesn't hijack the host page's
     * browser-zoom shortcut. Off by default (opt-in).
     */
    keyboardShortcuts?: boolean | { enabled?: boolean; show?: boolean; mapZoom?: boolean }

    /**
     * Where every built-in control goes: slots → ordered entries. See the
     * "Configuring the layout" guide. Map slots: topLeft, topCenter,
     * topRight, leftCenter, rightCenter, bottomLeft, bottomCenter,
     * bottomRight; status bar slots: statusLeft, statusRight. A map slot is
     * an array or `{ items, direction }`; a status slot is an array. Unlisted
     * controls are hidden (except 'attribution', which then stays on the
     * map). First place wins for a control listed twice. Visibility flags
     * still apply. 'separator' goes inside a group or in a status slot.
     * To change a few controls and keep the rest: `withLayout({ move, hide })`.
     * Default: DEFAULT_LAYOUT.
     */
    layout?: LayoutConfig
  }

  /** Floating toolbar (drawing tools) layout. Its place is the 'toolbar' entry in `ui.layout`. */
  toolbar?: {
    /**
     * `'horizontal'` (default) lays the tool buttons in a row with the
     * place-search input inline. `'vertical'` stacks tools top-to-bottom and
     * collapses the search into an icon button.
     */
    direction?: 'horizontal' | 'vertical'
  }

  /** Measurement and number display. */
  units?: {
    /** Length unit. `'auto'` picks metric/imperial from the browser locale. Default: `'auto'`. */
    length?: 'metric' | 'imperial' | 'auto'
    /** Area unit. Default: `'auto'`. */
    area?: 'metric' | 'imperial' | 'auto'
    /** Number format. `'human'` = `"1.2 km"`, `'raw'` = `"1234.56 m"`. Default: `'human'`. */
    display?: 'human' | 'raw'
    /** Decimal places in `'raw'` display mode. Default: 2. */
    precision?: number
  }
}

type MapSlot =
  | 'topLeft' | 'topCenter' | 'topRight'
  | 'leftCenter' | 'rightCenter'
  | 'bottomLeft' | 'bottomCenter' | 'bottomRight'
type StatusSlot = 'statusLeft' | 'statusRight'
type LayoutSlot = MapSlot | StatusSlot

type LayoutControl =
  | 'toolbar' | 'undo' | 'redo'
  | 'fitBounds' | 'locate' | 'zoomIndicator'
  | 'table' | 'schema' | 'geojson' | 'settings' | 'keyboard'
  | 'applyChanges'
  | 'attribution'        // status bar slots only
  | 'basemap'            // basemap picker; hidden when the editor has no picker; never in a group

type MapControl = Exclude<LayoutControl, 'attribution'>
type StatusControl = Exclude<LayoutControl, 'toolbar' | 'applyChanges'>
type MapGroup = { group: ReadonlyArray<Exclude<MapControl, 'toolbar' | 'basemap'> | 'separator'> }
type StatusGroup = { group: ReadonlyArray<Exclude<StatusControl, 'basemap'> | 'separator'> }
type MapEntry = MapControl | MapGroup                        // no bare 'separator' over the map
type StatusEntry = StatusControl | 'separator' | StatusGroup
type MapSlotConfig = readonly MapEntry[] | { items: readonly MapEntry[]; direction?: 'horizontal' | 'vertical' }
type StatusSlotConfig = readonly StatusEntry[]               // always horizontal
type LayoutConfig = { [S in MapSlot]?: MapSlotConfig } & { [S in StatusSlot]?: StatusSlotConfig }
// Unions of the two: LayoutGroup, LayoutEntry, LayoutSlotConfig.

// Changes for withLayout(patch, base = DEFAULT_LAYOUT): LayoutConfig
type SlotFor<C extends LayoutControl> =
  C extends 'attribution' ? StatusSlot : C extends 'toolbar' | 'applyChanges' ? MapSlot : LayoutSlot
interface LayoutPatch {
  /** Put a control in a slot wherever it was (or add it): at the end, or first with at: 'start'. */
  move?: { [C in LayoutControl]?: SlotFor<C> | { slot: SlotFor<C>; at?: 'start' | 'end' } }
  /** Take controls off the layout (wins over move). */
  hide?: readonly LayoutControl[]
}

const DEFAULT_LAYOUT: LayoutConfig = {
  topCenter:  ['toolbar'],
  leftCenter: [{ group: ['undo', 'redo'] }],
  bottomLeft: ['basemap', 'fitBounds', 'locate', 'zoomIndicator', 'table', 'schema', 'geojson', 'settings', 'keyboard', 'applyChanges'],
}

<ElementEditor
  config={{
    ui: {
      layout: {
        topCenter:   ['toolbar'],
        leftCenter:  [{ group: ['fitBounds', 'separator', 'locate'] }],
        bottomLeft:  [{ group: ['table', 'schema', 'geojson', 'separator', 'settings'] }],
        bottomRight: ['applyChanges'],
        statusLeft:  [{ group: ['undo', 'redo'] }, 'separator', 'keyboard'],
        statusRight: ['zoomIndicator', 'separator', 'attribution'],
      },
    },
  }}
  slots={{ bottomLeft: <MyAdminButton /> }}
/>

<ElementEditor layout="minimal" config={{ ui: { geojsonEditorOpen: 'docked' } }} />

<ElementEditor
  config={{
    mode: 'dark',
    tools: ['polygon', 'point'],
    ui: {
      dataTable: false,
      schemaEditor: false,
      keyboardShortcuts: false,
    },
  }}
/>

type DrawTool =
  | 'polygon' | 'rectangle' | 'circle' | 'line' | 'point' | 'freehand' | 'route' | 'picker'
  | 'measure' | 'search'

type ToolbarPosition =
  | 'top-left'    | 'top-center'    | 'top-right'
  | 'left-center' | 'right-center'
  | 'bottom-left' | 'bottom-center' | 'bottom-right'