# Phone Number Field

Overview

<figure><img src="/files/M3UFsBIXTwO59sxgdyws" alt=""><figcaption></figcaption></figure>

## Usage

### When to use this component?

Phone fields are used in forms and input scenarios where users need to enter their phone number. They help maintain a consistent format, making it easier to validate and utilize the phone number for communication purposes.

### How it works

A phone field component typically includes a label, a phone number-formatted input area, and optional elements like placeholder text and helper text to assist the user. It may also display different states, such as focused, filled, or error, to reflect its current status. The phone field ensures that the phone number is entered accurately and in the correct format.

### Code

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

```jsx
<dda-phonefield
    label="Phone Number"
    placeholder="00 000 0000"
    helper_text="Helper or footer text"
    error_message="This is an error message"
    max_length="10"
    validation_id=""
    validation_type="normal"
    disabled="false"
    custom_class=""
    component_mode=""
    input_id="input"
    button_id="button"
    aria_label="phone-field"
    button_aria_label="phone-button"
    onchange=""
    toggle_button_name="toggle-button"
    country_select_button_name="country-select-button"
    phone_input_name="phone-input"
></dda-phonefield>
```

{% endtab %}

{% tab title="React" %}

```jsx
<DdaPhonefield
    label="Phone Number"
    placeholder="00 000 0000"
    helper_text="Helper or footer text"
    error_message="This is an error message"
    max_length="10"
    validation_id=""
    validation_type="normal"
    disabled="false"
    custom_class=""
    component_mode=""
    input_id="input"
    button_id="button"
    aria_label="phone-field"
    button_aria_label="phone-button"
    onchange=""
    toggle_button_name="toggle-button"
    country_select_button_name="country-select-button"
    phone_input_name="phone-input"
></DdaPhonefield>
```

{% endtab %}

{% tab title="Vue" %}

```jsx
<DdaPhonefield
    label="Phone Number"
    placeholder="00 000 0000"
    helper_text="Helper or footer text"
    error_message="This is an error message"
    max_length="10"
    validation_id=""
    validation_type="normal"
    disabled="false"
    custom_class=""
    component_mode=""
    input_id="input"
    button_id="button"
    aria_label="phone-field"
    button_aria_label="phone-button"
    onchange=""
    toggle_button_name="toggle-button"
    country_select_button_name="country-select-button"
    phone_input_name="phone-input"
></DdaPhonefield>
```

{% endtab %}

{% tab title="Angular" %}

```jsx
<dda-phonefield
    label="Phone Number"
    placeholder="00 000 0000"
    helper_text="Helper or footer text"
    error_message="This is an error message"
    max_length="10"
    validation_id=""
    validation_type="normal"
    disabled="false"
    custom_class=""
    component_mode=""
    input_id="input"
    button_id="button"
    aria_label="phone-field"
    button_aria_label="phone-button"
    onchange=""
    toggle_button_name="toggle-button"
    country_select_button_name="country-select-button"
    phone_input_name="phone-input"
></dda-phonefield>
```

{% endtab %}
{% endtabs %}

### Properties

