Building a Custom Map Drawing Toolbar in React Without Coupling UI to the Map

Adam Groves — Wed, 09 Sep 2026 12:59:19 +0000

How to separate drawing state, application controls, and map rendering so your UI can evolve independently of the map engine.

Map drawing looks simple until it becomes part of a real application.

A user clicks a polygon tool, draws a boundary, and saves it. Then the product requirements grow: the toolbar needs to live in a sidebar, the selected shape needs an editable name, colors need to come from the application’s design system, undo and redo need to work from keyboard shortcuts, and annotations need to persist alongside the rest of the project data.

At that point, drawing is no longer just a map control. It is application state.

This article explores how to structure a React drawing experience so the map handles geographic interaction and rendering, while the application owns the workflow. We’ll build a custom toolbar using react-map-annotate, an open-source library I created to make that separation practical across multiple map engines.

The coupling problem

Many drawing integrations begin with an imperative API:

const draw = new MapDrawingControl();

map.addControl(draw);

// Later, somewhere in the application:
draw.changeMode("draw_polygon");

This is a perfectly reasonable model for a self-contained map tool. The difficulty appears when the rest of the application needs to participate.

You may end up maintaining several representations of the same state:

Application toolbar
       ↓
Drawing control mode
       ↓
Drawing control feature store
       ↓
Map events
       ↓
React state
       ↓
Application sidebar / database

Now consider a user renaming a polygon in the sidebar. The application updates its state, but the drawing control may still have its own feature representation. You need to synchronize the change back. Selection, deletion, styling, and undo history can introduce similar coordination problems.

The issue is not that imperative drawing APIs are inherently bad. It is that the drawing control has become the owner of state that the application also needs to own.

For a React application with a custom design system, I prefer a different boundary:

Application state
       ↓
Drawing session
       ├── Custom toolbar
       ├── Annotation sidebar
       ├── Keyboard shortcuts
       ├── Persistence
       └── Map adapter
              ↓
           Map engine

The map is still responsible for pointer interaction, coordinate projection, and rendering. But it is no longer the center of the application’s drawing workflow.

The architecture: session, UI, and adapter

The approach used by react-map-annotate separates drawing into three responsibilities.

1. The drawing session

The session owns concepts such as the active tool, draft geometry, selection, annotation changes, and drawing actions.

Your application can access those actions through React hooks instead of reaching into a map instance.

2. The application UI

The toolbar, annotation list, property inspector, and keyboard shortcuts are consumers of the session. They do not need to know whether the map underneath is Mapbox or Leaflet.

This means the same drawing action can be triggered from a toolbar button, a command palette, or a keyboard shortcut.

3. The map adapter

The adapter translates the session into map-specific rendering and interaction. Each engine has different APIs for layers, markers, projection, and pointer events, but those details stay behind the adapter boundary.

The library currently provides adapters for Mapbox, MapLibre, Google Maps, Leaflet, and ArcGIS, with a shared annotation model.

Building a custom toolbar

Let’s start with a Mapbox example. The important part is that the toolbar is not a child of the map. It is a sibling that consumes the same provider.

Install the package and the Mapbox dependencies:

npm install @orange-groove/react-map-annotate react-map-gl mapbox-gl

Now create a small drawing application:

import { useState } from "react";
import Map from "react-map-gl/mapbox";

import {
  AnnotateProvider,
  useAnnotateTools,
  type Annotation,
} from "@orange-groove/react-map-annotate/core";

import { Annotate } from "@orange-groove/react-map-annotate/mapbox";

import "@orange-groove/react-map-annotate/styles.css";

function DrawingToolbar() {
  const {
    items,
    finish,
    canFinish,
    undo,
    redo,
    canUndo,
    canRedo,
    selectedId,
    deleteSelected,
  } = useAnnotateTools();

  return (
    <div role="toolbar" aria-label="Map drawing tools">
      {items.map((item) => (
        <button
          key={item.id}
          type="button"
          aria-pressed={item.active}
          onClick={item.select}
        >
          {item.label}
        </button>
      ))}

      <button type="button" disabled={!canFinish} onClick={finish}>
        Finish
      </button>

      <button type="button" disabled={!canUndo} onClick={undo}>
        Undo
      </button>

      <button type="button" disabled={!canRedo} onClick={redo}>
        Redo
      </button>

      <button
        type="button"
        disabled={!selectedId}
        onClick={deleteSelected}
      >
        Delete
      </button>
    </div>
  );
}

