Google Maps block
An accessible Google Maps embed, available once you forward a Maps Embed API key.
On this page
The Google Maps block embeds a map with the Google Maps Embed API.
Where it is offeredLink to this section
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.
FieldsLink to this section
| 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] |
As a direct child of a card it gains a Card width option; see Media inside a card.
Without a keyLink to this section
A stored Google Maps block whose key has since been removed renders nothing instead of an empty iframe.
Rendered outputLink to this section
Renders GoogleMapEmbed, a titled, accessible iframe inside MediaWrapper and Figure.
ConverterLink to this section
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.
CustomizingLink to this section
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 for the configuration pattern and Converters for the renderer contract. A project converter used in client-mode live preview also needs browser registration.