Live Activity Templates

A template decides what a Live Activity looks like on the device. To see these templates in real scenarios, with full payloads, browse the use cases.

Updates animate in place, and values with a time_since or time_until formatter keep ticking on the device between updates; everything else, including a progress bar, holds until the next update.

Note

These templates drive Live Activities: the ephemeral, real-time layer that starts, updates moment to moment, and ends. The persistent Home Screen and Lock Screen widgets use their own set of templates, documented on the Widget Templates page.

Choosing a template

Pick the template that matches the shape of your activity; each card jumps to the template’s schema and examples.

Progress A task with a clear finish: a dishwasher cycle, 3D print, or charging session. Monitor Live readings while something runs: temperatures, sensor values, machine states. Remote New Something you control while it runs: a vacuum, the garage door, a car charging. Generic Legacy A simple progress bar with a state line. Kept for older setups; prefer Progress.

Progress Template

ID: progress

The progress template is a flexible way to visualize any progress-based activity. It supports simple single-color bars, multi-segment bars with individual colors, and two display modes for segmented bars.

Home Assistant

The Aivi integration sets up a Progress Live Activity from a form in Home Assistant, with a live preview. To use a plain automation instead, import the blueprint:

Two more blueprints are available for segmented bars and timer-driven progress. See the blueprints page for the full list.

API schema

Field	Type	Description	Required?
template	"progress"	Identifies this template.	Yes
progress	ProgressBar	Progress bar configuration.	Yes
icon	string | Icon	An SF Symbols icon name or an Icon with rendering options.	No
header_left	Value	Left header slot.	No
header_right	Value	Right header slot.	No
footer_left	Value	Left footer slot.	No
footer_right	Value	Right footer slot.	No
compact_value	Value	Value shown in Dynamic Island compact trailing.	No
tap_url	string	Tap action URL to open when tapped.	No

To get a better understanding of how this schema correlates to a displayed live activity, see the picture below:

Progress bar

The progress field accepts two styles, distinguished by the style key.

Simple

A single-color bar.

Field	Type	Description	Required?
style	"simple"	Identifies this style.	Yes
value	float	Progress in range [0.0–1.0].	Yes
color	Color	Bar fill color.	No

Segmented

A bar split into labeled sections with individual colors.

Field	Type	Description	Required?
style	"segmented"	Identifies this style.	Yes
value	float	Overall progress in range [0.0–1.0].	Yes
segments	Segment[]	1–4 segments. Values must sum to 1.0.	Yes
display	"split" | "layered"	How segments are rendered. Default: "split".	No

Note

split renders segments side by side with gaps. layered overlaps them so each segment emerges from under the previous one with a gradient transition. The overall value sets how much of the whole bar is filled; the per-segment value weights only divide the bar into labeled sections.

Segment object

Field	Type	Description	Required?
value	float	Fraction of the bar this segment occupies.	Yes
fill_color	Color	Color when filled.	Yes
track_color	Color	Unfilled track color.	No
track_fill	"solid" | "hatched"	Track pattern. Default: "solid".	No
label	string	Label shown below the segment.	No

Example payloads

Simple bar:

{
  "template": "progress",
  "icon": "washer",
  "header_left": { "value": "In progress", "text_color": "green" },
  "header_right": { "value": "1h 32m" },
  "progress": {
    "style": "simple",
    "value": 0.65,
    "color": "blue"
  },
  "footer_left": { "value": "Progress" },
  "footer_right": { "value": "65%" }
}

Segmented bar (layered, with hatched overflow zone):

{
  "template": "progress",
  "icon": "bolt.car",
  "header_left": { "value": "90%", "text_color": "green" },
  "header_right": { "value": "3 min left" },
  "progress": {
    "style": "segmented",
    "value": 0.90,
    "display": "layered",
    "segments": [
      {
        "value": 0.8,
        "fill_color": "green",
        "track_color": "gray",
        "label": "Standard"
      },
      {
        "value": 0.2,
        "fill_color": "green",
        "track_color": "gray",
        "track_fill": "hatched",
        "label": "Extended"
      }
    ]
  },
  "footer_left": { "value": "Supercharger", "text_color": "gray" },
  "footer_right": { "value": "Est. $4.85" },
  "compact_value": { "value": "90%" }
}

Monitor Template

ID: monitor

The monitor template is designed for tracking a live status with one or two columns of labeled values.

Home Assistant

The Aivi integration sets up a Monitor Live Activity from a form in Home Assistant, with a live preview. To use a plain automation instead, import the blueprint:

API schema

Field	Type	Description	Required?
template	"monitor"	Identifies this template.	Yes
icon	string | Icon	An SF Symbols icon name or an Icon with rendering options.	No
left_column	Column	Left column payload.	No
right_column	Column	Right column payload.	No
primary_column	"left" | "right"	Column emphasized in compact layouts.	No
tap_url	string	Tap action URL to open when tapped.	No

Note

• At least one of left_column or right_column must be provided.
• primary_column decides which column value appears on the Dynamic Island, watchOS, and CarPlay.

To get a better understanding of how this schema correlates to a displayed live activity, see the picture below:

Column object

Field	Type	Description	Required?
header	string	Short label above the value.	No
value	Value	Value payload.	Yes
footer	string	Optional label below the value.	No

Value object

Field	Type	Description	Required?
value	string	Value to display.	Yes
text_color	Color	Text color for the value.	No
formatter	Formatter	Controls how the raw value is displayed.	No

Color

Color identifiers map to SwiftUI system colors. Swatches below show approximate previews.

Identifier	Preview
red
orange
yellow
green
mint
teal
cyan
blue
indigo
purple
pink
brown
gray
gray2
gray3
gray4
gray5
gray6

Icon object

When you need more than just a symbol name, pass an object to customize how the icon is rendered. All fields except name are optional. Omit them to keep the default appearance.

Field	Type	Description	Required?
name	string	SF Symbol name.	Yes
rendering_mode	"monochrome" | "hierarchical" | "palette" | "multicolor"	How the symbol’s layers are colored.	No
primary_color	Color	Primary layer color.	No
secondary_color	Color	Secondary layer color (palette mode).	No
tertiary_color	Color	Tertiary layer color (palette mode).	No
color_rendering	"flat" | "gradient"	Flat fill or vertical gradient. Default: "flat".	No

Note

Not every SF Symbol supports every rendering mode. If a symbol doesn’t support the requested mode, it falls back to monochrome automatically.

Example: palette icon with gradient

{
  "icon": {
    "name": "thermometer.sun",
    "rendering_mode": "palette",
    "primary_color": "red",
    "secondary_color": "orange",
    "color_rendering": "gradient"
  }
}

Passing a plain string ("icon": "thermometer.sun") continues to work and renders the symbol in monochrome with the default color.

Formatter

A formatter decides how to display the raw value field. If formatter is omitted or provided with null, it will display the value as-is without any transformation.

Identifier	Description
time_since	Formats an ISO8601 timestamp as an auto-updating elapsed timer.
time_until	Formats an ISO8601 timestamp as an auto-updating countdown timer.

Example payload

{
  "template": "monitor",
  "icon": "robotic.vacuum.and.ellipsis",
  "left_column": {
    "value": {
      "value": "Mopping",
      "text_color": "indigo"
    },
    "footer": "In living room"
  },
  "right_column": {
    "value": {
      "value": "20.1 m²"
    },
    "footer": "Battery: 87%"
  }
}

Preview

Left: Expanded dynamic island. Right: Lock screen.

Remote Template

ID: remote

A device you can control while it runs: its picture or icon, a state, one reading, and up to three buttons and toggles on the Lock Screen and in the expanded Dynamic Island. A press reaches your system; see Buttons and Toggles for how presses work and how you confirm them.

Needs Aivi 2.4 or later on every phone that shows it.

API schema

Field	Type	Description	Required?
template	"remote"	Identifies this template.	Yes
value	Value	The reading, at most 64 characters. A time_until or time_since formatter makes it a ticking timer.	Yes
actions	Action[]	1–3 buttons, toggles and links, in the order you send them. Every id must be unique.	Yes
unit	string	Drawn right after the value, for example "min". At most 8 characters.	No
value_label	string	A word under the value, for example "left". At most 24 characters.	No
state	{ value, text_color }	The state word under the name, for example "Cleaning", at most 24 characters, with an optional color.	No
progress	Simple progress bar	A bar under the reading. Only the simple style.	No
stats	Stat[]	Up to 2 extra readings, on the Lock Screen only, and only without progress. A stat’s max is ignored.	No
compact_value	Value	A shorter reading for the compact Dynamic Island, for example "64%", at most 64 characters. Default: value and unit.	No
image	{ url, alt }	A picture of the device, shown in place of the icon. An https:// URL of at most 512 characters; see Pictures.	No
icon	string | Icon	An SF Symbols icon name or an Icon. Shown in place of the picture until the phone has it.	No
accent	Action color	The color of the icon tile, and of buttons that set none. Default: the state’s color.	No
tap_url	string	Tap action URL to open when the card is tapped outside a button.	No

Any other field is rejected.

Caution

content.state is the state word on the card. The request’s own state (ONGOING or IDLE) is separate: buttons work only while it is ONGOING. See Live Activities.

Remote action object

The widget action object with only the parts a Live Activity draws: id, label, icon, color, kind, and active for a button or on for a toggle, or url for a link. subtitle, gradient, image and state_text are rejected. With one or two actions each button shows its label; with three, only the symbol.

Where it shows

• Lock Screen: the picture, the name and state, the reading, the bar or the stats, and the buttons.
• Expanded Dynamic Island: the same, without stats.
• Compact Dynamic Island: the icon or picture and compact_value.
• Apple Watch: the name, state, reading and bar, without buttons.

Example payload

A robot vacuum with a pause toggle and two buttons. Send it as content, with "state": "ONGOING":

