# Number Format

> :::info Note
To apply **Number Format** for your dimension/measure, ensure its `type` is `number`.
:::

:::info Note
To apply **Number Format** for your dimension/measure, ensure its `type` is `number`.
:::

## Overview of Number Format

To format your number fields, add a **format** property with a string pattern representing your chosen format.

```json
dimension formatted_price {
  label: "Formatted Price"
  type: "number"
  format: "#,###[$$]"
}
```

![Demostration for raw and formatted values](https://cdn.holistics.io/docs/aml-data-format/03.png)

## Shorthand Syntax vs. Full Syntax

Normally, you would use the shorthand version, which is represented as a string pattern under the `format` field. However, if you want **more control over your formats**, consider using the full syntax instead as it offers additional options to choose from.

<details>
  <summary>Shorthand format example</summary>
  
    ```json
    dimension price {
      label: "price"
      type: "number"
      description: "This dimension is using the shorthand format syntax"
      format: "[$$]#,###"
    }
    ```
  
</details>

<details>
  <summary> Full format example</summary>
  
    ```jsx
    dimension price {
      label: "price"
      type: "number"
      description: "This dimension is using the full number format syntax"
      format {
        pattern: '[$$]#,###0.00,,"\M"'
        // There are more options to choose from!
        groupSeparator: " "
        decimalSeparator: "."
      }
    }
    ```
  
</details>

## Order for Number Format

The number format follows the order below.

![Order for Number Format](https://cdn.holistics.io/docs/aml-data-format/order-of-data-format.png)

## Available Number Format options

### currency (optional)

:::info  Note
abbreviation/currency **cannot be used with** percentage.
:::

**Syntax:**
```json
 [$<currency code>]
```

**Description:**
- The currency notation must be wrapped in **$&lt;insert_your_currency_here&gt;.**
- The currency notation can only be placed in one of these places:
    - **At the beginning** of the string pattern.
    - **At the end** of the string pattern.
- Currently, we only support these currency types:

    ```tsx
    '$'   // US Dollar / MEX Peso
    '€'   // Euro
    '¥'   // Yen
    '£'   // Pound
    '元'  // Renminbi
    '₺'   // Lira
    '₩'   // Won
    '₽'   // RUS Ruble
    '₹'   // IND Rupee
    '₨'   // PAK Rupee
    '₱'   // PHL Peso
    'A$'  // AUS Dollar
    'C$'  // CAN Dollar
    'S$'  // SGP Dollar
    'NZ$' // NZ Dollar
    'HK$' // HK Dollar
    '₪'   // Shekel
    'R$'  // Real
    '฿'   // Thai Baht
    'R'   // South African Rand
    'Fr'  // Franc
    'kr'  // Krona / Krone
    'Ft'  // Forint
    'Rp'  // Rupiah
    'RM'  // Ringgit
    'VND' // VN Dong
    'Tk'  // BGD Taka
    ```

**Example:**

| Raw Value | Number Pattern | Displayed as |
| --- | --- | --- |
| 54 | [$$]#,### | $54 |
| 1236 | #,###[$€] | 1,236€ |

### group separator for integer values (optional)

:::info Note

**Holistics will automatically apply thousands separator for integers** whether you specify this option or not.
:::

**Syntax:**

```ruby
#,###
```

**Description:**
- Use this pattern to group your integer digits. Only **thousands grouping** is supported (a separator every three digits). There is no separate millions or billions grouping mode.
- In shorthand syntax the separator is **always a comma** (`,`). Writing the pattern with a different character (such as `#.###`) does not change the separator. To use a space or a dot, switch to the full syntax and set [`groupSeparator`](#groupseparator).

**Example:**

| Raw Value | Number Pattern | Displayed as |
| --- | --- | --- |
| 586347 | #,### | 586,347 |
| 1234 | #,### | 1,234 |
| 23431 | #,### | 23,431 |

### fraction (optional)

```json
0.0 (add more 0 if more decimal places are needed)
```

**Description:**
- Specify how many numbers should be included in the fraction format.
- The default separator is a dot(`.`). To specify another separator, refer to [Full Format: Custom Decimal Separator](#decimalseparator).

**Example:**

| Raw Value | Number Pattern | Displayed as |
| --- | --- | --- |
| 123456789.0123 | 0.00 | 123456789.01 |

### percentage (optional)

:::info Note
abbreviation/currency **cannot be used with** percentage.
:::

**Syntax:**

```json
% or \\%
```

**Description:**
  - `%` converts a number to percentage format **by multiplying the original value** by 100.
  - `\\%` converts a number to percentage format **without modifying the original value**.
**Example:**

| Raw Value | Number Pattern | Displayed as |
| --- | --- | --- |
| 12.3456 | `#,###0.0%` | 1,234.6% |
| 12.3456 | `#,###0.0\\%` | 12.3% |

### abbreviation (optional)

:::info  Note
abbreviation/currency **cannot be used with** percentage.
:::

**Syntax:**

Pick **one** of the following tokens to abbreviate long numeric values:

- `"A"`: auto-select (K, M, or B based on the value)
- `,"K"`: thousand
- `,,"M"`: million
- `,,,"B"`: billion

**Description:**
  - If your string pattern is wrapped in **single quotes (’ ‘)**, you **will not** need to wrap your abbreviation with **escape characters(`\ \`)**. For example, this is a valid pattern: `format: '<other_format_part>,"K"'`
  - If your string pattern is wrapped in **double quotes (” “)**, you **will** have to wrap your abbreviation with **escape characters(`\ \`)**. For example, this is a valid pattern: `format: "<other_format_part>,\"K\""`

**Example:**

| Raw Value | Number Pattern | Displayed as |
| --- | --- | --- |
| 124412.4 | '#,###0.000,"K"' | 124.412K |
| 157698 | '#,###0.000,,"M"' | 0.158M |

## Additional options for Full Syntax Number Format

To use these options, specify your Number Format in [Full Syntax form](#shorthand-syntax-vs-full-syntax).

### groupSeparator

This option allows you to select a **custom separator** **for your integer values**.

**Syntax:**

```json
format {
  pattern: "#,###"
  groupSeparator: ","
}
```

**Description:**
- By default, the group separator for integer values is a comma `,`. To opt for another separator, add this option in your **format** field.
- **Selectable separators** include:
  - `","`: comma separator (default)
  - `" "`: space separator
  - `"."`: dot separator
**Example:**

| Raw Value | Number Pattern | Displayed as |
| --- | --- | --- |
| 543213 | groupSeparator: " " | 543 213  |
| 12345.1 | groupSeparator: "," | 12,345.1 |

### decimalSeparator

This option allows you to select a **custom separator** **for your decimal values**.

**Syntax:**

```json
format {
  pattern: "0.00"
  decimalSeparator: "."
}
```

**Description:**
- By default, the group separator for decimal values is a dot `.`. To opt for another separator, add this option in your **format** field.
- **Selectable separators** include:
  - `"."`: dot separator (default)
  - `","`: comma separator

**Example:**

| Raw Value | Number Pattern | Displayed as |
| --- | --- | --- |
| 54.123 | decimalSeparator: "," | 54,123 |