Map

The simplest usage: a Leaflet map centred on London. Leaflet 1.9.4 ships inside the Extras package rather than loading from a CDN, so this map needs no token, no network dependency beyond the tiles, and no CSP entry for a third-party script host.

The map fills its container, so give that container a height - a map inside a parent with no height of its own collapses to nothing.

Markers are added imperatively and keyed by a string id, so each one can be moved, removed or replaced on its own. PopupHtml renders raw HTML and PopupText is escaped for you - pass anything user-supplied through the latter. Set Alt on every marker: it becomes the accessible name, and without one a screen reader reads a row of indistinguishable "marker" entries.

Wait for OnReady before calling any map method; until then the underlying map does not exist yet and the call throws. SyncMarkers replaces the whole set in a single interop call, which is worth reaching for over a loop of AddMarker on a Blazor Server circuit.

Add random marker

Clear all

Open London popup

Fit to markers

Seed markers are added on OnReady. Try the buttons.

Draw polylines, polygons, circles (radius in metres, so they stay geographically true as you zoom) and rectangles. Each layer carries a string id, so adding a shape under an id that already exists replaces it rather than stacking a second copy.

BitMapVectorPathStyle covers stroke colour, width, opacity, dash pattern and offset, line cap and join, and the fill. Note Fill = false is not the same as a zero fill opacity: an invisible fill is still rendered and still swallows clicks. Clicking a shape raises OnVectorClick with the layer id, the kind of geometry, and where the click landed.

Redraw

Clear vectors

Click Redraw to draw shapes, then click a shape.

Load any GeoJSON document as a styled layer. It is passed as a string rather than a modelled object graph - GeoJSON is already the wire format, so serializing it twice would be pure overhead on a large payload.

Clicking a feature raises OnGeoJsonFeatureClick with that feature's properties as a JsonElement, so you can read whatever fields your data actually carries without modelling them up front. Treat those properties as untrusted: they are data, and rendering them as HTML is how a GeoJSON document turns into a script injection.

Load GeoJSON

Remove layer

Click 'Load GeoJSON', then click a feature.

Switch the basemap at runtime by assigning a new Provider instance - any XYZ template with {z}, {x} and {y} placeholders is accepted, plus the optional {s} subdomain.

Set TileAttribution to whatever the tile source requires. This is a licence term, not decoration: OpenStreetMap-derived tiles must credit "© OpenStreetMap contributors" visibly, and the public tile.openstreetmap.org server is explicitly not for production traffic.

OSM default

Carto Voyager

OpenTopoMap

OnClick and OnDoubleClick report where the pointer landed, and only when the click did not hit a marker or a vector layer - those raise their own events instead.

OnViewChanged fires after a pan or zoom settles. Every provider coalesces the burst of move and zoom events a single drag produces into one notification per idle window, because each one is an interop round-trip - a SignalR message per event under Blazor Server. GetView reads the same snapshot on demand.

OnContextMenu reports a right-click (or a long press on touch) with the coordinate under the pointer - the usual way to offer "add a marker here". The browser's own menu still opens unless the provider sets SuppressBrowserContextMenu; only suppress it when you put a menu of your own in its place, because taking it away costs the user "open in new tab", "copy image" and their assistive-technology equivalents.

Fly to Tokyo

Log viewport

Pan/zoom or click the map.

Provider-level options: the interaction toggles (ScrollWheelZoom, Dragging, DoubleClickZoom, BoxZoom, KeyboardNavigation), the scale bar, and MaxBounds to keep the user inside a region. Changing any of them means assigning a new provider instance - the parameter is compared by reference.

On top of the basemap, AddTileOverlay stacks a second XYZ source with its own opacity and stacking order, which is how weather radar, labels or a heat layer are usually delivered.

Marker tooltips appear on hover - and on keyboard focus, since a marker is a tab stop - on Leaflet, MapLibre, Mapbox, OpenLayers and Azure Maps; ArcGIS and Cesium have no equivalent and use Title instead. ZIndexOffset is Leaflet-only. Each type's reference notes which backend honours what, because a parameter silently ignored by the provider you happen to be using is worse than one that is not there.

