|
| 1 | +--- |
| 2 | +title: Add properties to basic cell values |
| 3 | +description: Add properties to basic cell values. |
| 4 | +ms.topic: how-to #Required; leave this attribute/value as-is |
| 5 | +ms.date: 05/12/2025 |
| 6 | +ms.localizationpriority: medium |
| 7 | +--- |
| 8 | + |
| 9 | +# Add properties to basic cell values |
| 10 | + |
| 11 | +Add properties to basic cell values in Excel to associate additional information with the values. Similar to [entity values](excel-data-types-linked-entity-cell-values.md), you can add properties to the **string**, **double**, and **Boolean** basic types. Each property is a key/value pair. The following example shows the number 14.67 (a double) that represents a bill with added fields named **Drinks**, **Food**, **Tax**, and **Tip**. |
| 12 | + |
| 13 | +:::image type="content" source="../images/data-type-basic-fields.png" alt-text="Screenshot of the drinks, food, tax, and tip fields shown for the selected cell value."::: |
| 14 | + |
| 15 | +If the user chooses to show the data type card, they'll see the values for the fields. |
| 16 | + |
| 17 | +:::image type="content" source="../images/data-type-basic-data-type-card.png" alt-text="Data type card showing values for drinks, food, tax, and tip properties."::: |
| 18 | + |
| 19 | +Cell value properties can also be used in formulas. |
| 20 | + |
| 21 | +:::image type="content" source="../images/data-type-basic-dot-syntax.png" alt-text="Show user typing 'a1.' and Excel showing a menu with drinks, food, tax, and tip options."::: |
| 22 | + |
| 23 | +## Create a cell value with properties |
| 24 | + |
| 25 | +To create a cell value and add properties to it, use `Range.valuesAsJson` to assign properties. The following code sample shows how to create a new number in cell **A1**. It adds the **Food**, **Drinks**, and additional properties describing a bill in a restaurant. It assigns a JSON description of the properties to `valuesAsJson`. |
| 26 | + |
| 27 | +```typescript |
| 28 | +async function createNumberProperties() { |
| 29 | + await Excel.run(async (context) => { |
| 30 | + const sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 31 | + const range = sheet.getRange("A1"); |
| 32 | + range.valuesAsJson = [ |
| 33 | + [ |
| 34 | + { |
| 35 | + type: Excel.CellValueType.double, |
| 36 | + basicType: Excel.RangeValueType.double, |
| 37 | + basicValue: 14.67, |
| 38 | + properties: { |
| 39 | + Food: { |
| 40 | + type: Excel.CellValueType.string, |
| 41 | + basicType: Excel.RangeValueType.string, |
| 42 | + basicValue: "Sandwich and fries" |
| 43 | + }, |
| 44 | + Drinks: { |
| 45 | + type: Excel.CellValueType.string, |
| 46 | + basicType: Excel.RangeValueType.string, |
| 47 | + basicValue: "Soda" |
| 48 | + }, |
| 49 | + Tax: { |
| 50 | + type: Excel.CellValueType.double, |
| 51 | + basicType: Excel.RangeValueType.double, |
| 52 | + basicValue: 5.5 |
| 53 | + }, |
| 54 | + Tip: { |
| 55 | + type: Excel.CellValueType.double, |
| 56 | + basicType: Excel.RangeValueType.double, |
| 57 | + basicValue: 21 |
| 58 | + } |
| 59 | + } |
| 60 | + } |
| 61 | + ] |
| 62 | + ]; |
| 63 | + await context.sync(); |
| 64 | + }); |
| 65 | +} |
| 66 | +``` |
| 67 | + |
| 68 | +> [!NOTE] |
| 69 | +> Some cell values change based on a user's locale. The `valuesAsJsonLocal` property offers localization support and is available on all the same objects as `valuesAsJson`. |
| 70 | +
|
| 71 | +## Add properties to an existing value |
| 72 | + |
| 73 | +To add properties to an existing value, first get the value from the cell using `valuesAsJson`, then add a properties JSON object to it. The following example shows how to get the number value from cell **A1** and assign a property named **Precision** to it. Note that you should check the type of the value to ensure it's a **string**, **double**, or **Boolean** basic type. |
| 74 | + |
| 75 | +```typescript |
| 76 | +async function addPropertyToNumber() { |
| 77 | + await Excel.run(async (context) => { |
| 78 | + let sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 79 | + let range = sheet.getRange("A1"); |
| 80 | + range.load("valuesAsJson"); |
| 81 | + await context.sync(); |
| 82 | + let cellValue = range.valuesAsJson[0][0] as any; |
| 83 | + |
| 84 | + // Only apply this property to a double. |
| 85 | + if (cellValue.basicType === "Double") { |
| 86 | + cellValue.properties = { |
| 87 | + Precision: { |
| 88 | + type: Excel.CellValueType.double, |
| 89 | + basicValue: 4 |
| 90 | + } |
| 91 | + }; |
| 92 | + range.valuesAsJson = [[cellValue]]; |
| 93 | + await context.sync(); |
| 94 | + } |
| 95 | + }); |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +## Differences from entity values |
| 100 | + |
| 101 | +Adding properties to **string**, **Boolean**, and **double** basic types is similar to adding properties to entity values. However there are differences. |
| 102 | + |
| 103 | +- Basic types have a non-error fallback so that calculations can operate on them. For example, consider the formula **=SUM(A1:A3)** where **A1** is **1**, **A2** is **2**, and **A3** is **3**. **A1** is a double with properties, while **A2** and **A3** don't have properties. The sum returns the correct result of **6**. The formula wouldn't work if **A1** was an entity value. |
| 104 | +- When the value of a basic type is used in a calculation, the properties are excluded in the result. In the previous example of **=SUM(A1:A3)** where A1 is a double with properties, the result of **6** does not have any properties. |
| 105 | +- If no icon is specified for a basic type, the cell doesn't show any icon. But if an entity value doesn't specify an icon, it shows a default icon in the cell value. |
| 106 | + |
| 107 | +## Formatted number values |
| 108 | + |
| 109 | +You can apply number formatting to values of type `CellValueType.double`. Use the `numberFormat` property in the JSON schema to specify a number format. The following code sample shows the complete schema of a number value formatted as currency. The formatted number value in the code sample displays as **$24.00** in the Excel UI. |
| 110 | + |
| 111 | +```typescript |
| 112 | +// This is an example of the complete JSON of a formatted number value with a property. |
| 113 | +// In this case, the number is formatted as currency. |
| 114 | +async function createCurrencyValue() { |
| 115 | + await Excel.run(async (context) => { |
| 116 | + const sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 117 | + const range = sheet.getRange("A1"); |
| 118 | + range.valuesAsJson = [ |
| 119 | + [ |
| 120 | + { |
| 121 | + type: Excel.CellValueType.double, |
| 122 | + basicType: Excel.RangeValueType.double, |
| 123 | + basicValue: 24, |
| 124 | + numberFormat: "$0.00", |
| 125 | + properties: { |
| 126 | + Name: { |
| 127 | + type: Excel.CellValueType.string, |
| 128 | + basicValue: "dollar" |
| 129 | + } |
| 130 | + } |
| 131 | + } |
| 132 | + ] |
| 133 | + ]; |
| 134 | + await context.sync(); |
| 135 | + }); |
| 136 | +} |
| 137 | +``` |
| 138 | + |
| 139 | +The number formatting is considered the default format. If the user, or other code, applies formatting to a cell containing a formatted number, the applied format overrides the number’s format. |
| 140 | + |
| 141 | +## Card layout |
| 142 | + |
| 143 | +Cell values with properties have a default data type card that the user can view. You can provide a custom card layout to use instead of the default card layout to improve the user experience when viewing properties. To do this, add the **layouts** property to the JSON description. |
| 144 | + |
| 145 | +For more information, see [Use cards with cell value data types](excel-data-types-entity-card.md). |
| 146 | + |
| 147 | +## Nested data types |
| 148 | + |
| 149 | +You can nest data types in a cell value, such as additional entity values, as well as **strings**, **doubles**, and **Booleans**. The following code sample shows how to create a cell value that represents the charge status on a computer battery. It contains a nested entity value that describes the computer properties for power consumption and charging status. The computer entity value also contains a nested string value that describes the computer’s power plan. |
| 150 | + |
| 151 | +```typescript |
| 152 | +async function createNumberWithNestedEntity() { |
| 153 | + await Excel.run(async (context) => { |
| 154 | + const sheet = context.workbook.worksheets.getActiveWorksheet(); |
| 155 | + const range = sheet.getRange("A1"); |
| 156 | + range.valuesAsJson = [ |
| 157 | + [ |
| 158 | + { |
| 159 | + type: Excel.CellValueType.double, |
| 160 | + basicType: Excel.RangeValueType.double, |
| 161 | + layouts: { |
| 162 | + compact: { |
| 163 | + icon: "Battery10" |
| 164 | + } |
| 165 | + }, |
| 166 | + basicValue: 0.7, |
| 167 | + numberFormat: "00%", |
| 168 | + properties: { |
| 169 | + Computer: { |
| 170 | + type: Excel.CellValueType.entity, |
| 171 | + text: "Laptop", |
| 172 | + properties: { |
| 173 | + "Power Consumption": { |
| 174 | + type: Excel.CellValueType.double, |
| 175 | + basicType: Excel.RangeValueType.double, |
| 176 | + basicValue: 0.25, |
| 177 | + numberFormat: "00%", |
| 178 | + layouts: { |
| 179 | + compact: { |
| 180 | + icon: "Power" |
| 181 | + } |
| 182 | + }, |
| 183 | + properties: { |
| 184 | + plan: { |
| 185 | + type: Excel.CellValueType.string, |
| 186 | + basicType: Excel.RangeValueType.string, |
| 187 | + basicValue: "Balanced" |
| 188 | + } |
| 189 | + } |
| 190 | + }, |
| 191 | + Charging: { |
| 192 | + type: Excel.CellValueType.boolean, |
| 193 | + basicType: Excel.RangeValueType.boolean, |
| 194 | + basicValue: true |
| 195 | + } |
| 196 | + } |
| 197 | + } |
| 198 | + } |
| 199 | + } |
| 200 | + ] |
| 201 | + ]; |
| 202 | + await context.sync(); |
| 203 | + }); |
| 204 | +} |
| 205 | +``` |
| 206 | + |
| 207 | +The following image shows the number value and the data type card for the nested laptop entity. |
| 208 | + |
| 209 | +:::image type="content" source="../images/data-type-basic-nested-entities.png" alt-text="Cell value in Excel showing battery charge at 70%, and the data type card showing the nested laptop entity with charging and power consumption property values."::: |
| 210 | + |
| 211 | +## Compatibility |
| 212 | + |
| 213 | +On previous versions of Excel that don't support the data types feature, users see a warning of **Unavailable Data Type**. The value still displays in the cell and functions as expected with formulas and other Excel features. If the value is a formatted number, calculations use the `basicValue` in place of the formatted number. |
| 214 | + |
| 215 | +On Excel versions older than Office 2016, the value is shown in the cell with no error and is indistinguishable from a basic value. |
| 216 | + |
| 217 | +## See also |
| 218 | + |
| 219 | +- [Excel JavaScript API data types core concepts](excel-data-types-concepts.md) |
0 commit comments