Map
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
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. |
| 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. |
| DashArray | string? | null | Custom SVG dash pattern (e.g. "6 4"). Null = solid. |
| HoverColor | string? | null | Stroke color applied on hover. Null = no hover highlight. |
| HoverWeight | double? | null | Stroke width applied on hover. Null = same as Weight. |
| Animate | bool | false | Animate the line drawing on first render (draws from start to end over ~1 s). |
| Tooltip | string? | null | Hover tooltip text. |
| PopupHtml | string? | null | HTML string rendered inside a click popup. |
MapPolygon
| Prop | Type | Default | Description |
|---|---|---|---|
| Points | IEnumerable<(double Lat, double Lon)> | required | Ordered points forming the polygon ring. First and last are connected automatically. |
| Color | string? | null | Border stroke color. |
| FillColor | string? | null | Fill color. Null = same as Color. |
| Weight | double | 2 | Border stroke width in pixels. |
| Opacity | double | 0.9 | Border stroke opacity (0–1). |
| FillOpacity | double | 0.2 | Fill opacity (0–1). |
| Tooltip | string? | null | Hover tooltip text. |
| PopupHtml | string? | null | HTML string rendered inside a click popup. |
MapCircle
| Prop | Type | Default | Description |
|---|---|---|---|
| Center | (double Lat, double Lon) | (0, 0) | Circle center in decimal degrees. |
| RadiusMeters | double | 100 | Radius in real-world meters. Pixel size scales with zoom. |
| Color | string? | null | Border stroke color. |
| FillColor | string? | null | Fill color. Null = same as Color. |
| Weight | double | 2 | Border stroke width in pixels. |
| Opacity | double | 0.9 | Border stroke opacity (0–1). |
| FillOpacity | double | 0.2 | Fill opacity (0–1). |
| Tooltip | string? | null | Hover tooltip text. |
| PopupHtml | string? | null | HTML string rendered inside a click popup. |
MapArc
| Prop | Type | Default | Description |
|---|---|---|---|
| From | (double Lat, double Lon) | (0, 0) | Arc start point. |
| To | (double Lat, double Lon) | (0, 0) | Arc end point. |
| Curvature | double | 0.25 | Height of the arc above the straight chord as a fraction of chord length. 0 = straight line, 1 = full-semicircle bulge. |
| Color | string? | null | Stroke color. Friendly name or CSS color. Null = theme primary. |
| Weight | double | 2.5 | Stroke width in pixels. |
| Opacity | double | 0.9 | Stroke opacity (0–1). |
| Dashed | bool | true | Arcs are dashed by default. Set to false for a solid line. Ignored when DashArray is set explicitly. |
| DashArray | string? | "5 6" | Custom SVG dash pattern. Overrides Dashed. |
| HoverColor | string? | null | Stroke color applied on hover. Null = no hover highlight. |
| HoverWeight | double? | null | Stroke width applied on hover. Null = same as Weight. |
| Animate | bool | false | Animate the arc drawing on first render (draws from start to end over ~1 s). |
| Tooltip | string? | null | Hover tooltip text. |
| PopupHtml | string? | null | HTML string rendered inside a click popup. |
MapPopup
| Prop | Type | Default | Description |
|---|---|---|---|
| Lat | double | 0 | Latitude of the popup anchor point. |
| Lon | double | 0 | Longitude of the popup anchor point. |
| IsOpen | bool | false | Whether the popup is visible. Two-way bindable via IsOpenChanged. |
| CloseButton | bool | true | Show a close (×) button inside the popup. |
| CloseOnClick | bool | true | Close the popup when the user clicks the map background. |
| Html | string? | null | HTML string for the popup body. Overrides ChildContent. |
| ChildContent | RenderFragment? | null | Rich popup body as a Blazor render fragment. |
MapLegend / MapLegendItem
| Prop | Type | Default | Description |
|---|---|---|---|
| MapLegend.Title | string? | null | Optional heading shown above the legend rows. |
| MapLegend.Position | string | "bottom-left" | Corner shorthand: "top-left", "top-right", "bottom-left", "bottom-right". Or pass Tailwind classes via Class. |
| MapLegendItem.Color | string? | null | Dot fill color. Friendly names (red, green, blue, teal, etc.) or any CSS color. |
| MapLegendItem.Label | string? | null | Text label shown beside the colored dot. |