---
title: "Google Maps block"
description: "An accessible Google Maps embed, available once you forward a Maps Embed API key."
requested_language: nl
language: en
translation_notice: "This page isn't translated yet"
url: https://docs.systhema.app/nl/payload/blocks/google-maps
version: unreleased (main)
docs_index: https://docs.systhema.app/nl/llms.txt
---
> This page isn't translated yet. Showing English.


The Google Maps block embeds a map with the Google Maps Embed API.

## Where it is offered

Offered in the `root`, `region` and `fragment` tiers, so editors can place it on a page, inside a Section, Feature or Gallery body, and inside cards, columns and accordions. It is never offered in the `slot` tier. The block is on exactly when you forward a key: `googleMaps: { apiKey: process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY }`. A missing or blank key leaves it off, and `enabled: false` turns it off even with a key; see [Plugin options](https://docs.systhema.app/nl/payload/plugin-options.md).

## Fields

<!-- generated:block-fields googleMap -->

| Field         | Type       | Label          | Default   | Notes                                                                                                                                                                                                                                                                                                                                                                   |
| ------------- | ---------- | -------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `_inCard`     | `checkbox` |                |           |                                                                                                                                                                                                                                                                                                                                                                         |
| `_tier`       | `select`   |                |           | Options: `root` (Root), `region` (Region), `fragment` (Fragment), `slot` (Slot), `stack` (Stack)                                                                                                                                                                                                                                                                        |
| `address`     | `text`     | Define address |           | Required                                                                                                                                                                                                                                                                                                                                                                |
| `aspectRatio` | `select`   | Aspect Ratio   | `3/2`     | Shown when `siblingData?.[addressKey]`; Required; Shown when `siblingData?.[addressKey]`; Options: `21/9-md` (21:9 on desktop, 4:3 on mobile), `21/9` (cinema - 21:9), `16/9` (video - 16:9), `4/3` (landscape photo - 4:3), `3/2` (landscape photo - 3:2), `1/1` (square - 1:1), `3/4` (portrait photo - 3:4), `4/5` (instagram - 4:5), `9/16` (vertical video - 9:16) |
| `cardWidth`   | `radio`    | Width          | `default` | Shown when `siblingData?.[addressKey]`; Required; Shown when `hasValue(siblingData)&&siblingData?._inCard===true`; Options: `default` (Default), `card` (Card width)                                                                                                                                                                                                    |
| `width`       | `radio`    | Width          | `default` | Shown when `siblingData?.[addressKey]`; Required; Shown when `(hasValue?hasValue(siblingData):true)&&siblingData?._tier!=="fragment"`; Options: `default` (Default), `container` (Container), `screen` (Screen)                                                                                                                                                         |
| `zoom`        | `number`   | Default zoom   | `14`      | Required; Shown when `siblingData?.[addressKey]`                                                                                                                                                                                                                                                                                                                        |

<!-- /generated -->

As a direct child of a card it gains a **Card width** option; see [Media inside a card](https://docs.systhema.app/nl/payload/blocks/card.md#media-inside-a-card).

## Without a key

A stored Google Maps block whose key has since been removed renders nothing instead of an empty iframe.

## Rendered output

Renders `GoogleMapEmbed`, a titled, accessible iframe inside [MediaWrapper](https://docs.systhema.app/nl/components/media-wrapper.md) and [Figure](https://docs.systhema.app/nl/components/figure.md).

## Converter

`googleMapConverter` requires a string `address` and the configured Maps Embed API key. It wraps GoogleMapEmbed in MediaWrapper and Figure, defaults zoom to 14 and aspect ratio to `3/2`, and respects direct-card width. GoogleMapEmbed builds the place URL, loads lazily, and derives an accessible iframe title from the address.

## Customizing

Import `GoogleMapsBlock` from `@systhemaui/payload/blocks` as the starting schema for a project block. Register the definition and your renderer through `customBlocks`, using `type: 'block'` and the editor tiers you intend to support. A distinct slug creates a new block; a converter registered under the existing `googleMap` slug takes precedence over the built-in converter. Keep the fields that renderer reads, including populated relationships and nested editor states.

See [Registering blocks](https://docs.systhema.app/nl/payload/blocks.md#registering-blocks) for the configuration pattern and [Converters](https://docs.systhema.app/nl/payload/custom-blocks/converters.md) for the renderer contract. A project converter used in client-mode live preview also needs [browser registration](https://docs.systhema.app/nl/payload/frontend/live-preview/client-mode.md).

## Related

- [Feature block](https://docs.systhema.app/nl/payload/blocks/feature.md)
- [Hero blocks](https://docs.systhema.app/nl/payload/blocks/hero.md)