Interactive geographic map with declarative markers. Powered by MapLibre GL — open-source, no API key required. Ships with named tile presets including Auto, which follows the site theme automatically, and accepts raw style.json URLs.
Installation
dotnet add package Lumeo.Maps
One-time app setup (AddLumeo(), CSS & JS) is covered in the
installation guide.
Usage
@using Lumeo
<Map />
Satellite package. The Map lives in
Lumeo.Maps — install it alongside the core Lumeo
package. MapLibre GL and its stylesheet are loaded on demand from unpkg the
first time a Map mounts; no npm build step is required for consumers.
When to Use
Locating addresses, stores, or events on a slippy map
Visualizing point data sets with up to a few hundred markers
Pickers that capture a lat/lon from a click anywhere on the map
Read-only embeds in dashboards, contact pages, and event details
By default the Map lazy-loads MapLibre GL JS and its stylesheet from unpkg
the first time a Map mounts. That's the right tradeoff for most apps, but
it doesn't work behind a strict CSP, on an air-gapped intranet, or in compliance
scenarios where every third-party script call is a no-go.
The Lumeo CLI ships a one-shot installer that vendors MapLibre into
wwwroot/lib/lumeo-vendor/ and writes a bootstrap that wires up
window.lumeoCdn so the runtime loads from your own origin:
bash
# 1. Install the Lumeo CLI as a global dotnet tool$dotnet tool install -g Lumeo.Cli# 2. Vendor MapLibre into wwwroot/lib/lumeo-vendor/ and write the bootstrap$lumeo deps install --lib maplibre --write-bootstrap
# 3. Include the bootstrap before _content/Lumeo.Maps/js/* in index.html# <script src="js/lumeo-cdn-init.js"></script>
See CDN dependencies for the full list
of self-hostable libraries and the window.lumeoCdn override surface.
For more granular control (custom URL, integrity hash, alternative CDN) you can
set window.lumeoCdn = { mapLibreJs: "/my/cdn/maplibre-gl.js", mapLibreCss: "/my/cdn/maplibre-gl.css" };
before the first Map mounts.
API Reference
Map
Prop
Type
Default
Description
Center
(double Lat, double Lon)
(51.0, 10.4)
Map center. Two-way bindable.
Zoom
int
5
MapLibre zoom level (0–22). Two-way bindable.
Height
string
"400px"
CSS height applied to the container.
TileLayer
string
"Auto"
Tile preset or style URL. Auto (default) picks Positron (light) or DarkMatter (dark) based on the host page theme and swaps automatically when the user toggles dark mode. Other presets: Positron, DarkMatter, Voyager, CartoLight, CartoDark, OpenStreetMap, Satellite, Terrain. Also accepts a raw MapLibre style.json URL.
ZoomControl
bool
true
Show MapLibre's +/− zoom buttons.
Attribution
bool
true
Show the tile-provider attribution control. Tile providers' terms typically require attribution to stay visible — leave on.
ScrollWheelZoom
bool
true
Enable scroll-wheel zoom. Set to false in dense scrollable layouts to avoid trapping page scroll.
OnClick
EventCallback<(double, double)>
—
Fires with (lat, lon) when the user clicks the map.
Cluster
bool
false
Enable MapLibre-native marker clustering. Markers merge into count circles when close together.
Geolocate
bool
false
Show a "My location" button (browser Geolocation API).
Fullscreen
bool
false
Show a fullscreen toggle button.
Scale
bool
false
Show a metric scale bar in the bottom-left corner.
Search
bool
false
Show a Nominatim-backed geocoder search bar in the top-left.
Layers
string[]?
null
Preset names or { name, url } objects rendered as a chip-style layer switcher in the top-right.
Projection
string
"mercator"
MapLibre projection. "mercator" for a standard flat web map or "globe" for a 3-D spherical view (blends back to mercator above zoom 4).
AutoFitBounds
bool
false
When true, the map automatically fits its viewport to include all registered markers and shapes after the first render.
ChildContent
RenderFragment?
null
Place MapMarker, MapPolyline, MapPolygon, MapCircle, MapArc, MapHeatmap, and MapPopup children here.
Overlay
RenderFragment?
null
Content rendered as an absolutely-positioned layer inside the map (z-index 10). Use absolute-position classes on the child to place chips, legends, or badges in any corner.
Class
string?
null
Extra CSS classes on the root container.
MapMarker
Prop
Type
Default
Description
Lat
double
0
Latitude in decimal degrees.
Lon
double
0
Longitude in decimal degrees.
Title
string?
null
Tooltip on hover and fallback popup body.
IconUrl
string?
null
Bitmap icon URL (32×32 anchored bottom-center). When set, overrides Variant / Color / Icon.
Variant
string
"Default"
Visual style of the auto-generated marker: Default (filled circle), Outline, Pin (classic teardrop), or Dot (minimal).
Color
string?
null
Override the marker fill. Friendly names (red, green, yellow, blue, purple, pink, orange, teal, gray, slate) or any CSS color. Null = theme primary.
Label
string?
null
Text label rendered above the marker. Always visible by default; set LabelHoverOnly to show only on hover.
Highlighted
bool
false
Marks a "recommended" marker. With Cluster on, any cluster bubble containing a highlighted marker is tinted with --lumeo-map-cluster-highlight (default amber), so the recommendation stays visible while clustered. The pin itself is unchanged.
LabelHoverOnly
bool
false
When true, the Label is hidden until the marker is hovered. Useful on dense maps to reduce visual noise.
Icon
RenderFragment?
null
Inline content inside the marker circle — a letter, number, or <Blazicon> SVG.
Popup
RenderFragment?
null
Rich popup body. Falls back to Title when null. Styled as a shadcn card via map.css.
OnClick
EventCallback
—
Fires when the marker icon is clicked.
Draggable
bool
false
Allow the user to drag the marker to a new position.
OnDragEnd
EventCallback<(double, double)>
—
Fires with the new (lat, lon) after the user finishes dragging. Only fires when Draggable is true.
MapHeatmap
Prop
Type
Default
Description
Points
IEnumerable<(double Lat, double Lon, double Intensity)>
required
Heat point collection. Intensity should be in 0–1; use 1 for uniform weight.
Radius
int
20
Pixel radius of each point at full zoom. Scales with zoom automatically.
Opacity
double
0.8
Overall opacity of the heatmap layer (0–1).
ColorRamp
object[]?
null
Custom color ramp as alternating stop, cssColor values (e.g. new object[] { 0, "transparent", 1, "red" }). Defaults to a blue→cyan→yellow→red ramp.
MapPolyline
Prop
Type
Default
Description
Points
IEnumerable<(double Lat, double Lon)>
required
Ordered list of coordinates the polyline visits.
Color
string?
null
Stroke color. Friendly name or CSS color. Null = theme primary.
Weight
double
3
Stroke width in pixels.
Opacity
double
0.9
Stroke opacity (0–1).
Dashed
bool
false
Convenience toggle to render a standard "6 4" dash pattern. Ignored when DashArray is set explicitly.