Use tag expressions to create unique and dynamic watch faces. Tag expressions are conditions that allow you to change the rotation, placement, and opacity of a component based on tag values (watch data) such as date and time, battery status, or steps. Your watch face changes dynamically as the tag value changes.
For example, you can create a watch face where the object on the screen moves vertically with every passing second, or you can create a watch face with objects that appear or disappear at certain times.
Tag descriptions and value ranges are shown in the following tables.
Date & time
| Tag | Definition | Range | Example |
| UTC_TS | Timestamp as UTC milliseconds from the epoch | 1256953732 | |
| MSEC | Millisecond | 0 - 999 | 123 |
| SEC | Second in minute | 0 - 59 | 12 |
| SEC_Z | Second in minute (leading zero) | 00 - 59 | 03 |
| SEC_MSEC | Second in minute, including millisecond | 0.0 - 59.999 | 1.234 |
| SEC_IN_DAY | Second in day | 0 - 86,400 | 12,345 |
| MIN | Minute in hour | 0 - 59 | 3 |
| MIN_Z | Minute in hour (leading zero) | 00 - 59 | 03 |
| MIN_SEC | Minute in hour with second | 0.0 - 59.999 | 1.234 |
| HOUR_0_11 | Hour (0-11) in day | 0 - 11 | 3 |
| HOUR_0_11_Z | Hour (0-11) in day (leading zero) | 00 - 11 | 03 |
| HOUR_0_11_MIN | Hour (0-11) in day with minute | 0.0 - 11.999 | 1.234 |
| HOUR_1_12 | Hour (1-12) in day | 1 - 12 | 3 |
| HOUR_1_12_Z | Hour (1-12) in day (leading zero) | 01 - 12 | 03 |
| HOUR_1_12_MIN | Hour (1-12) in day with minute | 1.0 - 12.999 | 1.234 |
| HOUR_0_23 | Hour (0-23) in day | 0 - 23 | 3 |
| HOUR_0_23_Z | Hour (0-23) in day (leading zero) | 00 - 23 | 03 |
| HOUR_0_23_MIN | Hour (0-23) in day with minute | 0.0 - 23.999 | 1.234 |
| HOUR_1_24 | Hour (1-24) in day | 1 - 24 | 3 |
| HOUR_1_24_Z | Hour (1-24) in day (leading zero) | 01 - 24 | 03 |
| HOUR_1_24_MIN | Hour (1-24) in day with minute | 1.0 - 24.999 | 1.234 |
| DAY_1_31 | Day (1-31) in month | 1 - 31 | 3 |
| DAY_1_31_Z | Day (1-31) in month (leading zero) | 01 - 31 | 13 |
| DAY_1_31_HOUR | Day (1-31) in month with hour | 1.0 - 31.999 | 1.234 |
| DAY_WEEK | Day of week | 1(Sunday) - 7(Saturday) | 3 |
| DAY_WEEK_F | Day of week (full text) | Sunday - Saturday | Wednesday |
| DAY_WEEK_S | Day of week (abbreviated text) | Sun - Sat | Wed |
| DAY_IN_YEAR | Day in year | 1 - 365 | 123 |
| DAYS_IN_MON | Days in the current month | 28 - 31 | 31 |
| MON | Month in year | 1 - 12 | 3 |
| MON_Z | Month in year (leading zero) | 01 - 12 | 03 |
| MON_F | Month in year (full text) | January - December | November |
| MON_S | Month in year (abbreviated text) | Jan - Dec | Nov |
| MON_DAY | Month with day | 1.0 - 12.999 | 11.111 |
| YEAR | Year | 0000 - 9999 | 2021 |
| YEAR_S | Abbreviated year, represented by last two digits | 00 - 99 | 21 |
| YEAR_MON | Year with month | 2021.307 | |
| WEEK_IN_YEAR | Week in year | 1-52 | 24 |
| WEEK_IN_MON | Week in month | 1-5 | 2 |
| IS_24H | Whether the system uses 24-hour format | 0 (12-Hour), 1(24-Hour) | 0 |
| IS_DST | Whether the system uses Daylight Saving Time. | 0 (NO), 1(YES) | 0 |
| TMZN_ABB | Timezone abbreviation | PST | |
| TMZN_OFS | Timezone offset | -12 - +14 | +9 |
| TMZN_OFS_WITH_DST | Timezone offset, modified for daylight saving time | -12 - +14 | -7 |
| TMZN_ID | ID of timezone(ex. Asia/Seoul) | Asia/Seoul | |
| IS_AFTNOON | Whether the hour is before or after noon | 0(AM), 1(PM) | 0 |
| AMPM_PO | Position of AM/PM string | -1(Unknown), 0(First), 1(Last) | 0 |
| AMPM | AM/PM String formatted with system locale | AM / PM | AM |
Setting information
| Tag | Definition | Range | Example |
| LANG_LOC | String representation of the system locale object, consisting of language, country, variant, script, and extensions(ex. en_US) | ko_KR |
Device information
| Tag | Definition | Range | Example |
| BATT_PER | Current battery percentage | 0 - 100 | 70 |
| BATT_IS_CHARGE | Whether the battery is charging | 0 (NO), 1(YES) | 1 |
| BATT_IS_LOW | Whether the battery of the watch is low and not charging | 0 (NO), 1(YES) | 0 |
| BATT_TEM_C | Current battery Temperature (°C) | 28.8 | |
| BATT_TEM_F | Current battery Temperature (°F) | 83.84 |
Sensor data
| Tag | Definition | Range | Example |
| IS_ACC | Whether the device has an accelerometer sensor | 0 (NO), 1(YES) | 1 |
| ACC_X | Acceleration on the x-axis | ||
| ACC_Y | Acceleration on the y-axis | ||
| ACC_Z | Acceleration on the z-axis | ||
| ACC_A_X | Acceleration angle on the x-axis | -90.0 - 90.0 | |
| ACC_A_Y | Acceleration angle on the y-axis | -90.0 - 90.0 | |
| ACC_A_Z | Acceleration angle on the z-axis | -90.0 - 90.0 | |
| ACC_A_XY | Angle X + Angle Y | -180.0 - 180.0 |
Health data
| Tag | Definition | Range | Example |
| HR | Heart Rate | 0 - | 60 |
| HR_Z | Heart Rate (leading zero) | 00
80 120 |
|
| HR_LAST_MEASURED_TIME | Timestamp when the heart rate is measured | 1256953732 | |
| HR_MEASURE_RESULT | Whether heart rate measurement is successful or not | 0 (Fail), 1 (Success) | 0 |
| HR_IS_MEASURING | Whether heart rate is measuring or not | 0 (NO), 1(YES) | 0 |
| SC | Step Count | 0 - | 1000 |
| SC_GOAL | Set Goal of Step Count | 1 - 20000 | 20000 |
| SC_PER | Current percentage to Goal of Step count | 0 - 100 |
Moon phase
| Tag | Definition | Range | Example |
| MOON_PO | Position of moon phase | 0 - 28 | |
| MOON_TY | Type of moon phase | 0 - 7 | 2 |
| MOON_TY_NAME | Name of type |
Range definitions for MOON_PO tag
- 0-0.5: New moon
- 0.5-6.5 : Evening crescent
- 7 : First quarter
- 7.5-13.5 : Waxing gibbous
- 14 : Full moon
- 14.5-20.5 : Waning gibbous
- 21 : Last quarter
- 21.5-27.5 : Morning crescent
- 27.5-28 : New moon
Range definitions for MOON_TY tag
- 0 : New moon
- 1 : Evening crescent
- 2 : First quarter
- 3 : Waxing gibbous
- 4 : Full moon
- 5 : Waning gibbous
- 6 : Last quarter
- 7 : Morning crescent
Enter tag expressions directly into the rotate, placement, and opacity properties input fields of a component.
Tags must be enclosed in square brackets. To open the tag scripting popup, click the Tags button. In the scripting popup, you can enter lengthy tag expressions and can easily search for the data you want.
Operators
Tag expressions support various operators. These operators can modify the value of the tag expressions.
Arithmetic operators
Arithmetic operators are basic math functions. They perform a function between two values (operands).
| Operator | Definition |
| + | Addition |
| - | Subtraction |
| * | Multiplication |
| / | Quotient of division |
| % | Remainder of division |
Examples
The following examples show how to use tags and arithmetic operations in a tag expression:
5 * [BATT_PER] :
This returns the battery percentage multiplied by 5.
If the battery percentage is 7%, then the value returned is 35.
[SEC] / 3 :
This returns the quotient of seconds in a minute divided by 3.
If the number of seconds that have passed in the minute is 7, then the value returned is 2.33.
[SEC] % 3 :
This returns the remainder of seconds in a minute divided by 3.
If the number of seconds that have passed in the minute is 7, then the value returned is 1.
3 + 5 * [BATT_PER] :
The battery percentage is multiplied by 5, then 3 is added.
If the battery percentage is 7%, then the value returned is 38.
Multiplication is performed first (because it takes precedence over addition) and then 3 is added to that result: 3 + 5 * 7 → 3 + 35 → 38.
(3 + 5) * [BATT_PER] :
The addition operation in parentheses is performed first, then the result is multiplied by the battery percentage. If the battery percentage is 7%, then the value returned is 56.
Relational operators
Relational operators compare two values to determine which is greater than, less than, or equal to each other. A comparison that is true returns a value of one. A comparison that is false returns a value of zero.
| Operator | Definition |
| < | Less than |
| <= | Less than or equal to |
| > | Greater than |
| >= | Greater than or equal to |
| == | Equal to |
| != | Not equal to |
Examples
Relational operations are sometimes combined with arithmetic operations. The following are examples that use only relational operations, or relational operations and arithmetic operations.
[BATT_PER] <= 15 :
If the battery percentage is less than or equal to 15%, [BATT_PER] <= 15 is true and returns 1.
If the battery percentage is greater than 15%, [BATT_PER] <= 15 is false and returns 0.
1000 * ([HRATE] < 100) + 120
If the heart rate is less than 100 bpm, [HRATE] < 100 is true and returns the value of 1. Next, multiply 1 by 1,000 and then add 120. The final value returned is 1,120.
If the heart rate is greater than or equal to 100 bpm, [HRATE] < 100 is false and returns the value of 0 (zero).Next, multiply 0 by 1,000 and then add 120. The final value returned is 120.
Logical operators
Logical operators combine the results of two or more relational operations and return a value of 1 (true) or 0 (false). Tag expressions support two types of logical operations: AND and OR.
AND – Represented by an asterisk (*).
Both relational operations must be true in order for the AND logical operator to return a value of 1 (true). Otherwise, the return value is 0 (false).
OR – Represented by the plus sign (+).
One or more of the relational operations must be true in order for the OR logical operator to return a value of 1 (true). If both of the relational operations are false, then the return value is 0 (false).
The following table describes the results of a logical operation:
| Result of relational operation 1 | Result of relational operation 2 | Result of AND (*)
(relational operation 1) * (relational operation 2) |
Result of OR (+)
(relational operation 1) + (relational operation 2) |
| 0 (false) | 0 (false) | 0 * 0 = 0 | 0 + 0 = 0 |
| 0 (false) | 1 (true) | 0 * 1 = 0 | 0 + 1 = 1 |
| 1 (true) | 0 (false) | 1 * 0 = 0 | 1 + 0 = 1 |
| 1 (true) | 1 (true) | 1 * 1 = 1 | 1 + 1 = 1 |
A logical operator is applied only if both of the two operands (the values on either side of the operator) are relational operations. An arithmetic operator is applied if either of the two operands is a number value.
| Logical operation | Arithmetic operation | Arithmetic operation |
| Both operands are relational operations:
(0 <= 1) * (1 < 2) Result: 1 |
One operand is a relational operation and the other is a value:
(0 <= 1) *120 Result: 120 |
Both operands are values:
1*120 Result: 120 |
| This tag expression is made up of two relational operations on either side of the operator (0<=1 and 1<2). Because of this, the logical operator is applied. Because both of the relational operations are true, the final result of this tag expression is 1 (true). | This tag expression is made up of a relational operation (0<=1) and a number value (120). Because of this, the arithmetic operator is applied. The result of the relational operation is 1 (true) which is then multiplied by 120. The final result of this operation is 120. | This tag expression is made up of two number values (1 and 120). Because of this, the arithmetic operator is applied. The result is 1 multiplied by 120 which returns a final result of 120. |
Ternary operators
Ternary operations have three operands: a conditional operation, then a result if the conditional operation is true, and a result if the conditional operation is false. A conditional operation can be a relational or logical operation.
Ternary operations are presented in the following format:
conditional_operation? result_if_true: result_if_false
Examples
The following examples are used to set the opacity of an image on the watch face.
[BATT_PER] <= 20? 15: 100
This operation sets the opacity of an image on the watch face to 15, if battery percentage is less than or equal to 20%. Otherwise, set the opacity to 100.
([BATT_PER] >= 50) * ([BATT_PER] <= 75)? 100: 0
This example uses a logical operation for its conditional operation.
This sets the opacity of an image on the watch face to 100, if the battery percentage is greater than or equal to 50% and less than or equal to 75%. Otherwise, set the opacity to 0.
Nested ternary operations
Ternary operations can be nested within the result operand of another ternary operation.
For example, if you have two ternary operations (a? b: c) and (x? y: z), you could create the following nested ternary operations:
conditional_operation?(a? b: c):result_if_falseIf
conditional_operationis true, then check conditional operation a.If a is true, the result is b. If a is false, the result is c.
If
conditional_operationis false, the result isresult_if_false.conditional_operation?result_if_true:(x? y: z)If
conditional_operationis true, the result is result_if_true.If
conditional_operationis false, then check conditional operation x.If x is true, the result is y. If x is false, the result is z.
conditional_operation?(a? b: c):(x? y: z)If
conditional_operationis true, then check conditional operation a.If a is true, the result is b. If a is false, the result is c.
If
conditional_operationis false, then check conditional operation x.If x is true, the result is y. If x is false, the result is z.