# Number Field

## Overview 

<figure><img src="https://881612694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEHbeJtpysoolkLI59NrC%2Fuploads%2F6MBQ3HS5yS9mateVLOTM%2FNumber%20Field%20-%20Overview.png?alt=media&#x26;token=8ad46133-660f-43c1-97f3-4de96f44516d" alt=""><figcaption></figcaption></figure>

## Usage

### When to use this component?

Number inputs are used in forms and other input scenarios where users need to enter numeric values, such as quantities, amounts, or measurements. They ensure consistent formatting, making it easier to validate and process the numeric data accurately.

### How it works

A number input component typically includes a label, a number-formatted input area, and optional elements like placeholder text, helper text, and a stepper for incrementing or decrementing the value. It may have different states to indicate its status, such as focused, filled, or error, ensuring that the numeric input is entered correctly and within the expected range.

### Code

{% tabs %}
{% tab title="Vanilla Js" %}

```jsx
<dda-number-field
    label="Amount"
    value=""
    placeholder="Enter amount"
    helper_text="Helper or footer text"
    error_message=""
    validation_type="normal"
    size="medium"
    input_status="normal"
    selected_currency="USD"
    custom_class=""
    component_mode=""
    input_id="input"
    aria_label="input"
    onchange=""
    input_name="input"
    toggle_button_name="toggle-button"
    currency_button_name="currency-button"
    currencies='["USD","EUR","GBP","AED","PKR"]'>
</dda-number-field>
```

{% endtab %}

{% tab title="React" %}

```jsx
<DdaNumberField
    label="Amount"
    value=""
    placeholder="Enter amount"
    helper_text="Helper or footer text"
    error_message=""
    validation_type="normal"
    size="medium"
    input_status="normal"
    selected_currency="USD"
    custom_class=""
    component_mode=""
    input_id="input"
    aria_label="input"
    onchange=""
    input_name="input"
    toggle_button_name="toggle-button"
    currency_button_name="currency-button"
    currencies='["USD","EUR","GBP","AED","PKR"]'>
</DdaNumberField>
```

{% endtab %}

{% tab title="Vue" %}

```jsx
<DdaNumberField
    label="Amount"
    value=""
    placeholder="Enter amount"
    helper_text="Helper or footer text"
    error_message=""
    validation_type="normal"
    size="medium"
    input_status="normal"
    selected_currency="USD"
    custom_class=""
    component_mode=""
    input_id="input"
    aria_label="input"
    onchange=""
    input_name="input"
    toggle_button_name="toggle-button"
    currency_button_name="currency-button"
    currencies='["USD","EUR","GBP","AED","PKR"]'>
</DdaNumberField>
```

{% endtab %}

{% tab title="Angular" %}

```jsx
<dda-number-field
    label="Amount"
    value=""
    placeholder="Enter amount"
    helper_text="Helper or footer text"
    error_message=""
    validation_type="normal"
    size="medium"
    input_status="normal"
    selected_currency="USD"
    custom_class=""
    component_mode=""
    input_id="input"
    aria_label="input"
    onchange=""
    input_name="input"
    toggle_button_name="toggle-button"
    currency_button_name="currency-button"
    currencies='["USD","EUR","GBP","AED","PKR"]'>
</dda-number-field>
```

{% endtab %}
{% endtabs %}

### Properties

For version 3.12.0+ you can use the new unified [input interactions](https://designsystem.dubai.ae/developers/input-interactions) to set/get data from the components.

| Property               | Description                                                                                                                                           | Type     |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `aria_label`           | An optional string for defining an accessible label for the input field, used by screen readers.                                                      | `string` |
| `component_mode`       | A string that can be used to define different modes of the component (e.g., `readonly`, `disabled`).                                                  | `string` |
| `currencies`           | A string containing a JSON array of currency options to display in the dropdown.                                                                      | `string` |
| `custom_class`         | An optional string for adding custom CSS classes to the component for styling purposes.                                                               | `string` |
| `error_message`        | A string that displays an error message below the input field if there's an issue with the entered data (e.g., validation failure).                   | `string` |
| `helper_text`          | A string that provides additional helper text below the input field, typically used to give guidance on acceptable input.                             | `string` |
| `input_id`             | A unique string identifier for the input element, used for labeling and accessibility.                                                                | `string` |
| `input_status`         | A string (in JSON format) that contains any status information related to the input (e.g., could be used for showing "loading" or "disabled" states). | `string` |
| `label`                | A string that provides the label text for the input field, typically displayed above the input box.                                                   | `string` |
| `placeholder`          | A string that defines the placeholder text shown inside the input field when it is empty.                                                             | `string` |
| `selected_currency`    | A string representing the currency currently selected from the dropdown. Default is 'USD'.                                                            | `string` |
| `size`                 | A string that controls the size of the input field (e.g., `small`, `medium`, `large`).                                                                | `string` |
| `validation_type`      | A string that represents the type of validation being applied to the input (e.g., `required`, `numeric`, etc.).                                       | `string` |
| `value`                | A string that holds the value of the input field.                                                                                                     | `string` |
| `input_name`           | Name attribute for the input field                                                                                                                    | `string` |
| `toggle_button_name`   | Name attribute for the currency dropdown                                                                                                              | `string` |
| `currency_button_name` | Name attribute for the currency switcher                                                                                                              | `string` |

## Anatomy

<figure><img src="https://881612694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEHbeJtpysoolkLI59NrC%2Fuploads%2FxIDeM2yoyXzrSKq36qwL%2FNumber%20Field%20-%20Anatomy.png?alt=media&#x26;token=7d708b32-c7f7-4d0a-9f82-bda67c2f5509" alt=""><figcaption></figcaption></figure>

### Anatomy Options

**Label**: Positioned above the input field, the label ("Amount") indicates the purpose of the field, guiding users to input a specific monetary value.

**Placeholder**: The placeholder text within the input field provides an example format or prompt.

**Currency Symbol**: Displayed before the placeholder text within the input field.

**Lead Icon**: Positioned to the left of the helper text, the lead icon provides a visual cue that can offer additional information or help related to the amount input.

**Caption**: Positioned below the input field, the caption provides additional instructions or context, such as "Helper or footer text," to assist users with the input.

**Stepper**: Positioned on the left within the input field, the stepper allows users to increase or decrease the amount by tapping up or down arrows, offering a quick way to adjust the input.

**Currency Dropdown**: Positioned to the right of the input field, the currency dropdown lets users select the desired currency, ensuring clarity in financial transactions.

## Dos and Don'ts

| Dos                                                                                            | Don'ts                                                                           |
| ---------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| Use number inputs to collect numeric values in a standardized format.                          | Don't use number inputs for non-numeric inputs.                                  |
| Label the number input clearly to indicate its purpose.                                        | Avoid using ambiguous or unclear labels for number inputs.                       |
| Include placeholder text to show the expected numeric format.                                  | Don't rely solely on placeholder text for essential instructions.                |
| Provide helper text to explain any specific formatting or range requirements.                  | Don't overload the number input with too much information.                       |
| Ensure the number input is large enough to be easily tappable or clickable.                    | Avoid making the number input too small to interact with comfortably.            |
| Use the stepper for inputs that require incremental adjustments.                               | Don't use steppers if precise values are required without increments.            |
| Validate input and provide clear error messages when the numeric format or range is incorrect. | Don't provide generic error messages that don't help users understand the issue. |
| Keep consistent styling and spacing across all number inputs in the application.               | Don't use inconsistent styles that may confuse users.                            |