Standard Joomla XML field type - Tel

The tel field type is designed for entering phone numbers. When rendering a form, this field generates the standard HTML5 element <input type="tel" />. The main feature of this type is improved user experience on mobile devices: when the field is activated, the browser automatically displays a numeric keypad optimized for entering phone numbers. Additionally, the specific type allows browsers and password managers to correctly recognize the field for contact data autofill functionality.

Field Attributes

Below are the main attributes supported by the URL field type. Use them inside the <field> tag of your XML manifest.

Attribute	Type	Description
`name`	string	Required. Unique system identifier for the field. Used to retrieve the value in PHP ($input->get('name')).
`type`	string	Required. Must be set to "tel". Defines the field type and its behavior.
`label`	string	Field label visible to the user. Can be a language constant (e.g., COM_EXAMPLE_PHONE_LABEL).
`description`	string	Field description. In Joomla 3, it appears as a tooltip; in Joomla 4/5/6, it is displayed as text below the field.
`required`	boolean	Makes the field required. Accepts values true or false.
`pattern`	string	Regular expression for validating the phone number format. Critically important because there is no built-in validation. Example: [+]?[0-9s-()]+.
`hint`	string	Placeholder text inside the empty field. Disappears when input begins.
`default`	string	Default value displayed when creating a new record.
`autocomplete`	string	Controls autofill. Recommended value: "tel" to suggest numbers from the browser’s contacts.
`showon`	string	Conditional field display. The field is shown only if another field meets the specified condition. Example: showon="country:US".
`filter`	string	Server-side data filtering. For phone numbers, "cmd" (cleaning) or "string" (preserving format) is recommended.
`maxlength`	integer	Maximum number of characters that can be entered.
`size`	integer	Visible width of the field in characters. Does not affect the maximum input length.
`class`	string	Additional CSS classes for styling (e.g., Bootstrap classes).
`readonly`	boolean	The field is read-only. The value cannot be changed, but it is sent to the server.
`disabled`	boolean	The field is completely disabled. It does not accept focus and is not sent to the server.
`autofocus`	boolean	Automatically sets focus on the field after the page loads.
`spellcheck`	boolean	Enables/disables spell checking. For phone numbers, false is recommended.

Visual Examples

Below are screenshots showing how the field appears in different Joomla versions and admin panel themes.

Joomla 3 Isis

Classic field appearance in the Isis template.

Joomla 4 / 5 / 6 Cassiopeia (Light)

Visual Display of the Tel Field in Joomla 4/5/6 - Cassiopeia Admin Template (Light Theme)

Modern Cassiopeia design. Light theme.

Joomla 4 / 5 / 6 Cassiopeia (Dark)

Visual Display of the Tel Field in Joomla 4/5/6 - Cassiopeia Admin Template (Dark Theme)

Admin dark theme. High-contrast text and dark background.

XML Usage Example

Add this code inside the form tag in your XML file. The type="tel" attribute defines the field’s semantics as a phone number, allowing browsers to correctly handle input (including autofill and input interface adaptation).

<field
    name="phone"
    type="tel"
    label="Phone Number"
    description="Enter your phone number"/>

Retrieving Value in PHP

To retrieve the phone number value, use the application input object (Input). Since a phone number is a string, use the getString() method (to preserve original formatting) or getCmd() (to strip special characters). The example below demonstrates correct data retrieval, accounting for differences in Input object initialization between Joomla 3 and Joomla 4/5/6.

// --- OPTION FOR JOOMLA 4 / 5 / 6 (Modern) ---
use JoomlaCMSFactory;

// Get the input object via Factory (recommended MVC approach)
$input = Factory::getApplication()->input;

// getString() preserves spaces and parentheses (for display)
$phoneDisplay = $input->getString('phone_field', '');

// getCmd() removes extra characters, leaving only digits, +, -, . (for database)
$phoneClean = $input->getCmd('phone_field', '');


// --- OPTION FOR JOOMLA 3.x (Legacy) ---
// In J3, the JFactory class is used
$input = JFactory::getApplication()->input;

// Similar filtering logic
$phoneDisplay = $input->getString('phone_field', '');
$phoneClean = $input->getCmd('phone_field', '');

// OR the old way (not recommended):
// $phone = JRequest::getVar('phone_field', '', 'post', 'cmd');


// --- IMPORTANT FILTERING NOTE ---
// Do NOT use getInt() for phone numbers, as it will truncate the number 
// if it contains '+', '(', or spaces.
// Use getString() for display and getCmd() for saving/searching.

// Safe output to screen (XSS protection):
echo htmlspecialchars($phoneDisplay, ENT_QUOTES, 'UTF-8');

For phone numbers, it is critical not to use the getInt() method, as it will truncate data due to the presence of +, parentheses, or spaces. Instead, use getString() to preserve original formatting for display, or getCmd() to clean the number of extra characters before saving to the database. When displaying the value on a page, always use htmlspecialchars() to protect against XSS vulnerabilities.

Tip: To improve user experience on mobile devices, it is recommended to add the autocomplete="tel" attribute, which helps browsers automatically suggest saved phone numbers. If strict input format validation is required, use the pattern attribute with a regular expression, as the standard tel type does not perform automatic client-side data validation.

Common Pitfalls

Lack of automatic validation: Unlike the email or url fields, the tel type does not validate the format of entered data on the client side. Users can enter letters or arbitrary characters, and the form will still be considered valid. For strict validation, you must use the pattern attribute with a regular expression.
PHP Filtering Specifics: Never use the $input->getInt() method to retrieve phone numbers, as it will truncate the number at the first special character (e.g., + or space). Use getString() to preserve formatting, and getCmd() to clean the number before saving it to the database.
Differences in Mobile Keyboards: The behavior of the numeric keypad on iOS and Android may vary depending on the OS version and browser. The type="tel" attribute is only a recommendation for the browser and does not guarantee that an exclusively numeric input panel will appear in all possible scenarios.