How do I add the Map block to a Hugo site?

Add a "block: map" entry to the sections list in your page's front matter, then fill in the content fields. HugoBlox renders it automatically — copy the example config above as a starting point.

Is the Map block free to use?

Yes. Every HugoBlox block is free and open-source under the MIT license — use it in personal and commercial projects, with no attribution required.

Can I customize the Map block?

Yes. It exposes 20 content options, plus 7 design options, and inherits the shared block settings for background, spacing, and colors. You can also describe the changes you want to Hugo Chat AI and it will edit the config for you.

Does the Map block work with any Hugo theme?

The block ships in the open-source HugoBlox kit. Add the kit to any Hugo site and the block becomes available in your page sections — there is no theme lock-in.

hugoblox.com/blocks/map

ContactFree · MITPreact · interactive

Map block

An interactive, open-source map (MapLibre + OpenFreeMap, no API key) with an address card and directions CTA.

Customize with AI View source

Add it to any Hugo page's sections list — no build step.

v1.0.0Version

20Options

MITLicense

Quick start

Add the Map block

Drop this into your page's front matter, under the sections list. Edit the values, and HugoBlox renders the block — no build step.

Add to your page's sections

- block: map
  content:
    title: Visit the lab
    subtitle: We're on the Stanford campus — drop in any time during office hours.
    location:
      address: "353 Jane Stanford Way\nStanford, CA 94305\nUnited States"
      lat: 37.4275
      lng: -122.1697
    zoom: 15
    cta:
      directions:
        text: Get directions
      phone: +1-650-555-0142
      email: [email protected]
  design:
    layout: side-by-side
    height: md
    style: streets

Flexibility

Layouts & variants

Switch the block's design with these presets — no custom CSS.

layoutLayout variant. 'side-by-side' shows the address card next to the map (default). 'map-only' renders just the map with an optional title above.

side-by-sidedefaultmap-only

heightMap viewport height preset.

smmddefaultlgfull

stylePer-block override of the site's default map style (configured under `hugoblox.maps.style` in params.yaml).

streetslightdarkbright

borderOuter border treatment.

roundeddefaultnone

Reference

Configuration

Every option the Map block accepts, generated from its schema.

Content options

Properties set under the block's content key.

Property	Type	Default	Description
`title`	`string`	—	Heading shown above the map or in the address card (supports Markdown bold/italic).
`subtitle`	`string`	—	Supporting sentence below the title — context, hours, or directions hint.
`location`	`object`	—	Single primary location. Required when not using `markers[]`. Latitude and longitude are required to render the map; address is optional but recommended (displayed in the side address card).
`location.address`	`string`	—	Postal address shown in the address card. Use newlines (block-literal `\|` in YAML) to split into multiple lines.
`location.lat`required	`number`	—	Latitude in decimal degrees (WGS84). Positive = north of equator, negative = south.
`location.lng`required	`number`	—	Longitude in decimal degrees (WGS84). Positive = east of Greenwich, negative = west.
`zoom`	`number`	14	Initial zoom level. 1 = whole world, 10 = city, 14 = neighbourhood (default), 17 = building, 19 = max useful for street maps.
`markers`	`object[]`	—	List of map markers. When present, overrides `location` and the map auto-fits to enclose every marker. Use for directories, multi-office maps, conference venues, etc.
`markers[].lat`required	`number`	—	Marker latitude in decimal degrees.
`markers[].lng`required	`number`	—	Marker longitude in decimal degrees.
`markers[].title`	`string`	—	Marker name shown in the popup heading when the pin is clicked.
`markers[].description`	`string`	—	Secondary text shown in the popup body — short address, room number, or a one-line note.
`markers[].url`	`string`	—	Optional URL — adds a 'View details →' link to the popup that navigates to this page when clicked.
`markers[].icon`	`string`	—	(Reserved) Icon name from the icon library — future support for custom marker icons. Currently ignored; markers use the default brand-coloured pin.
`cta`	`object`	—	Address card calls-to-action: directions button, phone, and email. All optional. Phone and email are shown as tap-to-call / tap-to-email links.
`cta.directions`	`object`	—	Directions button — links to a maps service with routing pre-filled to the location.
`cta.directions.text`	`string`	Get directions	Button label.
`cta.directions.url`	`string`	—	Optional URL override. When omitted, an OpenStreetMap directions URL is auto-generated from the location's lat/lng. Set this to point users at Google Maps, Apple Maps, or a venue-specific page.
`cta.phone`	`string`	—	Phone number shown in the address card as a tel: link. Include country code for international friendliness.
`cta.email`	`string`	—	Contact email shown in the address card as a mailto: link.

Design options

Properties set under the block's design key — shared background, spacing, and color settings apply on top.

Property	Type	Default	Description
`layout`	`side-by-side \| map-only`	side-by-side	Layout variant. 'side-by-side' shows the address card next to the map (default). 'map-only' renders just the map with an optional title above.
`height`	`sm \| md \| lg \| full`	md	Map viewport height preset.
`style`	`streets \| light \| dark \| bright`	—	Per-block override of the site's default map style (configured under `hugoblox.maps.style` in params.yaml).
`border`	`rounded \| none`	rounded	Outer border treatment.
`interactive`	`boolean`	true	Allow pan, zoom, and marker interaction. Disable for a 'preview-only' map that behaves like an image.
`cooperative_gestures`	`boolean`	—	Require Cmd/Ctrl + scroll to zoom on desktop and two-finger pan on touch devices. Prevents the map from hijacking page scroll when the user scrolls through it. Overrides the site-level default in `hugoblox.maps.cooperative_gestures`.
`attribution`	`boolean`	true	Show the map attribution control. Overrides `hugoblox.maps.attribution`. Required by OpenStreetMap / OpenFreeMap terms — only disable if attribution is shown elsewhere on the page.

Compose

Works well with

Blocks that pair naturally with Map on the same page.

Contact Info CTA Card Team Showcase

Frequently asked

Map block FAQ

Add a "block: map" entry to the sections list in your page's front matter, then fill in the content fields. HugoBlox renders it automatically — copy the example config above as a starting point.

Ready to build with the Map block?

Customize with AI View source