Skip to content
Get the appGet app

Building Blocks

The Live Activity templates and the widget templates share one vocabulary: a value with its color and formatter, an icon, and the URL a tap opens. Each template’s schema links here wherever a field takes one of these.

A Value is the text a template shows in one of its slots, such as a reading or a state line, with an optional color and formatter.

FieldTypeDescriptionRequired?
valuestringValue to display.Yes
text_colorColorText color for the value.No
formatterFormatterControls how the raw value is displayed.No

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

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

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.

FieldTypeDescriptionRequired?
namestringSF Symbol name.Yes
rendering_mode"monochrome" | "hierarchical" | "palette" | "multicolor"How the symbol’s layers are colored.No
primary_colorColorPrimary layer color.No
secondary_colorColorSecondary layer color (palette mode).No
tertiary_colorColorTertiary layer color (palette mode).No
color_rendering"flat" | "gradient"Flat fill or vertical gradient. Default: "flat".No

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.

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.

IdentifierDescription
time_sinceFormats an ISO8601 timestamp as an auto-updating elapsed timer.
time_untilFormats an ISO8601 timestamp as an auto-updating countdown timer.

Every Live Activity template and most widget templates take an optional tap_url field. When set, tapping the Live Activity on the Lock Screen or in the Dynamic Island, or tapping the widget, 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.

Use casetap_url value
Open a webpagehttps://example.com/status
Navigate in Home Assistanthomeassistant://navigate/lovelace/climate
Call a HA servicehomeassistant://call_service/switch.toggle?entity_id=switch.garage
Open another appmyapp://dashboard

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.

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.