BlazorGoogleMaps

BlazorGoogleMaps

️ Blazor interop for Google Maps JavaScript API A powerful and easy-to-use Blazor library for integrating Google Maps into your Blazor WebAssembly and Blazor Server applications.

---

Table of Contents

• Features
• Prerequisites
• Installation
• Quick Start
• Configuration
• Usage Examples
• Live Demos
• Breaking Changes
• Contributing

---

✨ Features

• Full Google Maps API Support - Markers, Polylines, Polygons, Circles, Info Windows, and more
• Blazor WebAssembly & Server - Works seamlessly with both hosting models
• Advanced Markers - Render Blazor components directly on the map
• Marker Clustering - Built-in support for marker clustering
• Heat Maps - Visualize data density with heat map layers
• ️ Directions & Routes - Full support for directions and route rendering
• Map Styling - Customize map appearance with style options
• Data Layers - Support for GeoJSON and other data formats
• ⚡ Event Handling - Comprehensive event support for interactive maps
• Drawing Tools - Built-in drawing manager for shapes and overlays
• ️ Static Maps - Render maps as plain images, with no JavaScript involved

---

Prerequisites

• .NET 8.0 or higher
• A valid Google Maps API key (Get one here)

---

Installation

Install the package via NuGet Package Manager:

dotnet add package BlazorGoogleMaps

Or via NuGet Package Manager Console:

Install-Package BlazorGoogleMaps

---

Quick Start

Step 1: Configure Your API Key

Add BlazorGoogleMaps to your Program.cs:

Option 1: Simple Configuration (Recommended)

builder.Services.AddBlazorGoogleMaps("YOUR_GOOGLE_API_KEY");

Option 2: Advanced Configuration

builder.Services.AddBlazorGoogleMaps(new GoogleMapsComponents.Maps.MapApiLoadOptions("YOUR_GOOGLE_API_KEY")
{
	Version = "beta",
	Libraries = "places,visualization,drawing,marker"
});

Option 3: Custom Key Service

For more complex scenarios (e.g., loading keys asynchronously from a database):

builder.Services.AddScoped();

⚠️ Legacy Method (Not Recommended): Adding the script tag directly to your HTML is still supported but not recommended.

---

Step 2: Add JavaScript References

Add the required JavaScript files to your wwwroot/index.html (Blazor WASM) or _Host.cshtml/_HostLayout.cshtml (Blazor Server):

Optional: For marker clustering support, add:

---

Usage Examples

Basic Map

Create a simple map component:

@page "/map"
@using GoogleMapsComponents
@using GoogleMapsComponents.Maps

Google Map

@code {
	private GoogleMap? _map1;
	private MapOptions _mapOptions = default!;

	protected override void OnInitialized()
	{
		_mapOptions = new MapOptions()
		{
			Zoom = 13,
			Center = new LatLngLiteral()
			{
				Lat = 13.505892,
				Lng = 100.8162
			},
			MapTypeId = MapTypeId.Roadmap
		};
	}

	private async Task AfterMapRender()
	{
		// Map is ready - you can perform additional initialization here
		var bounds = await LatLngBounds.CreateAsync(_map1!.JsRuntime);
	}
}

---

Advanced Map with Blazor Components

Render interactive Blazor components as markers (requires Google Maps v=beta and a MapId):

…

---

Static Maps

The Maps Static API returns a map as an ordinary image. No JavaScript is loaded and no interop object is created, which makes it a good fit for thumbnails, previews, e-mails, print views and pages that must stay lightweight. The trade-off is that the result is a picture: it cannot be panned or zoomed.

@page "/static-map"
@using GoogleMapsComponents.Maps
@using GoogleMapsComponents.Maps.StaticMaps

@code {
	private StaticMapOptions _options = new()
	{
		Center = new LatLngLiteral(13.505892, 100.8162),
		Zoom = 13,
		Width = 600,
		Height = 400,
		MapType = MapTypeId.Roadmap
	};
}

Markers, paths and polygons are added through the options. Locations accept either coordinates or a geocodable address, and locations that share a style belong in a single StaticMapMarker so that the URL stays short:

…

To build a URL outside of a component — to embed a map in an e-mail, a PDF or a report — inject StaticMapService, which is registered by AddBlazorGoogleMaps and uses the same API key as the rest of the library:

@inject StaticMapService StaticMaps

var url = await StaticMaps.GetUrlAsync(options);

EncodedPolyline accepts an already encoded polyline, so the OverviewPolyline of a route returned by the Directions API can be drawn on a static map directly. PolylineEncoder encodes and decodes those values.

Requests may optionally be signed. Signing needs the URL signing secret, which must never be shipped to a browser, so StaticMapUrlSigner.Sign and StaticMapService.GetSignedUrlAsync belong in server-side code only.

---

Live Demos

Explore interactive examples and learn more features:

• ** Server-Side Demo:** GitHub Repository
• ** Client-Side Demo:** Live Demo

The server-side demos include the most up-to-date examples covering:

• Markers and Info Windows
• Polylines, Polygons, and Circles
• Heat Maps and Data Layers
• Drawing Manager
• Routes and Directions
• Event Handling
• Map Styling
• And much more!

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

---

License

This project is licensed under the MIT License.

---

Acknowledgments

• Built with ❤️ for the Blazor community
• Powered by the Google Maps JavaScript API

---

Happy Mapping! ️