Add tooltip markers + fit

Add tile overlay

Log viewport

Toggle options or use the buttons.

Move the camera from code: ZoomIn/ZoomOut step by whole zoom levels, SetZoom jumps to an absolute one, PanBy shifts the view by a pixel offset, and PanTo recentres on a coordinate without touching the zoom the user chose.

The pan buttons are not just a convenience. WCAG 2.2 requires a single-pointer alternative to dragging (SC 2.5.7), so a map that can only be panned by dragging fails an audit - PanBy is what you build that alternative from.

FlyTo animates the move. When the visitor has asked their system for reduced motion, RespectReducedMotion (on by default) turns that flight into an instant jump to the same place; pass essential: true for a move whose motion is what carries the meaning. Locate asks the browser for the visitor's position - the browser shows its own permission prompt, and a refusal comes back as null rather than an exception.

Zoom in

Zoom out

Zoom 6

West

East

North

South

Fly to Rome

Locate me

Use the buttons to drive the camera from code.

The map canvas is focusable, labelled by AriaLabel, and described by KeyboardInstructions - which assistive tech reads and sighted keyboard users see the moment the map takes focus. EscapeToExit (on by default) lets Escape return focus to the page, so a focused map is never a keyboard trap.

AnnounceViewChanges reports the new centre and zoom through a polite live region, throttled by ViewAnnouncementThrottle so a drag cannot flood the screen reader. Supply ViewAnnouncementFormatter to announce a place name instead of a pair of decimals - far more useful to someone who cannot see the map.

CooperativeGestures stops the map swallowing the page scroll: a bare wheel scrolls the page and shows a hint, ctrl (⌘ on macOS) + wheel zooms, and on touch one finger scrolls while two fingers pan. Turn it on for any map embedded in a longer page.

None of that reaches the markers themselves, though: a map is a picture, and its pins are drawn rather than written. MarkerListMode renders the same markers as a table - name, coordinates, and a button that brings each one into view and raises the same OnMarkerClick a mouse user gets. ScreenReaderOnly leaves the map looking untouched while making that table reachable; Visible shows it to everyone, which is often the better answer for a store locator. It is also what survives being printed.

LoadState distinguishes the four things that can happen on the way to a rendered map - Idle, Loading, Ready, Failed, and Unsupported for a browser that cannot give a WebGL-backed provider a context at all. OnLoadStateChanged reports every transition; LoadingTemplate, ErrorTemplate and UnsupportedTemplate replace the built-in messages.

AutoResize (on by default) watches the container and re-measures the map itself, which also covers the classic case of a map inside a collapsed panel that would otherwise render grey forever - drag the resize handle below to see it. LazyLoad defers creating the map until it scrolls into view, so a map below the fold does not compete with the page's first paint.

State: Idle

@bind-Center and @bind-Zoom make the camera ordinary Blazor state: assigning either moves the map, and panning or zooming writes the new value straight back into your field. The component diffs the two directions against the map's last reported viewport, so echoing a value the map itself produced does not move it again.

Markers takes the whole set as a collection instead of a sequence of imperative calls. BitMapMarker is a record, so the component compares the incoming markers by value against what is already rendered and touches only the ones that changed - which matters beyond speed, because re-adding a marker closes its open popup and drops its keyboard focus. When most of the set changed it replaces everything in one batched call instead.

Markers are keyboard-reachable by default: Tab moves between them and Enter or Space opens the popup. Set Focusable="false" on decorative pins, and give every meaningful one an Alt so it announces as a place rather than as "marker".

Rome

Paris

Add a marker

Move the first marker

Centre 41.9028, 12.4964 - zoom 5.0 - 2 marker(s)

Set Clustering and nearby markers collapse into a bubble showing how many they stand for; clicking one zooms to fit its members. The map below carries 500 markers - drawn individually they are unreadable, and each one is its own DOM node and its own keyboard tab stop.