export function DrawingApp({ token }: { token: string }) {
  const [annotations, setAnnotations] = useState<Annotation[]>([]);

  return (
    <AnnotateProvider
      annotations={annotations}
      onChange={setAnnotations}
    >
      <div className="drawing-layout">
        <aside className="drawing-sidebar">
          <DrawingToolbar />
        </aside>

        <main className="map-container">
          <Map
            mapboxAccessToken={token}
            initialViewState={{
              longitude: -81.1,
              latitude: 32.0,
              zoom: 12,
            }}
            mapStyle="mapbox://styles/mapbox/streets-v12"
            style={{ width: "100%", height: "100%" }}
          >
            <Annotate />
          </Map>
        </main>
      </div>
    </AnnotateProvider>
  );
}

The toolbar does not receive a mapRef. It does not call map.addControl(). It does not need to know how Mapbox represents drawing modes.

It receives a list of available tools and actions from the drawing session. The map adapter consumes that same session and renders the interaction.

The bundled toolbar is optional; the application can replace it entirely.

Controlling drawing from anywhere

Sometimes a generic toolbar is not enough. You may have a command palette, a workflow-specific button, or a form that needs to start a particular drawing action.

The lower-level useAnnotate() hook exposes the session directly:

import { useAnnotate } from
  "@orange-groove/react-map-annotate/core";

function BoundaryActions() {
  const {
    tool,
    setTool,
    finish,
    canFinish,
  } = useAnnotate();

  return (
    <section>
      <button
        type="button"
        aria-pressed={tool === "polygon"}
        onClick={() => setTool("polygon")}
      >
        Draw boundary
      </button>

      <button
        type="button"
        disabled={!canFinish}
        onClick={finish}
      >
        Save boundary shape
      </button>
    </section>
  );
}

This is useful when drawing is part of a larger workflow. For example, a site-planning application might have a “Define property boundary” step. The user does not need to interact with a generic drawing toolbar at all; the workflow can activate the polygon tool directly.

The same principle applies to keyboard shortcuts, contextual menus, and custom controls built with Chakra UI, MUI, Radix, or your own component system.

Editing annotations from a sidebar

Drawing the geometry is only the first part of most applications. Users also need to name, style, select, and delete their annotations.

The library exposes those operations through useAnnotateItems():

import { useAnnotateItems } from
  "@orange-groove/react-map-annotate/core";

function AnnotationSidebar() {
  const items = useAnnotateItems();

  return (
    <aside>
      <h2>Annotations</h2>

      {items.map((item) => (
        <div key={item.id}>
          <button
            type="button"
            aria-pressed={item.isSelected}
            onClick={item.select}
          >
            {item.annotation.label || "Untitled annotation"}
          </button>

          <input
            aria-label="Annotation name"
            value={item.annotation.label ?? ""}
            onChange={(event) =>
              item.setLabel(event.target.value)
            }
          />

          <input
            type="color"
            aria-label="Annotation color"
            value={item.annotation.color ?? "#2563eb"}
            onChange={(event) =>
              item.setColor(event.target.value)
            }
          />

          <button type="button" onClick={item.remove}>
            Delete
          </button>
        </div>
      ))}
    </aside>
  );
}

The sidebar is not scraping information from a map overlay. It is operating on the annotation session directly.

That distinction matters when you add more application behavior. A property inspector can update stroke width. A project form can rename an annotation. A bulk action can delete selected items. The map does not need to become the API through which every application feature passes.

Keeping persistence at the application boundary

The provider can receive controlled annotations and an onChange callback:

const [annotations, setAnnotations] = useState<Annotation[]>([]);

<AnnotateProvider
  annotations={annotations}
  onChange={setAnnotations}
>
  {/* Map and application UI */}
</AnnotateProvider>

This makes persistence an application concern.

For example, you might debounce changes before saving them to an API:

function useSaveAnnotations(
  projectId: string,
  annotations: Annotation[]
) {
  // Your application can debounce, validate, and persist
  // the annotation array using its existing data layer.
}

Or you could store the annotations in Zustand, Redux, or another state-management solution.

The important architectural point is that persistence does not need to ask the map for its current features. The application already has the data it intends to save.