{
  "template": "remote",
  "icon": "fan.fill",
  "accent": "green",
  "state": { "value": "Cleaning · Kitchen", "text_color": "green" },
  "value": { "value": "12" },
  "unit": "min",
  "value_label": "left",
  "progress": { "style": "simple", "value": 0.64, "color": "green" },
  "compact_value": { "value": "64%" },
  "actions": [
    { "id": "pause", "kind": "toggle", "label": "Pause", "icon": "pause.fill", "color": "orange", "on": false },
    { "id": "dock", "label": "Dock", "icon": "house.fill" },
    { "id": "stop", "label": "Stop", "icon": "stop.fill" }
  ]
}

Generic Template Legacy

ID: generic

Tip

The Progress template replaces Generic with a more flexible layout. Generic continues to work, but we recommend migrating to Progress for new activities.

The generic template works best for simple activities that map cleanly to a progress bar.

Home Assistant

Use the Home Assistant quick-start blueprint to post Live Activity updates using the Generic template.

API schema

Field	Type	Description	Required?
template	"generic"	Identifies this template.	Yes
progress	float	Progress of the activity in range [0.0-1.0].	Yes
state	string	Describes the state of the activity.	No
icon	string | Icon	An SF Symbols icon name or an Icon with rendering options.	No
remaining_time	int	Remaining time in seconds.	No
tap_url	string	Tap action URL to open when tapped.	No

Caution

In the Generic template, state and progress mean something different from elsewhere in the API. content.state here is free-form display text (for example "In progress"), not the lifecycle state (ONGOING / IDLE) on the request envelope. And progress here is a bare float, not the ProgressBar object the Progress template uses.

To get a better understanding of how this schema correlates to a displayed Live Activity, see the picture below:

Example payload

{
  "template": "generic",
  "progress": 0.35,
  "state": "In progress",
  "icon": "washer",
  "remaining_time": 2120
}

Preview

Left: Expanded dynamic island. Right: Lock screen.

Left: Compact dynamic island. Right: Apple Watch.

Live activity in the CarPlay dashboard.

Tap Action URL

All templates support an optional tap_url field. When set, tapping the Live Activity on the lock screen or Dynamic Island opens the specified URL instead of the Aivi app.

This works with any URL scheme the device can handle: regular web links, app deep links, or custom schemes. The URL is at most 256 characters. javascript, data, file, blob, about and aivi URLs are rejected.

On a widget or Live Activity shared with someone, Aivi asks them before it opens the URL, and they can choose to always allow that website or app. Your own taps open straight away.

Examples

Use case	tap_url value
Open a webpage	https://example.com/status
Navigate in Home Assistant	homeassistant://navigate/lovelace/climate
Call a HA service	homeassistant://call_service/switch.toggle?entity_id=switch.garage
Open another app	myapp://dashboard

Home Assistant deep links

Home Assistant’s Companion app supports a number of URL schemes for navigating to dashboards, calling services, and more. See the HA Companion docs on URL Handler for the full list.

Width-limited Dynamic Island

On iPhone 18 Pro, and in landscape on any iPhone with a Dynamic Island, the compact presentation has room for only a few characters on each side. Values are condensed to fit. Units are abbreviated, large numbers get a prefix and fractions are rounded, so 24.2 kWh becomes 24kWh and 1500 W becomes 1.5kW.

A value that cannot be condensed, like a word or a clock string, is left out and the icon stands alone. For times, send time_until or time_since values instead. They always fit.

Short units table

Category	Value unit	Short form
Time	min, minutes · h, hr, hours · s, sec, seconds · d, days	m · h · s · d
	w, weeks · mo, months · y, yr, years	w · mo · y
Ratio	%, percent, pct	%
Temperature	°C, °F, ℃, ℉, °, degrees, celsius, fahrenheit	°
Energy	wh, kwh, kilowatt-hours · kcal, kilocalories · cal	Wh, kWh · kcal · cal
Power	w, watts · kw, kilowatts · va · var	W · kW · VA · var
Electricity	v, volts · a, amps, amperes · hz, hertz	V · A · Hz
Length	millimeters · centimeters · meters · kilometers	mm · cm · m · km
	inches · feet · yards · miles	in · ft · yd · mi
Speed	mph · m/s · kn, knots · kph, kmh, km/h	mph · m/s · kn · km/h
Volume	l, liters, litres · ml · gal, gallons · m3, cbm	L · mL · gal · m³
Mass	g, grams · kg, kilos · lb, lbs, pounds · oz, ounces	g · kg · lb · oz
Pressure	pa · hpa · kpa · bar · psi · mbar, millibar · mmhg · inhg	Pa · hPa · kPa · bar · psi · mbar · mmHg · inHg
Data	b, bytes · kb · mb · gb · tb · kib, mib, gib	B · kB · MB · GB · TB · KiB, MiB, GiB
Area	m2, m² · ft2, sqft · ha, hectares · ac, acres	m² · ft² · ha · ac
Other	lux · db · dbm · ppm · bpm · rpm	lx · dB · dBm · ppm · bpm · rpm

Finding SF Symbols

To browse the full catalog of available symbols, you can use one of the following apps:

• SF Symbols: Apple’s official app for macOS.
• Interactful: a free third-party SF Symbols browser for iPhone and iPad. Look under Foundations → Iconography.