Tag expressions
Use tag expressions to create unique and dynamic watch faces. Tag expressions are conditions that let you change the rotation, placement, and opacity of a component based on tag values that represent watch data, such as the 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 an 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.
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 dialog in Watch Face Studio, select Tags. In the scripting dialog, you can create longer tag expressions and search for the tags you want.
The available tags, their descriptions, and their value ranges are shown in the following tables.
Date and 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 with leading zero  00  59  03 
SEC_MSEC  Second in minute with 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 with leading zero  00  59  03 
MIN_SEC  Minute in hour with second  0.0  59.999  1.234 
HOUR_0_11  Hour in day (011)  0  11  3 
HOUR_0_11_Z  Hour in day (011) with leading zero  00  11  03 
HOUR_0_11_MIN  Hour in day (011) with minute  0.0  11.999  1.234 
HOUR_1_12  Hour in day (012)  1  12  3 
HOUR_1_12_Z  Hour in day (012) with leading zero  01  12  03 
HOUR_1_12_MIN  Hour in day (012) with minute  1.0  12.999  1.234 
HOUR_0_23  Hour in day (023)  0  23  3 
HOUR_0_23_Z  Hour in day (023) with leading zero  00  23  03 
HOUR_0_23_MIN  Hour in day (023) with minute  0.0  23.999  1.234 
HOUR_1_24  Hour in day (124)  1  24  3 
HOUR_1_24_Z  Hour in day (124) with leading zero  01  24  03 
HOUR_1_24_MIN  Hour in day (124) with minute  1.0  24.999  1.234 
DAY_1_31  Day in month (131)  1  31  3 
DAY_1_31_Z  Day in month (131) with leading zero  01  31  13 
DAY_1_31_HOUR  Day in month (131) 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 with 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  152  24 
WEEK_IN_MON  Week in month  15  2 
IS_24H  Whether the system uses 24hour format  0 (12hour), 1 (24hour)  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  Asia/Seoul  
IS_AFTNOON  Whether the hour is before or after noon  0 (AM), 1 (PM)  0 
AMPM_PO  Position of AM or 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. For example, 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  
UNREAD_NC  Count of unread notifications on the device  3 
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  Acceleration angle X + angle Y  180.0  180.0 
Health data
Tag  Definition  Range  Example 

HR  Heart rate  0   60 
HR_Z  Heart rate with leading zero  00 80 120 

SC  Step count  0   1000 
SC_GOAL  Step count goal  1  20000  20000 
SC_PER  Step count as percentage of step count goal  0  100 
Moon phase
Tag  Definition  Range  Example 

MOON_PO  Position of moon phase  0  28 (See below)  14.5 
MOON_TY  Type of moon phase  0  7 (See below)  2 
MOON_TY_NAME  Name of moon phase  (See below) 
The [MOON_PO] tag has the following range definitions:
 00.5: New moonon
 0.56.5: Evening crescentnt
 7: First quarterer
 7.513.5: Waxing gibbousus
 14: Full moonon
 14.520.5: Waning gibbousus
 21: Last quarterer
 21.527.5: Morning crescentnt
 27.528: New moon
The [MOON_TY] and [MOON_TY_NAME] tags have the following range definitions:
 0: New moon
 1: Evening crescent
 2: First quarter
 3: Waxing gibbous
 4: Full moon
 5: Waning gibbous
 6: Last quarter
 7: Morning crescent
Functions
Functions  Definition  Expression example  Output example 

round(num)  Returns the closest integer to num.  round(1.6)  2 
floor(num)  Returns the greatest integer less than or equal to num.  floor(1.6)  1 
ceil(num)  Returns the smallest integer that is greater than or equal to num.  ceil(1.2)  2 
sin(num)  Returns the sine of num.  sin(1)  0.84147096 
cos(num)  Returns the cosine of num.  cos(1)  0.5403023 
tan(num)  Returns the tangent of num.  tan(1)  1.5574077 
abs(num)  Returns the distance from zero.  abs(10)  10 
clamp(num, min, max)  Returns the value of clamping num between max and min.  clamp([ACC_A_X], 30, 60)  30~60 
numberFormat(form, num)  Transforms num into the format of form. form is made up of the following values: 0: Fills empty spaces with zero. #: Does not display places with no values. .: Indicates the position of the decimal point. 
(numberFormat("#.#", [SEC_MSEC])) (numberFormat("#.###", ([SEC_MSEC]*10))) (numberFormat("000.000", ([SEC_MSEC]*10))) (numberFormat("0000.000", ([SEC_MSEC]*10))) 
32.4 324.37 324.370 0324.370 
asin(num)  Returns the arcsine function of num.  asin(0.841)  1 
acos(num)m  Returns the arccosine function of num.  acos(0.54)  1 
atan(num)  Returns the arctangent function of num.  atan(1.557)  1 
deg(num)  Converts num from radians to degrees.  deg(3.142)  180 
rad(num)  Converts num from degrees to radians.  rad(180)  3.141 
pow(base, exponent)  Returns the result of a base raised to an exponent.  pow(12, 2)  144 
Operators
Tag expressions support various operators that can modify the value of the tag expressions.
Arithmetic operators
Arithmetic operators are basic math functions. They perform a function between 2 values, which are also called 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 the 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 2 values to determine their relationship, such as whether one is greater than, less than, or equal to the other. A comparison that is true returns a value of 1. A comparison that is false returns a value of 0.
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 examples 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. Next, multiply 0 by 1,000 and then add 120. The final value returned is 120.
Logical operators
Logical operators combine the results of 2 or more relational operations and return a value of 1 (true) or 0 (false). Tag expressions support the logical operations AND and OR.

AND – represented by an asterisk (*)
Both relational operations must be true 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 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 logical operations:
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 operands—the values on either side of the operator—are relational operations. An arithmetic operator is applied if either of the 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 consists of 2 relational operations on either side of the operator (0<=1 and 1<2), so 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 consists of a relational operation (0<=1) and a number value (120), so 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 consists of 2 number values (1 and 120), so the arithmetic operator is applied. The result is 1 multiplied by 120, which returns a final result of 120. 
Ternary operators
Ternary operations have 3 operands: a conditional operation, then a result if the conditional operation is true, and then 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, it sets 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, it sets 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 2 ternary operations (a? b: c) and (x? y: z), you can create the following nested ternary operations:

conditional_operation? (a? b: c): result_if_false
If
conditional_operation
is true, then check conditional operation a.If a is true, the result is b. If a is false, the result is c.
If
conditional_operation
is false, the result isresult_if_false
. 
conditional_operation? result_if_true: (x? y: z)
If
conditional_operation
is true, the result isresult_if_true
.If
conditional_operation
is 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_operation
is true, then check conditional operation a.If a is true, the result is b. If a is false, the result is c.
If
conditional_operation
is false, then check conditional operation x.If x is true, the result is y. If x is false, the result is z.