The grouping runs inside BitMap, in screen space, above whichever provider is active - so it behaves the same on all seven backends instead of needing a Leaflet plugin here and a GeoJSON source there. Screen space rather than degrees matters: a fixed distance in degrees covers far less ground near the poles, so a degree-based radius over-clusters at high latitudes.

RadiusPixels sets how aggressively markers merge, MaxZoom the level at which they all separate again, and CullOffscreen (on by default) keeps markers outside the viewport from reaching the provider at all - that is most of the performance win. OnClusterClick fires instead of OnMarkerClick, because a bubble is not one of your markers - and it reports the count either way, so turning ZoomOnClick off to handle the click yourself still tells you how big the bubble was. A bubble is a keyboard-reachable marker with a name of its own, so that name is translatable too: AriaLabelFormat sets it, with {0} standing for the count.

Scatter again

Click a bubble to zoom into it, or a single pin for its own click event.

SetLayerVisible and SetTileOverlayVisible toggle something off the map while keeping its definition, so switching it back on needs no re-declaration - and a provider swap brings it back in whatever state you left it. Prefer this to a zero opacity: an invisible layer is still drawn and still hit-tested, so it goes on swallowing clicks meant for what is underneath.

SetLayerStyle restyles a shape without restating its geometry, and SetTileOverlayOpacity blends a raster overlay against the basemap - the usual way weather or heat data is layered over a street map. A tile overlay also takes a MinZoom/MaxZoom window, so a source that only publishes some zooms does not answer with a grid of 404s, and Subdomains for sources that shard tiles across hostnames. ClearTileOverlays takes them all off at once, the counterpart of ClearMarkers and ClearVectorLayers.

RequestFullscreen takes the map's own container fullscreen rather than the page, so your overlay content and controls go with it. Call it from a real click: browsers only honour the request inside the short activation window a gesture opens. OnFullscreenChanged reports the state either way, including when the user leaves with Escape.

Hide the area

Restyle the area

Hide the overlay

Dim the overlay

Fullscreen

Toggle the area and the overlay, or restyle the area in place.

MarkerPopupTemplate makes a popup's content ordinary Blazor markup instead of an HTML string. That is worth preferring over PopupHtml for two reasons. Blazor escapes what it renders, so a popup built from data you do not control cannot become an injection point - the whole class of bug that a raw-HTML popup puts on you. And the content is live: components, event handlers, bindings and validation all work inside it, where an HTML string is inert. Click a marker below and use the button in its popup.

The popup is rendered by BitMap and pinned to its marker, so it looks and behaves the same on all seven backends rather than inheriting each vendor's. It is a role="dialog" named after its marker; opening it moves keyboard focus inside, Escape closes it and hands focus back to the map, and a click elsewhere on the map or the popup's own close button dismisses it. It follows its marker when the marker moves, and closes itself if that marker leaves the map.

The mechanics are worth knowing if you build something similar: the popup's DOM stays exactly where Blazor put it and only its transform is driven from JavaScript, recomputed per animation frame. Handing that DOM to the mapping library's own popup would move it out of the container Blazor patches by position, and the next render of that region would corrupt or throw.

Click a marker, then use the button inside its popup.

MapLibre GL JS renders vector tiles on the GPU, which is what makes smooth zooming and runtime restyling possible. It is BSD-licensed and needs no token for the default demo style - bring your own style URL and tile source for production.

The library is fetched from a CDN on first render, so it needs a script-src entry and a WebGL-capable browser; without one the component shows its unsupported state rather than a blank canvas.

OpenLayers 10 is loaded as ES modules through a small loader shipped in the Extras package - a real module, so the dynamic imports need no 'unsafe-eval' in your CSP. No token required; it defaults to OpenStreetMap raster tiles.

OpenLayers is the backend to reach for when the work is GIS-shaped rather than map-shaped: it is the only one here with first-class support for arbitrary projections and a wide format library.

Mapbox GL JS requires a public access token to load mapbox:// styles.

To get started:

1. Create a free account at mapbox.com(opens in a new tab)
2. Copy your default public token from the Access Tokens(opens in a new tab) page
3. Pass it to BitMapboxMapProvider.AccessToken

