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.
Figure 1. Tag scripting dialog
The available tags, their descriptions, and their value ranges are shown in the following tables.
Date and time
Tag
Definition
Type
Range
Example
UTC_TS
Timestamp as UTC milliseconds from the epoch
Number
1256953732
MSEC
Millisecond
Number
0 - 999
123
SEC
Second in minute
Number
0 - 59
12
SEC_Z
Second in minute with leading zero
String
00 - 59
03
SEC_MSEC
Second in minute with millisecond
Number
0.0 - 59.999
1.234
SEC_IN_DAY
Second in day
Number
0 - 86,400
12,345
MIN
Minute in hour
Number
0 - 59
3
MIN_Z
Minute in hour with leading zero
String
00 - 59
03
MIN_SEC
Minute in hour with second
Number
0.0 - 59.999
1.234
HOUR_0_11
Hour in day (0-11)
Number
0 - 11
3
HOUR_0_11_Z
Hour in day (0-11) with leading zero
String
00 - 11
03
HOUR_0_11_MIN
Hour in day (0-11) with minute
Number
0.0 - 11.999
1.234
HOUR_1_12
Hour in day (0-12)
Number
1 - 12
3
HOUR_1_12_Z
Hour in day (0-12) with leading zero
String
01 - 12
03
HOUR_1_12_MIN
Hour in day (0-12) with minute
Number
1.0 - 12.999
1.234
HOUR_0_23
Hour in day (0-23)
Number
0 - 23
3
HOUR_0_23_Z
Hour in day (0-23) with leading zero
String
00 - 23
03
HOUR_0_23_MIN
Hour in day (0-23) with minute
Number
0.0 - 23.999
1.234
HOUR_1_24
Hour in day (1-24)
Number
1 - 24
3
HOUR_1_24_Z
Hour in day (1-24) with leading zero
String
01 - 24
03
HOUR_1_24_MIN
Hour in day (1-24) with minute
Number
1.0 - 24.999
1.234
DAY_1_31
Day in month (1-31)
Number
1 - 31
3
DAY_1_31_Z
Day in month (1-31) with leading zero
String
01 - 31
13
DAY_1_31_HOUR
Day in month (1-31) with hour
Number
1.0 - 31.999
1.234
DAY_WEEK
Day of week
Number
1 (Sunday) - 7 (Saturday)
3
DAY_WEEK_F
Day of week, full text
String
Sunday - Saturday
Wednesday
DAY_WEEK_S
Day of week, abbreviated text
String
Sun - Sat
Wed
FIRST_DAY_WEEK
First day of week
Number
1 (Sunday) - 7 (Saturday)
1 in US, 2 in France
DAY_IN_YEAR
Day in year
Number
1 - 365
123
DAYS_IN_MON
Days in the current month
Number
28 - 31
31
MON
Month in year
Number
1 - 12
3
MON_Z
Month in year with leading zero
String
01 - 12
03
MON_F
Month in year, full text
String
January - December
November
MON_S
Month in year, abbreviated text
String
Jan - Dec
Nov
MON_DAY
Month with day
Number
1.0 - 12.999
11.111
YEAR
Year
Number
0000 - 9999
2021
YEAR_S
Abbreviated year, represented by last two digits
String
00 - 99
21
YEAR_MON
Year with month
Number
2021.307
WEEK_IN_YEAR
Week in year
Number
1-52
24
WEEK_IN_MON
Week in month
Number
1-5
2
IS_24H
Whether the system uses 24-hour format
Number
0 (12-hour), 1 (24-hour)
0
IS_DST
Whether the system uses Daylight Saving Time
Number
0 (No), 1 (Yes)
0
TMZN_ABB
Timezone abbreviation
String
PST
TMZN_OFS
Timezone offset
String
-12 - +14
+9
TMZN_OFS_WITH_DST
Timezone offset, modified for Daylight Saving Time
String
-12 - +14
-7
TMZN_ID
ID of timezone
String
Asia/Seoul
IS_AFTNOON
Whether the hour is before or after noon
Number
0 (AM), 1 (PM)
0
AMPM_PO
Position of AM or PM string
Number
-1 (Unknown), 0 (First), 1 (Last)
0
AMPM
AM/PM string formatted with system locale
String
AM/PM
AM
Table 1. Date and time tags
Setting information
Tag
Definition
Type
Range
Example
LANG_LOC
String representation of the system locale object, consisting of language, country, variant, script, and extensions. For example, en_US.
String
ko_KR
Table 2. Setting information tag
Device information
Tag
Definition
Type
Range
Example
BATT_PER
Current battery percentage
Number
0 - 100
70
BATT_IS_CHARGE
Whether the battery is charging
Number
0 (No), 1 (Yes)
1
BATT_IS_LOW
Whether the battery of the watch is low and not charging
Number
0 (No), 1 (Yes)
0
BATT_TEM_C
Current battery Temperature (°C)
Number
28.8
BATT_TEM_F
Current battery Temperature (°F)
Number
83.84
UNREAD_NC
Count of unread notifications on the device
Number
3
Table 3. Device information tags
Sensor data
Tag
Definition
Type
Range
Example
IS_ACC
Whether the device has an accelerometer sensor
Number
0 (No), 1 (Yes)
1
ACC_X
Acceleration on the X axis
Number
ACC_Y
Acceleration on the Y axis
Number
ACC_Z
Acceleration on the Z axis
Number
ACC_A_X
Acceleration angle on the X axis
Number
-90.0 - 90.0
ACC_A_Y
Acceleration angle on the Y axis
Number
-90.0 - 90.0
ACC_A_Z
Acceleration angle on the Z axis
Number
-90.0 - 90.0
ACC_A_XY
Acceleration angle X + angle Y
Number
-180.0 - 180.0
Table 4. Sensor data tags
Health data
Note:Health data is not shown when the device is locked.
Tag
Definition
Type
Range
Example
HR
Heart rate
Number
0 -
60
HR_Z
Heart rate with leading zero
String
00
80
120
SC
Step count
Number
0 -
1000
SC_GOAL
Step count goal
Number
1 - 20000
20000
SC_PER
Step count as percentage of step count goal
Number
0 - 100
Table 5. Health data tags
Moon phase
Tag
Definition
Type
Range
Example
MOON_PO
Position of moon phase
Number
0 - 28 (See below)
14.5
MOON_TY
Type of moon phase
Number
0 - 7 (See below)
2
MOON_TY_NAME
Name of moon phase
String
(See below)
New moon
Table 6. Moon phase tags
The [MOON_PO] tag has the following range definitions:
0-0.5: New moon
0.5-6.5: Evening crescentnt
7: First quarterer
7.5-13.5: Waxing gibbousus
14: Full moonon
14.5-20.5: Waning gibbousus
21: Last quarterer
21.5-27.5: Morning crescentnt
27.5-28: 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
Weather
Note:Watch faces should always check the [WTHR_IS_AVAIL] value before accessing other weather tags.
Tag
Definition
Type
Range
Example
WTHR_IS_AVAIL
Returns if there is any data that can be rendered.
Number
0 (No), 1 (Yes)
1
WTHR_COND
Weather Condition
Number
0 - 15 (See below)
8
WTHR_COND_NAME
Weather Condition Name
String
SUNNY
WTHR_IS_DAY
Returns if the current condition applies during daylight.
Number
0 (Night time), 1 (Day time)
0
WTHR_TEM
Current temperature
Number
25
WTHR_TEM_UNIT
Temperature unit
Number
1 / 2 (See below)
1
WTHR_DAY_TEM_LOW
Lowest temperature for the day
Number
18
WTHR_DAY_TEM_HIGH
Highest temperature for the day
Number
30
WTHR_CHANCE_PPTN
Current chance of precipitation
Number
0 - 100
0
WTHR_UV_INDEX
Current UV index
Number
3
WTHR_LAST_UPDATED
Last time the weather was updated from the provider
Number
Table 7. Weather tags
The [WTHR_COND] tag has the following range definitions:
0: UNKNOWN_VALUE
1: CLEAR
2: CLOUDY
3: FOG
4: HEAVY_RAIN
5: HEAVY_SNOW
6: RAIN
7: SNOW
8: SUNNY
9: THUNDERSTORM
10: SLEET
11: LIGHT_SNOW
12: LIGHT_RAIN
13: MIST
14: PARTLY_CLOUDY
15: WINDY
The [WTHR_TEM_UNIT] tag has the following range definitions:
1: CELSIUS
2: FAHRENHEIT
Weather forecast functions
Function
Definition
Return Type
Expression example
Example
forecastHour(index, String)
Forecast for the next few hours. Index starts from 1.
Number / String
forecastHour(1, "COND")
forecastHour(1, "COND_NAME")
Forecast conditions 1 hour from now.
8
SUNNY
forecastDay(index, String)
Forecast for the next few days. Index starts from 1.
Number / String
forecastDay(2, "COND_DAY")
forecastDay(2, "COND_DAY_NAME")
Forecast conditions 2 days from now.
8
SUNNY
Table 8. Weather forecast functions
Second parameter of forecastHour function has the following definitions:
IS_AVAIL
COND
COND_NAME
IS_DAY
TEM
Second parameter of forecastDay function has the following definitions:
IS_AVAIL
COND_DAY
COND_DAY_NAME
COND_NIGHT
COND_NIGHT_NAME
TEM_HIGH
TEM_LOW
CHANCE_PPTN
CHANCE_PPTN_NIGHT
Functions
Function
Definition
Return Type
Expression example
Output example
round(num)
Returns the closest integer to num.
Number
round(1.6)
2
floor(num)
Returns the greatest integer less than or equal to num.
Number
floor(1.6)
1
ceil(num)
Returns the smallest integer that is greater than or equal to num.
Number
ceil(1.2)
2
sin(num)
Returns the sine of num.
Number
sin(1)
0.84147096
cos(num)
Returns the cosine of num.
Number
cos(1)
0.5403023
tan(num)
Returns the tangent of num.
Number
tan(1)
1.5574077
abs(num)
Returns the distance from zero.
Number
abs(-10)
10
clamp(num, min, max)
Returns the value of clamping num between max and min.
Number
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.
Number
(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.
Number
asin(0.841)
1
acos(num)
Returns the arccosine function of num.
Number
acos(0.54)
1
atan(num)
Returns the arctangent function of num.
Number
atan(1.557)
1
deg(num)
Converts num from radians to degrees.
Number
deg(3.142)
180
rad(num)
Converts num from degrees to radians.
Number
rad(180)
3.141
pow(base, exponent)
Returns the result of a base raised to an exponent.
Number
pow(12, 2)
144
Table 9. Mathematical functions
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
Table 10. Arithmetic operators
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
Table 11. Relational operators
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).
Note:The asterisk represents both the multiplication arithmetic operator and the AND logical operator.
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).
Note:The plus sign represents both the addition arithmetic operator and the OR logical operator.
The following table describes the results of logical operations:
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.
Table 13. Examples of whether an operation is logical or arithmetic
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:
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 is result_if_false.
conditional_operation? result_if_true: (x? y: z)
If conditional_operation is true, the result is result_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.
Manage Your Cookies
We use cookies to improve your experience on our website and to show you relevant
advertising. Manage you settings for our cookies below.
Essential Cookies
These cookies are essential as they enable you to move around the website. This
category cannot be disabled.
Company
Domain
Samsung Electronics
.samsungdeveloperconference.com
Analytical/Performance Cookies
These cookies collect information about how you use our website. for example which
pages you visit most often. All information these cookies collect is used to improve
how the website works.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Functionality Cookies
These cookies allow our website to remember choices you make (such as your user name, language or the region your are in) and
tailor the website to provide enhanced features and content for you.
Company
Domain
LinkedIn
.ads.linkedin.com, .linkedin.com
Advertising Cookies
These cookies gather information about your browser habits. They remember that
you've visited our website and share this information with other organizations such
as advertisers.
Company
Domain
LinkedIn
.linkedin.com
Meta (formerly Facebook)
.samsungdeveloperconference.com
Google Inc.
.samsungdeveloperconference.com
Preferences Submitted
You have successfully updated your cookie preferences.