As more Drupal teams start building pages with Drupal Canvas, a practical question comes up: how do you insert a Google Map or OpenStreetMap map into a Canvas page without creating a one-off component for every project?
We built Canvas Map module to provide that missing piece. The first stable release adds ready-to-use Google Maps and OpenStreetMap components to the Canvas editor.
The module scope is intentionally focused. An editor can place a single map in a page, enter a location, adjust its presentation, and keep working inside Canvas. The module does not try to replace Drupal's established tools for storing, querying, or visualizing geographic data.
Maps are a common part of contact pages, office listings, event pages, venue information, and other editorial layouts. In many of those cases, the requirement is simple: show one location as part of the page being assembled.
Drupal already has a mature mapping ecosystem. Modules such as Geofield, Geofield Map, and Leaflet are appropriate when location is structured content: for example, when a site needs map displays built from Views, multiple markers, spatial queries, or more advanced layers.
A map placed directly in a Canvas composition is a different use case. We wanted editors to be able to add that map in the same way they add other Canvas components, with no field-modeling exercise and no custom frontend integration.
What Canvas Map adds to Drupal Canvas
Canvas Map is a small component-provider framework with two optional provider submodules:
- Google Map: pin location set through address or place name, Google place ID, or latitude and longitude. It needs Google Maps Embed API key to work.
- OpenStreetMap: pin location is set via latitude and longitude only, but requires no API key or provider account.
Both components appear in the Maps section of the Canvas component library. Editors can configure zoom, map center, aspect ratio, corner radius, custom CSS classes, and an accessible name. Provider-specific controls stay with the relevant component: Google Map offers road map and satellite modes, while OpenStreetMap offers tile styles and an optional location pin.
The Google Maps and OpenStreetMap integrations can be enabled independently or used together. A site that only needs OpenStreetMap does not need to configure Google credentials, and a Google-only site does not load an unused OpenStreetMap component.
Adding Google Maps to a Drupal Canvas page
Canvas Map requires Drupal 11.3 or later and Canvas 1.8 or later. For the Google Maps component, install Canvas Map together with the Key module:
composer require drupal/canvas_map drupal/key
drush pm:install canvas_map_google_mapsThe Google provider uses the Maps Embed API. After enabling that API in a Google Cloud project, create a Key entity at /admin/config/system/keys, then select it on the Canvas Map settings page at /admin/config/system/canvas-map. An optional region setting is available for regional map behavior.
Even though the module stores the Key entity ID in configuration, not the API key value itself, the selected key is still sent to the browser as part of Google's iframe URL, which is how the Maps Embed API works. For that reason, the key should be restricted to the required API and to the site's permitted HTTP referrers in Google Cloud.
Once configuration is complete, open a page in Canvas, find Google Map under Maps, and drag it into the layout. The location can be:
- an address or place name, such as
Tbilisi, Georgia; - a Google place ID prefixed with
place_id:; or - a latitude and longitude pair, such as
41.7151, 44.8271.
The result is visible while the page is being composed, so editors can adjust the location, zoom, display mode, and dimensions without leaving Canvas.
Adding OpenStreetMap to a Drupal Canvas page
For a map that does not require an API key or provider account, enable the OpenStreetMap submodule:
composer require drupal/canvas_map
drush pm:install canvas_map_osmThere is no site-wide provider configuration. Add OpenStreetMap from the Maps section in Canvas and enter the location as latitude and longitude. That's it.
The component supports several tile styles and can show or hide a pin at the selected coordinates. It renders an interactive map using WebGL, so it needs a browser and device with WebGL support. Some available tile styles are delivered by services other than the OpenStreetMap project itself; site owners should review the provider terms and privacy implications that apply to their chosen style.
A lightweight embed, with the privacy implications stated
Both providers render inside an iframe. We chose this approach so the module does not add a map SDK to the host page and does not make server-side requests to a map provider. The browser loads the selected provider only where a map component is present.
An iframe is still a live third-party request. Canvas Map does not gate map loading behind consent by default. Sites with consent requirements can integrate with Klaro: it includes a Google Maps service definition, and Canvas Map supplies a disabled-by-default definition for OpenStreetMap. Sites using the CSP module also receive the required frame-src integration for enabled providers.
These details matter for a map component because embedding a map is not only a visual decision. The site's privacy policy, consent model, API restrictions, and chosen tile provider remain part of the implementation.
When Canvas Map is the right fit
Canvas Map is intended for editorial map placements inside Canvas. It is a good fit when:
- an editor needs to add one map to a contact, event, office, or venue page;
- the location belongs to the page composition rather than the site's structured data model; or
- a development team wants a small base for adding another iframe-based map provider.
It is not intended to manage geospatial fields, build a map from View results, display many content-derived markers, perform proximity searches, or provide GIS-style layers. Those requirements are better served by Geofield, Geofield Map, Leaflet, or a project-specific mapping architecture.
Drawing that boundary was important to us. Canvas Map handles the common page-building task without obscuring the point at which a site really needs structured geographic data.
Extending Canvas Map with another provider
The module includes a public provider plugin API. A custom module can define a provider plugin, its Canvas component, provider-specific settings, and iframe URL generation while reusing Canvas Map's shared foundations.
That makes it possible to integrate another commercial service, an internal mapping endpoint, or a project-specific provider without patching the Google Maps or OpenStreetMap implementations. The project documentation includes a provider guide and API reference for this workflow.
Canvas Map 1.0.0 is available from the project page on Drupal.org. After installation, enable the provider submodule you need and look for the Maps section in the Canvas component library. If the components do not appear immediately, rebuild Drupal's caches.
Bug reports, provider use cases, and contributions are welcome in the module issue queue.