Quick start: Leaflet adapter

Add Element Editor drawing tools to your existing Leaflet map. Estimated time: ~10 minutes.

Use @element-editor/adapter-leaflet when you already have a Leaflet or react-leaflet map in your application and want to add editing to it — without replacing your map setup. Element attaches as an editing layer; your map, tile provider, and controls stay exactly as they are.

Let your AI agent set this up. One prompt gets Claude, Codex, or Cursor to install and wire up Element in your project.

Configure visually first? Open the playground to tweak every setting and copy the resulting config. Pass the same config object to <ElementEditorUIProvider config={...}>.

Step 1 — Install

npm install @element-editor/adapter-leaflet @element-editor/ui leaflet react-leaflet
npm install -D @types/leaflet # TypeScript: leaflet ships no types of its own

If leaflet and react-leaflet are already in your project, you don't need to reinstall them. Peer dependencies: react and react-dom ^19.2, react-leaflet ^5, leaflet ^1.9. React 18 is not supported. If your app is on an older React 19, upgrade it first; npm otherwise stops with a peer dependency conflict (ERESOLVE). Apps made with Next.js 15's create-next-app pin React 19.1:

npm install react@^19.2 react-dom@^19.2

@element-editor/ui provides the toolbars and panels. The adapter already depends on it, but list it in your own package.json so you can import from it (pnpm and other strict package managers only resolve packages you declare). The same applies to @element-editor/core if you want its types and helpers, such as FeatureCollection or getFeatureCollectionBBox. Keep all @element-editor/* packages on the same version.

Step 2 — Import the CSS

Add this import once, near your app entry point:

import '@element-editor/adapter-leaflet/style.css'

The stylesheet includes Leaflet's CSS (leaflet/dist/leaflet.css), so you don't need to import that separately. Importing it again is harmless.

Warning: The JavaScript entry doesn't import any CSS. Without this import, tiles vanish, markers disappear, and the editor UI is unstyled.

The stylesheet doesn't reset your page. Tailwind's base styles apply only inside an element with a data-elm-theme attribute, so all editor UI must be rendered inside one (Step 3 shows how).

Step 3 — Build the component

Wrap your map in ElementEditorUIProvider and GeoStoreProvider, put it inside a data-elm-theme element, then place ElementEditorControls inside the MapContainer alongside your existing layers:

import { MapContainer, TileLayer } from 'react-leaflet'
import { ElementEditorUIProvider, GeoStoreProvider, ElementEditorControls } from '@element-editor/adapter-leaflet'
import '@element-editor/adapter-leaflet/style.css'

export default function MyMap() {
  return (
    <ElementEditorUIProvider>
      <GeoStoreProvider>
        <div data-elm-theme="light" style={{ position: 'relative', width: '100%', height: '600px' }}>
          <MapContainer
            center={[48.86, 2.35]}
            zoom={5}
            style={{ width: '100%', height: '100%' }}
          >
            <TileLayer
              attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
              url="https://tile.openstreetmap.org/{z}/{x}/{y}.png"
            />
            <ElementEditorControls onChange={(data) => console.log(data)} />
          </MapContainer>
        </div>
      </GeoStoreProvider>
    </ElementEditorUIProvider>
  )
}

Note: Placement rules:

  • ElementEditorUIProvider provides the contexts the editor needs: an error boundary, config, keyboard shortcuts, events and toasts, and the map controller used by zoom-to actions. ElementEditorControls throws without it. It also renders Element's own toast <Toaster>, so you don't need to add one.
  • GeoStoreProvider must wrap MapContainer (or any ancestor of it). It creates the store that ElementEditorControls and any @element-editor/ui components share. Use one per editor.
  • The data-elm-theme element ("light" or "dark") scopes the editor's styles and its keyboard shortcuts: a key press only acts on this editor when focus or your last click is inside it.
  • ElementEditorControls must be a child of MapContainer. It uses useMap() from react-leaflet internally.

What you get

Your existing Leaflet map now has Element editing attached:

  • Drawing tools for areas, lines, points, rectangles, circles, freehand paths, and routes — plus a picker (X) that imports shapes from OpenStreetMap
  • Drag-to-draw rectangles and circles; spacebar pans during drawing without leaving the tool; ⌘ J keeps the tool active after a shape commits
  • Click-to-select, multi-select, box-select; right-click context menu on features
  • Vertex editing, transform (scale/rotate), boolean operations, simplify/smooth/buffer
  • Group / ungroup with ⌘ G / ⌘ ⇧ G; groups carry through to metadata.groups
  • 25-step undo/redo
  • onChange fires after every committed change with the full FeatureCollection

ElementEditorControls renders no visible UI by default — it attaches invisible interaction overlays to the map. To add toolbars and panels, see Adding the full UI below.

Step 4 — Wire up data

onChange delivers a complete GeoJSON FeatureCollection after each committed change. Load existing data with initialData. The types come from @element-editor/core (see Step 1):

import { MapContainer, TileLayer } from 'react-leaflet'
import { ElementEditorUIProvider, GeoStoreProvider, ElementEditorControls } from '@element-editor/adapter-leaflet'
import type { FeatureCollection } from '@element-editor/core'
import '@element-editor/adapter-leaflet/style.css'

export default function MyMap() {
  const savedData: FeatureCollection | null =
    JSON.parse(localStorage.getItem('my-map') ?? 'null')

  function handleChange(data: FeatureCollection) {
    localStorage.setItem('my-map', JSON.stringify(data))
  }

  return (
    <ElementEditorUIProvider>
      <GeoStoreProvider>
        <div data-elm-theme="light" style={{ position: 'relative', width: '100%', height: '600px' }}>
          <MapContainer
            center={[48.86, 2.35]}
            zoom={5}
            style={{ width: '100%', height: '100%' }}
          >
            <TileLayer
              attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
              url="https://tile.openstreetmap.org/{z}/{x}/{y}.png"
            />
            <ElementEditorControls
              initialData={savedData ?? undefined}
              onChange={handleChange}
            />
          </MapContainer>
        </div>
      </GeoStoreProvider>
    </ElementEditorUIProvider>
  )
}

If initialData isn't a valid FeatureCollection, the editor reports an error event and starts empty instead of crashing. A single Feature is wrapped in a collection.

Adding the full UI

ElementEditorControls handles the editing layer. The toolbars, sidebar, data table, and modals are separate @element-editor/ui components that you position in your own layout.

Tip: With the full UI stack you get exactly the same experience as @element-editor/react — but with full control over where each panel lives in your layout.

UI components go outside MapContainer, positioned absolutely over the map div, and inside the same data-elm-theme element. They share the same GeoStoreProvider store as ElementEditorControls. FloatingToolbar, LayersPanel and DataTablePanel position themselves over the map, against the data-elm-theme element (give it position: relative). EditingToolbar, ActiveDrawingToolbar and single buttons such as FitBoundsButton render in place, so put them in an absolutely positioned wrapper of your own, as below. DataTablePanel writes its open height to --elm-table-offset on the data-elm-theme element; add it to a bottom-anchored wrapper's bottom and the wrapper rides above the open table. The data table and the modals are lazy-loaded, so they must be wrapped in <Suspense>. Give each its own boundary: a shared one unmounts the already-loaded siblings while a new one loads.

import { Suspense, useState } from 'react'
import { MapContainer, TileLayer } from 'react-leaflet'
import { ElementEditorUIProvider, GeoStoreProvider, ElementEditorControls } from '@element-editor/adapter-leaflet'
import {
  ThemeContext,
  FloatingToolbar,
  EditingToolbar,
  ActiveDrawingToolbar,
  FitBoundsButton,
  LayersPanel,
  DataTablePanel,
  ShortcutsModal,
  SettingsModal,
  SchemaModal,
  GeoJSONModal,
  useUIStore,
} from '@element-editor/ui'
import '@element-editor/adapter-leaflet/style.css'

// Schema and GeoJSON modals render whenever mounted, so mount them only while open.
function ConditionalModals() {
  const schemaOpen = useUIStore((s) => s.schemaModalOpen)
  const toggleSchema = useUIStore((s) => s.toggleSchemaModal)
  const codeOpen = useUIStore((s) => s.codeModalOpen)
  const toggleCode = useUIStore((s) => s.toggleCodeModal)
  return (
    <>
      {schemaOpen && <Suspense fallback={null}><SchemaModal onClose={toggleSchema} /></Suspense>}
      {codeOpen && <Suspense fallback={null}><GeoJSONModal onClose={toggleCode} /></Suspense>}
    </>
  )
}

export default function MyMap() {
  const [mapReady, setMapReady] = useState(false)

  return (
    <ElementEditorUIProvider>
      <GeoStoreProvider>
        <ThemeContext.Provider value="light">
          <div
            data-elm-theme="light"
            // overflow: hidden: the collapsed layers panel waits just outside the right edge.
            style={{ position: 'relative', width: '100%', height: '600px', overflow: 'hidden' }}
          >
            {/* Map — fills the container */}
            <MapContainer
              center={[48.86, 2.35]}
              zoom={5}
              // zIndex: 0 keeps Leaflet's panes (z-index 400+) under the editor's panels.
              style={{ position: 'absolute', inset: 0, zIndex: 0 }}
              whenReady={() => setMapReady(true)}
            >
              <TileLayer
                attribution='&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors'
                url="https://tile.openstreetmap.org/{z}/{x}/{y}.png"
              />
              {mapReady && <ElementEditorControls onChange={(data) => console.log(data)} />}
            </MapContainer>

            {/* UI panels — outside MapContainer, positioned absolutely over the map */}
            {mapReady && (
              <>
                {/* Drawing tool selector: positions itself, top center */}
                <FloatingToolbar />

                {/* Edit actions and finish / cancel drawing: you place these (bottom center here) */}
                <div style={{ position: 'absolute', bottom: 'calc(var(--elm-table-offset, 0px) + 16px)', left: '50%', transform: 'translateX(-50%)', zIndex: 400, display: 'flex', gap: 8 }}>
                  <EditingToolbar />
                  <ActiveDrawingToolbar />
                </div>

                {/* Fly to fit all features: you place it (bottom left here) */}
                <div style={{ position: 'absolute', bottom: 'calc(var(--elm-table-offset, 0px) + 16px)', left: 16, zIndex: 400 }}>
                  <FitBoundsButton />
                </div>

                <LayersPanel />                {/* Feature list sidebar: positions itself, right */}
                <Suspense fallback={null}><DataTablePanel /></Suspense>  {/* Spreadsheet view */}
                <Suspense fallback={null}><ShortcutsModal /></Suspense>
                <Suspense fallback={null}><SettingsModal /></Suspense>
                <ConditionalModals />
              </>
            )}
          </div>
        </ThemeContext.Provider>
      </GeoStoreProvider>
    </ElementEditorUIProvider>
  )
}

ThemeContext tells portaled UI (tooltips, menus, modals) which theme to use. Keep its value in sync with data-elm-theme. Any UI you portal elsewhere yourself should carry a data-elm-portal attribute on its root, so Element styles it and keyboard shortcuts keep working while it has focus.

For a complete working example with buttons that open each panel, see Custom UI with adapters.

What's next