Guide / Controls / Media

Picture

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.

Type
image
Also titled
Image
Default size
2 rows × 2 columns
Symbol
photo
Docs
Docs complete
Search for it as
  • picture
  • photo
  • icon
  • logo
  • thumbnail
  • img
Picture: SF Symbol placeholder (e.g., for camera feed)
Rendered by the app

Fields

9 fields you can set on a image control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
SymbolsystemNametext—

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.

urlurltext—

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.

Shapestylechoiceone 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.

  • roundedsoftly rounded corners
  • circleclipped to a circle or pill
Image roundnessimageCornerRadiusnumber0–60step 1—

How round the picture corners are

Rounds the picture's corners from 0 to 60 pt, overriding the Shape choice.

ShadowimageShadownumber0–30 ptstep 10

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.

FitaspectRatiochoiceone 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.

  • fitthe whole picture shows, with empty space if the shapes differ
  • fillthe picture covers the whole cell and the edges are cropped
BackgroundhideBackgroundon / offfalse (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.

valueMapvalueMapobject—

Show different pictures for different values

Loads the image at the web address listed for the incoming value; it wins over every other source.

colorMapcolorMapobject—

Show different colors for different values

Tints the symbol with the hex color listed for the incoming value; photos are not tinted.

Emits and receives

What this control sends when you use it, and what it can show or follow when data arrives.

Receives

Receives
TakesFromTypeWhat it does
valueshowhub, mqtt, http, sensor, store, derive, defaultstring

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: 1

Examples

5 examples, each one a control you can paste into a layout.

Synced album artwork

Shows the picture whose address arrives over a live feed.

JSON 11 lines
{
  "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" }]
}

Open in CAR-TER

Picture: Synced album artwork
Rendered by the app

Live weather icon (WMO code → SF Symbol, no server)

Turns a weather code from a web request into a colored symbol.

JSON 11 lines
{
  "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&current=weather_code", "interval": 900, "valuePath": "current.weather_code" }]
}

Open in CAR-TER

Picture: Live weather icon (WMO code → SF Symbol, no server)
Rendered by the app

Hero symbol tile

A big tinted symbol that fills its cell.

JSON 9 lines
{
  "type": "image",
  "id": "wx-hero",
  "position": [0, 0],
  "span": [3, 2],
  "systemName": "sun.max.fill",
  "tint": "#FFD60A",
  "hideBackground": true
}

Open in CAR-TER

The symbol fills the cell, so the span alone controls how big it reads.

Picture: Hero symbol tile
Rendered by the app

Device state → symbol

Changes symbol and color as a printer's state changes.

JSON 10 lines
{
  "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" }]
}

Open in CAR-TER

Picture: Device state → symbol
Rendered by the app

Try it on your phone

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.

  1. Install the Python kit.

    pip install carterkit
  2. Show “SF Symbol placeholder (e.g., for camera feed)” on your phone.

    carterkit demo image --example 'SF Symbol placeholder (e.g., for camera feed)'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Value maps

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" }
  • Keys match the stringified value, so 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.
  • Precedence: a valueMap URL wins, then an iconMap symbol, then the synced value as a URL, then the static url, then systemName.
  • Only absolute URLs load (a synced bare code is never mistaken for an address).
  • colorMap tints the mapped symbol; a photo is unaffected.

Border thickness takes the same three fields, where valueMap supplies display text.

Behavior

  • When synced, receives a URL string and loads the image from that URL
  • systemName renders as SF Symbol when no URL is available
  • A symbol scales to its cell, exactly as a photo does: give the control a [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 Dimensions
  • iconMap/valueMap/colorMap turn a synced code into a symbol, an image URL, and a tint — see Value maps
  • In a rowHeight: "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.
  • Supports long-press groups for detail views

Generated from ControlDocs/image.md. Something unclear or missing? Tell me.