---
title: "Phone Number Component"
slug: "phone-number-component"
tags: ["module-builder"]
updated: 2026-10-05T15:53:06Z
published: 2026-10-05T15:53:06Z
canonical: "docs.unqork.io/phone-number-component"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unqork.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Phone Number Component

The Phone Number component captures a domestic phone number with a configurable input mask. The default mask formats the entry as `(999) 999-9999`.

> [!NOTE]
> The Build Agent does not create new instances of this component.

> **How to read settings tables**
> 
> The tables below describe each configurable option as it displays in the UnqorkAI platform. Values are formatted as follows: `inline code` — a value to type exactly as shown | **Bold** — a value selected from a drop-down, radio button, tab, or choice chip | **ON**/**OFF** — toggle state | ✓ — checkbox checked | ☐ — checkbox unchecked

## General Settings

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Property ID | `key` | Text input | `phoneNumberField` | The unique identifier for this component instance. |

## Display Settings

### Field Text

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Label Text | `label` | Text input | — | Identifies the component on the canvas and informs end-users what information is requested. |
| Placeholder Text | `placeholder` | Text input | — | Hint text displayed inside the input field to guide end-users on what to enter. |
| Prefix | `prefix` | Text input | — | Text or symbol displayed before the input (for example, `$`, `@`). |
| Suffix | `suffix` | Text input | — | Text or symbol displayed after the input (for example, `.com`). |

### Contextual Help

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Tooltip | `description` | Text input | — | A brief description that displays when a cursor is positioned over the tooltip icon. |

### Default State Options

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Hide Field | `hidden` | Toggle | OFF | Hides the component from end-users but always displays in the Module Builder. |

### Formatting

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Autocomplete | `disableAutoComplete` | Toggle | ON | Lets the browser suggest and autofill previously entered phone numbers. |
| ↳ Autocomplete Value | `autocomplete` | Drop-down | — | Specifies the type of data the browser can autofill for this field. See [Autocomplete Values](/unqorkai/docs/autocomplete-values). Visible when **Autocomplete** is **ON**. |
| Mask | `inputMask` | Text input | `(999) 999-9999` | Enforces a specific phone number format. Numeric: `9`; alphabetical: `a`; alphanumeric: `*`. |
| Mask Error Message | `errors.mask` | Text input | `must be a valid mask` | Displays when the entered value does not match the required mask format. |

### Input Behavior

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Input Behavior | — | Drop-down | **Enable User Input** | Sets how end-users can interact with the field. |

> - **Enable User Input** (default): End-users can type directly into the phone number field.
> - **Display as Text** (`readOnlyView`): Displays the stored value as plain text without the input element. Shows `None` when empty.
> - **Read** (`htmlReadOnly`): Makes the field non-editable while still letting end-users view, select, and copy its content.
> - **Disable User Input** (`disabled`): Prevents end-users from editing the field. The field displays with an altered appearance to indicate it is not editable.

## Data Settings

### Data Storage

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Store Data in Database | `persistent` | Toggle | ON | When set to **ON**, this setting stores field values to the database when the module saves, end-users navigate between Panel components, or end-users navigate between workflow screens. Set to **OFF** to exclude this field from server-side submissions. |

> [!NOTE]
> Fields with **Store Data in Database** set to **OFF** are excluded from Plug-In component's API responses and Unqork's built-in tracker. When using a Plug-In component to remote-execute a module, any component whose value must be included in the API response requires **Store Data in Database** set to **ON**.

## Validation Settings

### User Input

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Required | `validate.required` | Toggle | OFF | Requires a value before the module can be submitted. |
| Required Error Message | `errors.required` | Text input | `is required` | Displays when the required field is left empty. |

## Advanced Settings

### Additional Validation Options

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Min Length | `validate.minLength` | Number input | — | Minimum number of characters required. |
| Min Length Error Message | `errors.minlength` | Text input | `Must be longer than` | Displays when the entered value is shorter than the minimum. |
| Max Length | `validate.maxLength` | Number input | — | Maximum number of characters allowed. |
| Max Length Error Message | `errors.maxlength` | Text input | `Must be shorter than` | Displays when the entered value exceeds the maximum. |
| Regular Expression Pattern (Regex) | `validate.pattern` | Text input | — | A regex pattern the entered value must match before the module can be submitted. See [Regular Expression Patterns](/unqorkai/docs/regular-expression-patterns) for common patterns and a syntax reference. |
| Pattern Error Message | `errors.pattern` | Text input | `Does not match pattern` | Displays when the value does not match the regex pattern. |

### Additional Styling

| Setting | Field | Type | Default | Description |
| --- | --- | --- | --- | --- |
| Custom CSS Class | `customClass` | Text input | — | A CSS class applied to the component for custom styling. |

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-10-02 | Added Build Agent notice — the Build Agent does not create new instances of this component (EN-8141). |
| — | Initial publication. |

An input mask is a string expression that constrains an end-user's input. For example, constraining a phone number input to 10 integers.

A Property ID is the unique field ID used by Unqork to track and link components in your module.

Label Text conveys what the input component is and what information it displays. Enter the purpose of the corresponding component or field.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

The VCS (version control system) Contributor role has permissions to edit modules in a branch. Set contributors during the VCS Create a Branch process.

APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.

Cascading Style Sheets (CSS) is a style sheet language used for presenting how a HTML or XML document looks to end-users.