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.
Value object
Section titled “Value object”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.
| Field | Type | Description | Required? |
|---|---|---|---|
value | string | Value to display. | Yes |
text_ | Color | Text color for the value. | No |
formatter | Formatter | Controls how the raw value is displayed. | No |
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
Section titled “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_ | "monochrome" | "hierarchical" | "palette" | "multicolor" | How the symbol’s layers are colored. | No |
primary_ | Color | Primary layer color. | No |
secondary_ | Color | Secondary layer color (palette mode). | No |
tertiary_ | Color | Tertiary layer color (palette mode). | No |
color_ | "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.
Formatter
Section titled “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_ | Formats an ISO8601 timestamp as an auto-updating elapsed timer. |
time_ | Formats an ISO8601 timestamp as an auto-updating countdown timer. |
Tap Action URL
Section titled “Tap Action URL”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.
Examples
Section titled “Examples”| Use case | tap_ value |
|---|---|
| Open a webpage | https:/ |
| Navigate in Home Assistant | homeassistant:/ |
| Call a HA service | homeassistant:/ |
| Open another app | myapp:/ |
Home Assistant deep links
Section titled “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.
Finding SF Symbols
Section titled “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.
Aivi: Live Activities and widgets over an API · Pricing · App Store