Converting to an app
A web map is a map. An application is a product around a map: its own pages, its own chrome, its own logic, deployed at your own address. Convert to an app takes the map you built and hands it to the App Builder as the starting point, so you never rebuild your layers, styles and popups by hand.
The button sits in the header bar, to the left of Publish. Save the map first: the conversion reads the saved web map, not the unsaved state on your screen.
Two ways to convert
Section titled “Two ways to convert”The dialog asks one question, and the answer only applies to this conversion. Nothing is written back onto your web map.
| Route | What it keeps | When to pick it |
|---|---|---|
| Blank template | Your layout, your widgets and your data. The app starts as your map. | You composed the map the way you want the app to look. |
| Existing template | Your data only, meaning layers, styles and popups. The template’s layout and widgets take over. | You want the app to look like a finished product rather than like a builder canvas. |
With the second route you also pick which template of the catalogue to build on. Whatever you choose, everything stays editable afterwards in the App Builder.
What your widgets become
Section titled “What your widgets become”Widgets are the part where a map and an application genuinely differ, so ALIGN is explicit about it rather than quietly dropping things. The tables below are generated from the conversion table in the code itself (the same table the conversion runs), so they cannot drift from what actually happens.
Of the 34 entries of the Gallery, 19 convert, 13 have no app counterpart yet, and 2 are layout.
Widgets that convert
Section titled “Widgets that convert”Their parameters come along. A setting the application widget does not offer is left at that widget’s default; the last column says which.
| Map Builder widget | In the application | What travels | What does not |
|---|---|---|---|
| Zoom | Zoom | visibility, corner, the zoom-level readout, the zoom limits | - |
| Home | Home | visibility, corner, the home view | - |
| Scale | Scale | visibility, corner, the unit | - |
| Fullscreen | Fullscreen | visibility, corner | - |
| Geolocate | Geolocate | visibility, corner | - |
| Attribution | Attribution | visibility, corner, folded or expanded | - |
| Minimap | Minimap | corner, the zoom offset, folded by default | the always-open panel mode |
| Basemap | Basemap switcher | the basemap pool, grid or list layout, previews, open state | exposing only part of the pool, a custom title |
| Bookmarks | Bookmarks | the views (name and camera), end-user saving, open state | thumbnails, a custom title |
| Feature editor | Feature editor | create, delete and geometry permissions, the editable layers and fields, the label field, folded or expanded | the curated geometry tools, the selection color, editing by the audience, a custom title |
| Layer control | Layers control | visibility, corner or region, open state, title, the visibility toggle, reordering | hiding the opacity slider or the zoom-to-layer action |
| Layer swipe | Layer swipe | both sides, orientation, handle position, engaged on load, orientation exposure, open state | a custom title |
| Legend | Legend | visibility, corner or region, open state, title | a hand-authored legend (the app legend is automatic) |
| Measure | Measure | the modes, the unit family | on-map labels, precision, the unit offer, starting in area mode, a custom title |
| Place search | Search | the placeholder, pin or highlight on result, the result zoom, open state | the source curation (place scopes, layer sources), the suggestion budget, disabling the fly-to zoom |
| Table | Attribute table | the layers, the visible columns, search, filter, export, page size, inline editing per layer and field | editing by the audience, the folded dock |
| Compass | Compass | visibility, corner | - |
| Terrain | Terrain | relief on or off, exaggeration, end-user exaggeration, open state | a custom title |
| Graticule | Graticule | the grid settings, the settings exposed to visitors, open state | exposing the label edges, a custom title |
Widgets with no counterpart yet
Section titled “Widgets with no counterpart yet”They are not rendered in the application. When you had one of them switched on, the conversion reports it by name instead of leaving you to notice later.
Annotations, Color bar, Filter, HTML block, Print, Time slider, 2D / 3D, 3D Globe, Atmosphere, Spin globe, Directions, Reverse geocode, Street View.
Layout
Section titled “Layout”Placement rather than widgets: the application renders them with the same parameters.
| Region | What travels |
|---|---|
| Header | title, description, background and text colors, font, alignment, size |
| Footer | title, description, background and text colors, font, alignment, size |
What your layers become
Section titled “What your layers become”Your layers travel with their source, their style and their popups; the application reads the same Datastore assets as the web map. A layer type the application runtime cannot render yet is left out with a note naming the layer; it is never shipped to fail inside your app.
| Transported | Not yet supported in the application |
|---|---|
| GeoJSON and uploaded vector files (with their symbology and popups) | OGC API Features |
| XYZ raster tiles (WMS and WMTS services, rehosted) | ArcGIS Vector Tile Service |
| Cloud-optimized GeoTIFF | OGC API Tiles (vector) |
| PMTiles | STAC items |
| FlatGeobuf | Video overlays |
| GeoParquet | deck.gl visualisations |
| WFS features | Zarr arrays |
| GeoRSS feeds | NetCDF |
| ArcGIS Feature Service | 3D Tiles |
| LiDAR point clouds | |
| Gaussian splatting scenes | |
| DuckDB query layers |
The conversion report
Section titled “The conversion report”The conversion ends with a report in two sections, shown once when you land in the App Builder. Data says that all your layers came across, or names the ones whose type the application cannot render yet (and a layer whose Datastore asset was deleted). Layout says that all your widgets came across, or names the ones with no counterpart. Either way, what is missing is yours to build in the App Builder. With the existing template route the report is empty by design: only your data travels, so there is nothing about widgets to say.
After the conversion
Section titled “After the conversion”You land in the App Builder with a working project. From there the map is one part of an application you keep building: pages, components, data connections, and a deploy of your own. The App Builder documentation picks up from there.
Converting does not consume or replace your web map. It stays in your Datastore, it stays openable in the Map Builder, and it stays published if it was.