# Building Blocks: Values, Colors, Icons and Tap URLs | Aivi

> The objects every Aivi Live Activity and widget template shares: the Value object, colors, icons, formatters, the tap action URL, and where to find SF Symbols.

Source: https://docs.getaivi.app/building-blocks/

The [Live Activity templates](https://docs.getaivi.app/templates/) and the [widget templates](https://docs.getaivi.app/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

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` | [`Color`](#color)         | Text color for the value.                | No        |
| `formatter`  | [`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`      | *Image: red*    |
| `orange`   | *Image: orange* |
| `yellow`   | *Image: yellow* |
| `green`    | *Image: green*  |
| `mint`     | *Image: mint*   |
| `teal`     | *Image: teal*   |
| `cyan`     | *Image: cyan*   |
| `blue`     | *Image: blue*   |
| `indigo`   | *Image: indigo* |
| `purple`   | *Image: purple* |
| `pink`     | *Image: pink*   |
| `brown`    | *Image: brown*  |
| `gray`     | *Image: gray*   |
| `gray2`    | *Image: gray2*  |
| `gray3`    | *Image: gray3*  |
| `gray4`    | *Image: gray4*  |
| `gray5`    | *Image: gray5*  |
| `gray6`    | *Image: 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](#finding-sf-symbols) name.             | Yes       |
| `rendering_mode`  | `"monochrome" \| "hierarchical" \| "palette" \| "multicolor"` | How the symbol’s layers are colored.               | No        |
| `primary_color`   | [`Color`](#color)                                             | Primary layer color.                               | No        |
| `secondary_color` | [`Color`](#color)                                             | Secondary layer color (palette mode).              | No        |
| `tertiary_color`  | [`Color`](#color)                                             | Tertiary layer color (palette mode).               | No        |
| `color_rendering` | `"flat" \| "gradient"`                                        | Flat fill or vertical gradient. Default: `"flat"`. | No        |

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**

```json
{
  "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. |

## 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](https://docs.getaivi.app/concepts/how-it-works/#sharing) 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](https://companion.home-assistant.io/docs/integrations/url-handler) for the full list.

## Finding SF Symbols

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

- **[SF Symbols](https://developer.apple.com/sf-symbols/)**: Apple’s official app for macOS.
- **[Interactful](https://apps.apple.com/app/interactful/id1528095640)**: a free third-party SF Symbols browser for iPhone and iPad. Look under Foundations → Iconography.
