Web Map Kit guide
Everything you need to go from a QGIS project to a live, shareable web map, keep it up to date, collect answers from the people who use it, and take it into the field without signal.
New here? Watch the 2-minute demo to see the whole flow first.
Quick start (about 5 minutes the first time)
- Install the plugin from the ZIP file.
- Open Web Map Kit → Hosting settings once, paste a Cloudflare token, and let the plugin set everything up.
- Open your project, click Publish web map, then share the link.
1. Install the plugin
- In QGIS (3.28 or newer, including QGIS 4), open Plugins → Manage and Install Plugins…
- Choose Install from ZIP, pick the
webmapkit-….zipfile you downloaded, and click Install Plugin. - A teal map-pin icon appears on the Web toolbar. Click it to publish; click the small ▾ arrow next to it for My published maps, Hosting settings and this guide. The same items are in the Web → Web Map Kit menu.
Updating: install the new ZIP the same way. Your hosting settings and published maps are kept. If the toolbar button looks unchanged, restart QGIS.
2. Set up hosting (once)
Your maps live in your own free Cloudflare account, using Cloudflare R2 storage. There's no monthly bill and no bandwidth charge, and only you control the files. Open Web Map Kit → Hosting settings and follow the three steps:
- Sign in to Cloudflare in your browser, or create a free account. Sign in first, so the next link can fill everything in.
- Create my token. Cloudflare opens with the token already filled in. Scroll down, click Continue to summary, then Create Token, then Copy. Using a different browser? Click Copy link and paste it there.
- Paste the token into the plugin. It checks the token, finds your account, creates a storage bucket called
maps, switches on its public address, and does a test upload.
“R2 isn't switched on yet”? New Cloudflare accounts need R2 turned on once: click Switch on R2, follow Cloudflare's steps (it asks for a card), then click I've done it, check again. The free tier costs nothing; see Costs and limits.
The Cloudflare page showed a list of tokens instead of a filled-in form
You probably weren't signed in when the link opened. Sign in, then click Create my token again. Or create it by hand:
- Create Token → Create Custom Token → Get started, and name it Web Map Kit.
- Add three permissions: Account · Workers R2 Storage · Edit, Account · Workers Scripts · Edit (for response forms) and Zone · Zone · Read.
- Continue to summary → Create Token → Copy, and paste it into the plugin.
Choose your map address
- Free Cloudflare address (
pub-….r2.dev) works straight away. It's good for drafts and personal maps. - Your own domain (for example
maps.yourcompany.com) looks professional for clients. The domain must already be on Cloudflare. Pick it, type a name in front (such asmaps), and the plugin connects it. That usually takes 1 to 5 minutes.
Already have R2 keys? On the first screen, choose I already have R2 keys and enter the Account ID, bucket, Access Key ID, Secret and public address yourself.
3. Publish a map
- Open your project and style it in QGIS as usual (see Supported styles).
- Click the Web Map Kit icon. Check the Title and Description, and tick the Layers to include. Visible ticks what's visible in QGIS.
- Pick a Background map, a Points style (circles like QGIS, round icon badges or map pins) and a Detail level. Automatic is right for almost every map.
- Opens at: What you see in QGIS now (the default) opens the web map at the area shown in your QGIS map window, so zoom QGIS to where you want visitors to start. Fit all layers opens it showing all your data.
- Leave Publish online ticked and check the Web address. The message under it tells you what will happen:
- ✓ New map: the address is free.
- ↻ Updates your map: this project's map will be replaced at the same link.
- ⚠ Already uses this address: a different map is there. Click Use a new address instead, or confirm you want to replace it.
- Click Create web map. Large maps can take a few minutes, and QGIS may look busy until it finishes. At the end, copy the link or click Open map.
Your settings are saved inside the project, so next time it's one click. The web map files are also kept on your computer (by default in Documents/Web Map Kit/). Use Preview on this computer to check a map without publishing it.
What your viewers get
- A fast map that works on phones and computers, with no login or app needed.
- Click any feature for a popup. The popup title comes from the layer's Display name field (Layer Properties → Display), or else the first name-like text field.
- Popup rows use your field aliases. To hide a field, set its widget type to Hidden in Layer Properties → Attributes Form.
- Photos at the top of the popup, if a layer has a photo field (see below).
- A legend with layer toggles and transparency sliders, and an optional search box.
Photos in popups
If a layer has a text field holding a photo for each feature, the photo appears at the top of its popup. Visitors click it to see it full size. There's nothing to switch on: Web Map Kit finds the field when you publish. See an example.
| The field contains | What happens |
|---|---|
Web links to photoshttps://example.com/photos/site1.jpg | The photo is shown straight from that link. Nothing is uploaded; the photos must stay online at that address. |
Photo files on your computerphotos/site1.jpg or C:\Survey\photos\site1.jpg | The photos are copied into the web map and published with it, so they keep working when the map is shared. Paths can be full paths, or relative to the project file (what the QGIS Attachment widget saves). |
- Formats: JPG, PNG, WebP and GIF.
- Size: copied photos are resized to at most 1600 px on the long side and saved as JPG (about 100–250 KB each), so even a few hundred photos stay small and fast. Phone photos are turned the right way up.
- Which field: one photo field per layer. A field set to the Attachment widget in Layer Properties → Attributes Form is picked first, then a field named like photo, image or picture. Most of the field's values must be photos.
- The photo field itself isn't listed as a row in the popup. To show no photo at all, set the field's widget to Hidden.
- Features without a photo get a normal popup. Files that can't be found are left out, and the publish log tells you how many.
4. Response forms: let people answer about places
Watch it first: setting up a form, answering on a phone with and without signal, and reviewing the answers in QGIS.
A response form adds a Send a response button to your web map. People answer your questions about a place (or about any spot they tap) and can attach photos. The answers go to a private store in your own Cloudflare account, never to the public map, and come into a QGIS layer when you click Get responses. You check what each answer would change, then apply it to your layer.
Good for: asset and site inspections, residents reporting problems, land owners confirming their parcel, volunteer surveys, community mapping. Visitors need no app and no account; the form follows their phone's language (English, Spanish, French, Portuguese, German or Italian).
Set up a form
- Open your project and click Publish web map. Tick Let visitors send responses, then click Set up form…. The Let visitors send responses window has four short steps.
- 1. What do people respond about?
- A place on the map (each parcel, site, school…): choose the Layer and the field that identifies each one (an ID or code field). Visitors click a feature and choose the form button in its popup.
- Anywhere: visitors tap the map where their answer belongs, or use Use my location (the phone's GPS, with its accuracy saved). Good for reporting problems.
- 2. Questions. The form starts with Your name and Comment. Click Add from the layer… to turn fields of your layer into questions: dropdowns (value maps), dates, numbers (with their range), yes/no and text are copied with their settings, and a field that may not be empty becomes a required question. Tick to add, untick to remove; the list says why some fields can't be questions (the ID field, fields hidden in your QGIS form, or a name clash). Edit questions… opens the QGIS form settings of the responses layer for anything else (labels, order, new questions).
- 3. Who can answer?
- Anyone who opens the map, or
- Only people with an access code (one per place). A code is made for every place and saved in a list next to your project (
…_access_codes.csv, keep it private). Print sheet (PDF)… makes a sheet with one QR code per place: scanning it opens the map at that place with the form open and the code filled in. A code only works for its own place.
- 4. Photos. Choose how many photos or PDFs people can attach (0 for none). Photos are JPG, PNG, WebP or HEIC, up to 8 MB each.
- More options ▸ lets you change the button text, the line above the form, what you call each place (e.g. parcel, bench) and add a privacy note shown under the form.
- Click Done. Web Map Kit creates the private Responses layer (a GeoPackage next to your project), the access codes, and the form handler in your Cloudflare account. Then click Create web map as usual.
“Your Cloudflare token can publish maps, but it can't run the response form yet”? Tokens made before version 1.3 can't set up the form handler. Click New token: Cloudflare opens with everything filled in; create it, copy it and paste it in Hosting settings. Your published maps stay as they are. (Or add Account · Workers Scripts · Edit to your existing “Web Map Kit” token.)
Share the form
- After publishing, the finish screen has QR code (for the map link), Codes list, Print codes (PDF)… and Get responses. The same buttons are in the publish window under the form status.
- Hand out the printed codes, or send each person their own link from the codes list. Without a QR code, people open the map, tap I have an access code, and the map takes them to their place.
- If you make new codes, the old ones stop working when you publish again. Reprint the sheet.
What visitors see
- They open the map (or scan the QR code), pick the place and tap the form button.
- They answer, attach photos and tap Send. They get a short reference number, and Send another starts the next one.
- No signal? The answer is kept on the phone (Saved on this phone) and sent by itself when the connection is back, even after the page was closed and opened again. A code typed while offline is checked when the answer is sent; if it's wrong, the visitor can correct it.
Get the answers into QGIS
- Open the project. When new answers are waiting, QGIS tells you how many. Click Get responses (on the finish screen, in the publish window, or in Set up form…).
- Answers arrive as features in the Responses layer, each with the time it was filled in on the phone. Photos are saved in a
collect_filesfolder next to your project (Open photos folder). Once an answer and its photos are safely in QGIS, they're removed from Cloudflare (untick Remove from Cloudflare once in QGIS to keep a copy there). - Click Review…. For each answer you see the place, what's in the layer now and what's proposed. Zoom to and Open photos help you check. Tick the answers you accept and click Apply to layer, or Dismiss the others. Only questions taken from the layer can change it: a visitor's name or comment never overwrites your data, and empty answers never clear a value.
- Applied changes go into the layer's edit session: check them on the map and save the layer to keep them, or roll back to undo. Responses are coloured by status: waiting for review, applied or dismissed.
Safety built in
- Wrong codes: after 8 wrong tries in 15 minutes, that connection is locked out of the form for 30 minutes.
- At most 30 responses per hour from one connection, and each response is stored only once even if a phone sends it twice.
- Uploads are checked: photos and PDFs only, 8 MB per file, 25 MB per response.
- Pause the form stops new responses while the map stays online.
Response forms are in the full Web Map Kit. Web Map Kit Lite (free) publishes maps without forms.
5. Use without signal
For field work, visitors can keep the whole map on their phone. Tick Let people save this map for use without signal in the publish window and choose:
- Area: What you see in QGIS now, All published layers, or Same area as last time. Keep it to the area people will work in.
- Detail: Street level (zoom in to individual buildings) or Neighbourhood (smaller download). The window shows the size per phone before you publish.
When you publish, Web Map Kit cuts that area out of a world background map made from OpenStreetMap by Protomaps, and publishes it with your map. The map then uses this background online too. The first time takes a little longer; republishing the same or a smaller area reuses what was downloaded (it's refreshed after 30 days). Areas over 1 GB are refused, because phones can't keep that reliably; a town at street level is usually a few MB to a few tens of MB.
On the phone
- Open the map once with a connection (Wi-Fi is best) and tap the save button at the top right, or Save in the “Going into the field?” bar. The map area, background, your data, fonts and the form are kept on the phone.
- iPhone and iPad: also tap Share → Add to Home Screen and open the map from that icon. Otherwise Safari may delete saved maps after about a week without use.
- In the field, open the map as usual (or from the home screen). With no signal it says No signal: showing the map saved on this phone, and everything works: map, popups, search and the form.
- When you publish a new version, the save button shows that the copy is out of date; tap it and Update now. Remove from this phone frees the space.
6. Supported QGIS styles
| In QGIS | On the web map |
|---|---|
| Single symbol | ✓ Fill, stroke, line width, point size and opacity |
| Categorized (by a field) | ✓ Colours, widths and sizes per category, with legend labels |
| Graduated (by a field) | ✓ Classes, colours and legend |
| Data-defined size (Size Assistant) | ✓ Proportional circles with a size legend |
| Layer opacity, “no fill” polygons | ✓ |
| Labels (single field) | ✓ Colour and size; polygon labels placed once per polygon |
| Categories or classes from an expression | One colour: use a field instead; you'll get a warning |
| Rule-based, heatmap, 2.5D, point clusters | One colour: not supported yet |
| SVG markers, patterns, geometry generators | Simplified to plain colours |
| Raster layers | ✕ Vector layers only (points, lines and polygons) |
After publishing, the finish screen lists anything under Worth checking, so nothing is dropped silently.
7. Update and manage your maps
- Update a map: change your data or styling, click Publish web map again, and keep the same web address. The link stays the same, and visitors see the new version within a minute.
- Publish another map: use a different title or web address. Each map gets its own link, and old maps stay online.
- Update the plugin: when a new version is out, QGIS shows a Get the update bar a few seconds after it starts. It opens the update page, where you get the new ZIP with the email you paid with. Updates to 1.x are free.
- My published maps (toolbar ▾ menu) lists every map in your hosting, with a preview, size and date. From there you can Open, Copy link, Copy embed code (to put the map in a website or blog), Update from this project, or Delete a map. Deleting stops the link working for everyone and can't be undone; your QGIS project isn't touched.
8. Fine-tune the look (optional)
Each published map is a small folder of files you can edit, then publish again:
style.csscontrols colours, fonts and panel styles. It's created once and never overwritten, so your changes are kept.config.jsonholds layers, colours, popups and labels. It's regenerated on every export, and the previous version is kept asconfig.backup.json. Most changes are best made in QGIS instead.CONFIG.mdin the folder explains every option.
9. Troubleshooting
“Cloudflare didn't accept this token”
The token was copied incompletely, or it was deleted. Cloudflare shows a token only once, so create a new one with Create my token and paste it again.
“The upload server didn't answer” during set-up
Brand-new accounts and tokens sometimes need a minute before uploads work. Wait a minute and click Try again. If it keeps failing, email us the grey Details line.
“This address is already used by something else in Cloudflare”
The name is taken by another Cloudflare service, often a Pages website or an old DNS record. Remove it there (Workers & Pages → your site → Custom domains, or DNS → Records), or choose a different name.
The map link shows “Error 404 / Object not found”
- Check the address in My published maps. The web address is made from the title, so it may differ from what you expected.
- Right after connecting your own domain, give Cloudflare a few minutes.
- If you switched Cloudflare accounts in Hosting settings, maps published to the old account stay there.
“Too detailed for an area this large”
You picked a high detail level for a big area, which would create millions of tiles. Choose Automatic, or a lower level.
Publishing takes a long time
World-wide data at high detail can take several minutes, and QGIS may look frozen until it finishes; that's normal. Automatic detail keeps it quick. The estimate under Detail tells you before you start.
A layer shows in one colour, or looks different from QGIS
Check the Worth checking notes on the finish screen, and the supported styles table. Categories and classes need to use a field, not an expression.
Photos don't appear in the popups
Check the publish log: it says "photos: N copied into the map" or "shown from the web links in …". If it says nothing about photos, the field wasn't recognised: make sure most values are photo files or links ending in .jpg, .png, .webp or .gif, or set the field's widget to Attachment. If some files are "not found on disk", check the paths are correct relative to the project file. Web-link photos only show if that website allows it and is online.
The form button doesn't appear on the map
Check that Let visitors send responses is ticked and the publish window says Form on, then publish again. In a place on the map mode the button is in the popup of the features of the chosen layer.
Visitors get “That code isn't valid”
Codes are not case-sensitive and spaces are ignored. If you clicked Make new codes, the old codes stopped working when you published again: hand out the new sheet. A code only works for its own place.
Saving the map on the phone is slow or stops
It shows which step it's on and how much it has downloaded. On a weak connection it retries; if it stays stuck, cancel and try again on Wi-Fi. Nothing half-saved is left behind. If it says there isn't enough space, choose a smaller area or Neighbourhood detail and publish again.
The background map doesn't appear
Background maps come from OpenFreeMap over the internet (or, for maps saved for use without signal, from the map's own copy). If your network blocks it, the map falls back to a plain background, and your data still shows. Check that Background isn't set to None in the publish window.
10. Costs and limits
Web Map Kit is a one-time purchase. Everything it publishes runs in your own Cloudflare account, and for typical projects that costs nothing. Cloudflare's current free allowances (from its R2 and Workers pricing pages, October 2026):
| What | Uses | Free each month | Typical project |
|---|---|---|---|
| Published maps | R2 storage | 10 GB storage, downloads (bandwidth) always free | 1–30 MB per map |
| Map views | R2 reads | 10 million reads | Each map tile is one small read (roughly 50–200 per visit), so tens of thousands of visits a month |
| Photos in popups | R2 storage | (part of the 10 GB) | 100 photos ≈ 15–25 MB |
| Response forms | A small Cloudflare Worker | 100,000 requests a day | A few requests per response |
| Answers and photos waiting to be fetched | Private R2 storage and writes | (part of the 10 GB) · 1 million writes | A few writes per response; removed from Cloudflare once in QGIS |
| Maps saved on phones | R2 storage and reads | (part of the 10 GB and 10 million reads) | A few MB to a few tens of MB per area, read in 4 MB blocks |
| Offline background map | Cut from Protomaps OpenStreetMap data | No charge | “© OpenStreetMap” credit shown on the map |
- Going over the free tier is unlikely for a single project. If it happens, extra R2 storage is $0.015 per GB a month, and Cloudflare's paid Workers plan starts at $5 a month (10 million requests included). Cloudflare asks for a card when you switch R2 on, but you pay nothing within the free tier.
- No per-response, per-map or per-user fees from us, ever. Unlimited maps and forms.
- Published maps are public: anyone with the link can view them. Don't publish confidential data. Responses are private: they're never shown on the public map.
- Your data stays yours: maps, answers and photos go straight between your computer, your visitors and your Cloudflare account. Nothing passes through our servers, and the plugin sends us no analytics.
11. Get help
Email [email protected]. Include your QGIS version and, if possible, a screenshot. Every message gets an answer, usually within a day. If Web Map Kit isn't right for you, you can get a full refund within 30 days (refund policy).
Web Map Kit is free software under the GNU GPL v2 or later. © 2026 Byteloom (Pvt) Ltd.