Without a valid token the map canvas will remain blank.

Security: only ship a public token (pk.*) to the browser, never a secret token (sk.*). Public tokens are visible to anyone using your site, so restrict each token to your production domains via the URL allowlist on the Access Tokens(opens in a new tab) page, set a billing cap, and use a separate token per environment so you can rotate or revoke without downtime. For stricter scenarios, mint a short-lived token from a server endpoint or proxy tile requests through your backend.

ArcGIS Maps SDK 5.0 is loaded as an ES module from the Esri CDN. The osm basemap works without an API key.

Security: if you supply an API key for non-OSM basemaps, configure HTTP referrer restrictions on the key in the ArcGIS Developer dashboard(opens in a new tab) so it can only be used from your own domains, and scope it to the minimum required services.

Azure Maps Web SDK v3 requires a subscription key for authentication.

To get started:

1. Create an Azure Maps account in the Azure Portal(opens in a new tab)
2. Navigate to your Maps account → Authentication → Shared Key Authentication
3. Copy the Primary Key and pass it to BitAzureMapsMapProvider.SubscriptionKey

Without a valid key the map will not render.

Security: shipping a shared subscription key to the browser is fine for demos but not recommended for production. For production, prefer Microsoft Entra ID or SAS token authentication: a backend mints a short-lived token and the client uses that instead of the primary key. If you must use a subscription key, restrict allowed origins on the Maps account and set usage alerts so a leaked key cannot quietly drain your quota.

CesiumJS renders a 3D globe. OSM imagery and smooth-ellipsoid terrain work without a token. A Cesium ion token unlocks Cesium World Terrain and Bing imagery.

Security: if you provide a Cesium ion token, create a dedicated token in the Cesium ion dashboard(opens in a new tab), grant only the asset access it needs, and add your production domains to the token's allowed URLs list so a copied token cannot be used from other origins.

IconUrl replaces the default pin with an image of your own, sized by IconWidth and IconHeight. The icons below are inline SVG data URIs, so they cost no extra request and can be recoloured from the same C# that builds the marker.

IconAnchorX and IconAnchorY say which pixel of the image sits on the coordinate, measured from its top-left corner. They default to the bottom centre, which is where a pin's tip is - so an icon that is a disc rather than a pin renders half a diameter too high until you anchor it at its own centre. Toggle it below: the ring marks the true coordinate, and only the centre-anchored disc actually sits on it.

Getting this right matters beyond neatness. An unanchored icon is off by its own height, which at street zoom is most of a city block - enough to put a delivery pin on the wrong side of the road.

BitMapLatLng and BitMapLatLngBounds carry the arithmetic that map work keeps needing, so it does not have to be rewritten - badly - in every app. DistanceTo measures the great-circle distance in metres, Offset travels a distance along a bearing, and ToBounds turns a radius into the box that frames it. Click anywhere on the map to drop a probe and see all three.

BitMapLatLngBounds answers the questions a viewport raises: FromMarkers and FromCoordinates build the smallest box around a set, Contains and Intersects test it, Extend grows it to take in one more place, and Pad leaves breathing room in map units rather than pixels. Boxes that cross the antimeridian are handled the short way round, which is where a hand-rolled min/max quietly produces a box wrapping the wrong way across the globe.

FitBounds takes both a pixel padding and a maxZoom ceiling - without the ceiling, framing a box around a single place drops you to street level. PanTo moves the centre while keeping the current zoom, and Project reports where a coordinate currently sits inside the container in CSS pixels, which is what you position an overlay of your own from.

Fit to the markers

Frame 5 km around Big Ben

Pan to Big Ben

Where is it on screen?

Click the map to drop a probe.

Style and Class land on the map's root element. The root is position:relative and fills its container, so this is also where you set the map's height - a map inside a parent with no height of its own collapses to nothing.

Set Dir="BitDir.Rtl" for right-to-left pages. The map canvas itself is direction-neutral - what flips is the component's own chrome: the keyboard-instructions panel, the cooperative-gestures hint, and any content you place in ChildContent.