Widgets¶
Widgets are the parts of the app users interact with: the layer list, legend, search box, draw tools and so on. Each one is a self-contained folder under app/widgets/, and the shell finds them automatically. You choose which to use and where they go by placing them in your project's settings.json.
Placing a widget¶
Each widget lists the surfaces it supports. Place it by adding its id to the matching array in settings.json:
"topBarWidgets": [{ "widgetName": "measure" }, { "widgetName": "draw" }],
"sidePanelWidgets": [{ "widgetName": "layer-list" }, { "widgetName": "legend" }, { "widgetName": "basemap" }],
"floatingWidgets": [
{ "slot": "top-left", "widgets": [{ "widgetName": "search", "order": -1, "stayOnMobile": true }] },
{ "slot": "top-right", "widgets": [{ "widgetName": "coordinates" }] }
],
"mobileWidgets": ["layer-list", "legend", "basemap", "bookmarks", "measure", "draw"]
| Surface | Where it appears | Placement array |
|---|---|---|
top-bar |
An icon button in the top bar; its UI opens in a panel beside the map | topBarWidgets |
side-panel |
An icon in the side rail; its UI slides out beside the map | sidePanelWidgets |
floating |
A button floating over a map corner | floatingWidgets |
A widget that supports several surfaces can appear in several places. The other placement fields (panelWidth, header, order, stayOnMobile) are covered in Building a Custom Widget.
mobileWidgets lists, in order, the widgets in the mobile top-bar carousel. On mobile it's the only way to open top-bar and side-panel widgets; floating widgets keep their buttons in the map corners. A widget can be in the carousel without being placed anywhere on desktop.
The built-in widgets¶
| Widget | id | Surfaces | What it does |
|---|---|---|---|
| Layer List | layer-list |
side-panel | Toggle layers, in groups; zoom, labels, transparency and filters per layer |
| Legend | legend |
side-panel | Symbology swatches for visible layers |
| Basemap | basemap |
top-bar, side-panel | Switch the basemap |
| Search | search |
floating | Search for places and for features in your layers |
| Measure | measure |
top-bar | Measure distances and areas |
| Draw | draw |
top-bar | Draw points, lines, polygons and text |
| Bookmarks | bookmarks |
side-panel, top-bar | Save and restore map views |
| Coordinates | coordinates |
floating | Live coordinates of the cursor or map center |
Search, measure, draw and bookmarks each have a settings block in settings.json, documented on the widget's page.
To build your own, start with Your First Widget.