In a production system, I would also keep server-side validation, authorization, and any required coordinate-system transformations in the persistence layer. A drawing library should not be responsible for deciding who is allowed to modify a project.

Avoiding map-engine lock-in

A common concern with map-heavy applications is that the rendering engine may change. Pricing, licensing, performance, or product requirements can make a migration necessary.

If your drawing UI is tightly coupled to one engine’s control API, migration becomes more than replacing the map component. You may also need to rewrite the toolbar, selection behavior, feature synchronization, and persistence logic.

With an adapter-based architecture, the application-facing session can remain stable while the map integration changes.

For example, the Mapbox adapter is imported from:

import { Annotate } from
  "@orange-groove/react-map-annotate/mapbox";

The MapLibre adapter uses:

import { Annotate } from
  "@orange-groove/react-map-annotate/maplibre";

The surrounding provider, custom toolbar, annotation list, and application state can continue using the core API.

This does not mean every map engine has identical capabilities. Terrain, markers, rendering, and engine-specific behavior still require adapter-specific handling. The goal is to isolate those differences rather than spread them throughout the application.

What belongs in the drawing library?

A useful boundary is to ask whether a feature is part of drawing interaction or part of the application’s business workflow.

The drawing library should handle things such as geometry creation, editing handles, selection, draft state, and rendering. The application should own project permissions, database persistence, business-specific validation, and the surrounding user experience.

For example, a field-service application might require a polygon to be named before it can be saved. That validation belongs in the application. The drawing session should expose the geometry and actions needed to implement it.

This separation also makes the library easier to reuse. A real-estate application, a GIS dashboard, and a site-planning tool can share drawing behavior without sharing the same toolbar or business rules.

Tradeoffs and alternatives

There are good reasons to use an existing map-native drawing control. If you need a simple polygon tool with a standard toolbar, a library such as Mapbox GL Draw, Leaflet.Draw, or Terra Draw may be a better fit.

Terra Draw in particular provides an adapter-based approach and programmatic drawing modes. It is a capable option for developers who want to assemble drawing behavior around different map engines.

The approach described here is aimed at a different integration preference: a React session that exposes drawing state and actions to the rest of the component tree, with optional stock UI and a shared annotation model.

That comes with its own tradeoffs. A headless API gives you more control, but it also means you are responsible for designing the user experience. You need to think about disabled states, accessibility, keyboard behavior, persistence, and how drawing fits into the rest of your application.

For complex products, that control is often exactly what you need.

Try it in your own application

react-map-annotate is MIT licensed and available on npm. It includes drawing and editing tools for polygons, rectangles, circles, lines, arrows, freehand paths, markers, text, and measurements, along with optional toolbar and annotation-list components.

The repository includes examples for custom toolbars, custom lists, headless usage, and the supported map engines.

I’m especially interested in feedback from developers building GIS dashboards, field-service applications, site-planning tools, or other map-heavy React products. If you have had to work around a drawing control to integrate it with your application’s state or design system, I’d like to hear what the difficult parts were.

The broader idea is simple: drawing should be a capability of your application, not an isolated control that your application has to work around.

GitHub - orange-groove/react-map-annotate: Draw on Mapbox, MapLibre, Google, Leaflet, or ArcGIS in React

Adam Groves — Wed, 09 Sep 2026 12:55:41 +0000

I built an open-source React map drawing library because I got tired of fighting drawing controls that wanted to own the UI.

react-map-annotate lets your application control the drawing session. Put the toolbar in your sidebar, header, or command palette. Select tools, finish shapes, edit labels and colors, undo/redo, and persist annotations through React state.

It supports Mapbox, MapLibre, Google Maps, Leaflet, and ArcGIS through separate adapters, with a shared annotation model.

The goal is simple: the map should render the drawing, not dictate how your application works.

It includes freehand drawing, polygons, rectangles, circles, arrows, markers, text, and measurement tools, along with editing handles and a headless API.

The project is MIT licensed and available on npm. I’d love feedback from developers building GIS, field-service, site-planning, or other map-heavy applications—especially anyone who has had to work around existing drawing controls.

GitHub: https://github.com/orange-groove/react-map-annotate

npm: https://www.npmjs.com/package/@orange-groove/react-map-annotate

What would you need from a drawing library before using it in a production application?

DEV Community: Adam Groves