When to use it. A MapKit view showing markers and polyline paths. Feed it the native payload or a GeoJSON FeatureCollection; the camera auto-fits everything it's given. Optionally interactive.
Type
map
Default size
4 rows × 4 columns
Symbol
map.fill
Docs
Docs complete
Search for it as
location
gps
pin
geo
route
places
Rendered by the app
Fields
7 fields you can set on a map control. Every control also takes the shared fields (id, position, span, sync, action).
Fields
Field
Type
Default
What it does
Map stylemapStyle
choiceone of 4
standard
Which kind of map to draw
Draws the map as a street map, satellite photos, photos with labels, or a whole-Earth globe.
standarddefaulta normal street map
satellitesatellite photos with no labels
hybridsatellite photos with street and place labels
globethe whole Earth seen from space, ignoring Zoom
Pan and zoommapInteractive
on / off
true(on)
Let people drag and zoom
When on you can pan and zoom the map with your fingers; off locks the view.
ZoommapZoom
number
0.01
How close the map starts
Sets how much ground a single-point view shows, as a span in degrees; smaller zooms in closer.
Titlelabel
text
—
A title above the map
Shows this text as a header above the map.
Pin colortint
color
#667eea
Color of the pins
Colors every pin that does not bring its own color.
mapConfigmapConfig
object
—
Teach the map a feed
Tells the map which properties of your data set pin size, color, label and ripple.
HeightcontrolHeight
number120–1200step 10
—
How tall the map is
Sets the map height from 120 to 1200 points when the grid flows; 2-D grids use row span instead.
Emits and receives
What this control sends when you use it, and what it can show or follow when data arrives.
Receives
Receives
Takes
From
Type
What it does
pinsshow
hub, mqtt, http, store
json
pins, each a coordinate with an optional label and color, paths through several points, and an optional center
the pins and paths are redrawn and the camera refits to show them, until you pan or zoom yourself; a pin marked ripple pulses to ask for attention
The endpoint's raw response is consumed as-is: each quake's [lng, lat, depth]
position becomes a marker, properties.mag scales it, properties.place labels it,
and M4.0+ quakes ripple. No valuePath is needed — the whole document is the payload.
"globe" is the style to reach for whenever the data is global. A fitted region
can't express "the whole planet" — MapKit's Mercator projection crops a 180°
latitude span to roughly 120° of longitude in a portrait cell, so a worldwide feed
opened on a partial world you had to pinch out of. The globe style instead points
the camera at the data's centroid from ~42,000 km, which keeps every marker and
both poles in frame at any spread.
The map receives its data as a JSON string via Sync — or, since it is a
JSON-document control, as a plain JSON object/array, which the app encodes for it.
That means an HTTP source can point straight at a GeoJSON endpoint with
no server in between.
Optional. Drawn as a single pin only when there are no markers and no paths
markers
array
Optional array of pins
markers[].coordinate
[lat, lng]
Required. lat + lng (or lon/longitude) keys are also accepted
markers[].color
string
Hex fill; falls back to the control's tint
markers[].size
number
Dot diameter in points (default 12, clamped 4–60)
markers[].label
string
Text under the dot (title is used when absent)
markers[].ripple
bool | object
An expanding ring animated at this marker
markers[].ripple.color
string
Ring color (default: the marker's color)
markers[].ripple.period
number
Seconds per expansion (default 1.6)
markers[].ripple.radius
number
Widest ring radius in points (default 44)
paths
array
Optional array of polyline paths
paths[].points
[[lat, lng], ...]
Array of coordinate pairs
paths[].color
string
Hex color for this path line
ripple is data, not a wire event: it rides in the payload, so an HTTP poll can
raise it. That's different from Pulse, which flashes the whole control when a
MeshSocket frame arrives.
GeoJSON payloads
A payload whose type is FeatureCollection, Feature, or a bare geometry is read
as GeoJSON:
GeoJSON positions are [longitude, latitude] — the reverse of the native
payload's [lat, lng]. The app flips them for you; don't pre-flip your feed.
A third element (elevation/depth) is ignored.
Feature properties style each marker. Recognized without configuration:
color or marker-color, size or marker-size, label or name, title,
ripple: true; paths read color or stroke.
For a feed you don't control, mapConfig points at whatever properties it does
have:
mapConfig field
Type
Default
Description
markerSizeProperty
string
—
Numeric property that drives marker diameter
markerSizeDomain
[number, number]
[0, 10]
Input range of that property
markerSizeRange
[number, number]
[8, 30]
Output diameter in points (clamped at the ends)
markerColorProperty
string
—
Property holding a hex color
markerLabelProperty
string
—
Property used as the marker label
rippleProperty
string
—
Numeric property that decides which markers ripple
rippleThreshold
number
0
rippleProperty >= threshold ⇒ that marker ripples
ripple
object
—
Ring styling (color/period/radius) for those markers
maxMarkers
number
400
Cap on rendered markers — public feeds can be unbounded
Object-array feeds (not GeoJSON)
Many public feeds are plain-JSON arrays of point objects, not GeoJSON — a flight feed
{ "ac": [ { "lat": …, "lon": …, "flight": … } ] }, a single-point tracker (the ISS:
{ "latitude": …, "longitude": … }), or a raw [lng, lat, weight] grid. Point the map
at those by naming the coordinate fields; all the styling keys above still apply (their
"property" is a key on each object). Declaring markersPath or markerLatProperty
switches the map into this mode — ordinary payloads are unaffected.
mapConfig field
Type
Default
Description
markersPath
string
—
Dot-path to the array of objects (e.g. "ac"). Omit if the payload is the array, or a single point object.
markerLatProperty / markerLngProperty
string
—
Latitude/longitude keys on each object. lat/lon/latitude/longitude are auto-detected when omitted.
markerIdProperty
string
—
Stable identity per marker across polls — required for smooth motion with more than one marker (e.g. "hex").
coordinateOrder
string
"lnglat"
For raw [a, b, weight] number triples (e.g. NOAA aurora): "lnglat" or "latlng". The third element feeds size (markerSizeDomain) and ripple.
minWeight
number
0
Number-triple mode: drop points weaker than this before the maxMarkers cap keeps the strongest.
Marker style & SF Symbols
mapConfig field
Type
Default
Description
markerStyle
enum
"dot"
dot, symbol (a bare SF Symbol), or puck (an SF Symbol inside a filled circle).
markerSymbol
string
—
Default SF Symbol name for symbol/puck (e.g. "airplane").
markerSymbolProperty
string
—
Per-object property giving an SF Symbol name, overriding markerSymbol. A feed property named symbol/sf-symbol is honored without config.
Motion & camera
mapConfig field
Type
Default
Description
motion
bool
false
Smoothly interpolate marker positions between polls so they glide instead of teleporting. Needs markerIdProperty for >1 marker.
motionDuration
number
1.2
Seconds a glide takes — set near your poll interval.
recenter
enum
"auto"
How the camera reacts to new data: auto (frame + follow, but stop the moment the user pans/zooms), always (refit every update), initial (frame once), off (never move).
center
[lat, lng]
—
Pin the camera to a fixed point (and the control's mapZoom) instead of fitting the data's bounds — e.g. frame a high-latitude feed.
Every marker renders as a colored dot with a white ring; label/title shows beneath it
A center with no markers and no paths draws one pin in the control's tint color
Paths render as polylines with their individual colors
The camera auto-fits the bounding box of all markers and path points (padded);
with a single point it centers there at mapZoom
mapStyle: "globe" overrides that fit: satellite imagery with realistic
elevation, viewed from ~42,000 km at the data's centroid, so the whole Earth is
in frame. Use it for any worldwide feed; mapZoom has no effect on it
Rippling markers animate an expanding ring at their coordinate; ripples are
suppressed under Reduce Motion
When no data is synced, shows a placeholder with a map icon
Map interactions (pan/zoom) don't fire any actions — display only
A re-broadcast that resolves to the same center is ignored, so a live feed
doesn't fight the user's panning
Notes
The sync value may be a JSON string or a JSON object/array — both work
Multiple paths with different colors can show different routes, zones, etc.
mapZoom is a coordinate span — smaller values = more zoomed in. It only applies
when there's a single point to show; multi-marker data is auto-fitted
Legacy { "center": …, "paths": … } payloads are unchanged — markers is additive