SF Symbol placeholder (e.g., for camera feed)
A static symbol standing in for a feed.
JSON 7 lines
{
"type": "image",
"id": "cam-front",
"position": [0, 0],
"span": [1, 2],
"systemName": "video.fill"
}
A photo or an icon
When to use it. A static or synced image display. Can show SF Symbols, remote URLs, or synced image URLs.
imagephoto
9 fields you can set on a image control. Every control also takes the shared fields (id, position, span, sync, action).
| Field | Type | Default | What it does |
|---|---|---|---|
SymbolsystemName | text | — | The symbol shown when there is no picture Draws this SF Symbol when no image loads or none is given, scaled to fill the cell (never below about 28 pt) and tinted. |
urlurl | text | — | The picture to load from the web Loads and shows the image at this absolute web address; a failed or missing address falls back to the symbol. |
Shapestyle | choiceone of 2 | — | Square-ish or round corners Clips the picture to rounded corners (12 pt) or a full circle; an image roundness value overrides it.
|
Image roundnessimageCornerRadius | number0–60step 1 | — | How round the picture corners are Rounds the picture's corners from 0 to 60 pt, overriding the Shape choice. |
ShadowimageShadow | number0–30 ptstep 1 | 0 | A soft shadow under the picture Blurs a dark shadow under the picture from 0 (none) to 30 pt, with room added around it so it is not cut off. |
FitaspectRatio | choiceone of 2 | — | Whether the picture fills the box or fits inside Scales the picture to sit fully inside its cell, or to cover the cell and crop the overflow.
|
BackgroundhideBackground | on / off | false (off) | Whether the card behind it is drawn Swaps in the SF Symbol listed for the incoming value, with "default" as the catch-all; it wins over the static symbol and url. |
valueMapvalueMap | object | — | Show different pictures for different values Loads the image at the web address listed for the incoming value; it wins over every other source. |
colorMapcolorMap | object | — | Show different colors for different values Tints the symbol with the hex color listed for the incoming value; photos are not tinted. |
What this control sends when you use it, and what it can show or follow when data arrives.
| Takes | From | Type | What it does |
|---|---|---|---|
valueshow | hub, mqtt, http, sensor, store, derive, default | string | a picture address, or a code (a number, state word or true/false) that the icon, picture and color maps turn into a symbol the picture changes to the one that matches; a code with no match uses the default entry, then the control's own symbol; a bare code is never read as an address Example: |
5 examples, each one a control you can paste into a layout.
A static symbol standing in for a feed.
{
"type": "image",
"id": "cam-front",
"position": [0, 0],
"span": [1, 2],
"systemName": "video.fill"
}
Shows the picture whose address arrives over a live feed.
{
"type": "image",
"id": "album-art",
"position": [0, 0],
"span": [3, 2],
"systemName": "music.note.list",
"style": "rounded",
"imageCornerRadius": 8,
"hideBackground": true,
"sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "player_state" }, "valuePath": "artwork_url" }]
}
Turns a weather code from a web request into a colored symbol.
{
"type": "image",
"id": "wx-icon",
"position": [0, 0],
"span": [2, 2],
"systemName": "cloud",
"hideBackground": true,
"iconMap": { "0": "sun.max.fill", "1": "sun.max.fill", "2": "cloud.sun.fill", "3": "cloud.fill", "45": "cloud.fog.fill", "51": "cloud.drizzle.fill", "61": "cloud.rain.fill", "71": "cloud.snow.fill", "80": "cloud.heavyrain.fill", "95": "cloud.bolt.rain.fill", "default": "questionmark.circle" },
"colorMap": { "0": "#FFD60A", "1": "#FFD60A", "2": "#FFD60A", "61": "#0A84FF", "80": "#0A84FF", "95": "#FF9F0A" },
"sync": [{ "method": "http", "url": "https://api.open-meteo.com/v1/forecast?latitude=42.36&longitude=-71.06¤t=weather_code", "interval": 900, "valuePath": "current.weather_code" }]
}
A big tinted symbol that fills its cell.
{
"type": "image",
"id": "wx-hero",
"position": [0, 0],
"span": [3, 2],
"systemName": "sun.max.fill",
"tint": "#FFD60A",
"hideBackground": true
}The symbol fills the cell, so the span alone controls how big it reads.

Changes symbol and color as a printer's state changes.
{
"type": "image",
"id": "printer-state",
"position": [0, 2],
"span": [2, 2],
"systemName": "printer",
"iconMap": { "idle": "printer", "printing": "printer.fill", "error": "exclamationmark.triangle.fill", "default": "questionmark.circle" },
"colorMap": { "printing": "#30D158", "error": "#FF453A" },
"sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "printer" }, "valuePath": "state" }]
}
carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.
Install the Python kit.
pip install carterkitShow “SF Symbol placeholder (e.g., for camera feed)” on your phone.
carterkit demo image --example 'SF Symbol placeholder (e.g., for camera feed)'Swap in any example name from this page, or leave --example off for the first one.
An image doesn't have to be fed a URL: point it at a code — a WMO weather code, a device state, an alarm level — and let the layout say what that code looks like.
"iconMap": { "0": "sun.max.fill", "3": "cloud.fill", "61": "cloud.rain.fill", "default": "questionmark.circle" },
"colorMap": { "0": "#FFD60A", "61": "#0A84FF" }
0, "0", true, and "rain" all work
from the same map. true/false also match yes/no/on/off/1/0, and a
number matches whether it arrives as 61 or 61.00. Key lookup falls back to a
case-insensitive match."default" is the catch-all for any value with no entry; with no "default"
either, the image falls back to its own systemName rather than rendering blank.valueMap URL wins, then an iconMap symbol, then the synced
value as a URL, then the static url, then systemName.colorMap tints the mapped symbol; a photo is unaffected.Border thickness takes the same three fields, where valueMap supplies display text.
systemName renders as SF Symbol when no URL is available[3, 2] span and it renders as a hero tile, not a small glyph in a large box. It
never shrinks below a legible ~28pt, which is also the size it settles at in a
flow grid (where the cell has no fixed height) — set controlHeight there to
make it larger. See Grid DimensionsiconMap/valueMap/colorMap turn a synced code into a symbol, an image URL,
and a tint — see Value mapsrowHeight: "auto" row an image never sets the row's height: it takes
the height its row's other content gives it, so a fallback symbol cannot balloon a
compact templated row.Generated from ControlDocs/image.md. Something unclear or missing? Tell me.