<table><thead><tr><th>Property</th><th>Description</th><th>Type</th></tr></thead><tbody><tr><td><code>aria_label</code></td><td>The aria-label for accessibility, describing the input field's function to screen readers.</td><td><code>string</code></td></tr><tr><td><code>button_aria_label</code></td><td>The aria-label for the dropdown button, providing context for screen readers.</td><td><code>string</code></td></tr><tr><td><code>button_id</code></td><td>The ID for the dropdown button, useful for styling or testing purposes.</td><td><code>string</code></td></tr><tr><td><code>component_mode</code></td><td>Defines the mode of the component, which can be used to customize its behavior or appearance </td><td><code>string</code></td></tr><tr><td><code>custom_class</code></td><td>A custom CSS class that can be added to the component’s root element for additional styling.</td><td><code>string</code></td></tr><tr><td><code>disabled</code></td><td>Determines if the input field is disabled or not. When <code>true</code>, the field is uneditable and grayed out.</td><td><code>boolean</code></td></tr><tr><td><code>error_message</code></td><td>An error message that is shown when the input is invalid or does not meet the validation criteria.</td><td><code>string</code></td></tr><tr><td><code>helper_text</code></td><td>Optional helper text displayed below the input field, providing extra information to the user about what should be entered.</td><td><code>string</code></td></tr><tr><td><code>input_id</code></td><td>The ID of the input field, useful for labeling and referencing the field in a form or when styling.</td><td><code>string</code></td></tr><tr><td><code>label</code></td><td>The label text that will be displayed next to the input field to describe the expected value (e.g., "Phone Number").</td><td><code>string</code></td></tr><tr><td><code>placeholder</code></td><td>A placeholder text that appears in the input field when it's empty, guiding the user on what to enter (e.g., "Enter phone number").</td><td><code>string</code></td></tr><tr><td><code>size</code></td><td>Specifies the size of the input field, e.g., "small", "medium", or "large". It adjusts the size of the input box accordingly.</td><td><code>string</code></td></tr><tr><td><code>validation_type</code></td><td>A type of validation to apply to the input field. This could trigger specific styling or validation behavior (e.g., "required", "email", etc.).</td><td><code>string</code></td></tr><tr><td><code>country_code</code></td><td>The default country code to be displayed in the input field, such as <code>+1</code> for the US or <code>+44</code> for the UK.</td><td><code>string</code></td></tr><tr><td><code>country_flag</code></td><td>The URL of the flag image associated with the default country. This is displayed alongside the country code.</td><td><code>string</code></td></tr><tr><td><code>phone_number</code></td><td>The value of the phone number entered by the user.</td><td><code>string</code></td></tr><tr><td><code>is_focused</code></td><td>A boolean that tracks whether the input field is currently focused by the user.</td><td><code>boolean</code></td></tr><tr><td><code>dropdown_open</code></td><td>A boolean indicating whether the country code dropdown is open or closed.</td><td><code>boolean</code></td></tr><tr><td><code>countries</code></td><td>A list of countries with their respective country codes and flag image URLs. This is used to populate the country selector dropdown.</td><td><p></p><pre class="language-typescriptreact"><code class="lang-typescriptreact">{ code: string; flag: string }[]
</code></pre></td></tr><tr><td><code>toggle_button_name</code></td><td>Name attribute for the country dropdown button</td><td><code>string</code></td></tr><tr><td><code>country_select_button_name</code></td><td>Name attribute for the country selection buttons in the dropdown</td><td><code>string</code></td></tr><tr><td><code>phone_input_name</code></td><td>Name attribute for the input field</td><td><code>string</code></td></tr><tr><td><code>max_length</code></td><td>Maximum number of digits allowed in the phone input.</td><td><code>string</code></td></tr><tr><td><code>validation_id</code></td><td>An optional identifier used for validation tracking.</td><td><code>string</code></td></tr><tr><td><code>onchange</code></td><td>Callback function triggered when the input value changes.</td><td><code>string</code></td></tr></tbody></table>

## Anatomy

<figure><img src="/files/oZqrbiUEy4bCl4ZLqoIp" alt=""><figcaption></figcaption></figure>

### Anatomy Options

**Label**: Describes the data to be entered, such as "Phone Number."

**Flag Icon**: Shows the flag of the selected country, identifying the country code.

**Lead-Icon**: Placed at the start of the input field to symbolize phone number entry.

**Country Dropdown**: Allows selection of the country code, displaying flags and codes for user convenience.

**Input Fields**: Segments where users type their phone number, structured by separators for clarity.

**Separator**: Divides segments of the phone number for organized input.

**Helper or Footer Text**: Provides extra guidance or requirements about the input format.

**Caption**: Offers additional details or instructions related to the input.

## Dos and Don'ts

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://designsystem.dubai.ae/components/phone-number-field.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.