Standard Joomla XML Field Type - URL

The URL field type in Joomla XML is designed for entering and validating web addresses. It renders a standard text input with browser-based link format validation. Supported in all current CMS versions (Joomla 3.x, 4.x, 5.x, 6.x).

A key feature is full support for Internationalized Domain Names (IDN), such as उदाहरण.परीक्षा or 例子.测试. Joomla automatically handles and saves Cyrillic and other national characters correctly, converting them to Punycode format for internal processing when necessary. This ensures data integrity regardless of encoding.

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. A unique system identifier for the field. Used to retrieve the value in PHP ($input->get('name')).
`type`	string	Required. Must be set to "url". Defines the field type and its behavior.
`label`	string	Field label visible to the user in the admin panel. Can be a language constant (e.g., COM_EXAMPLE_URL_LABEL).
`description`	string	Hint text. In Joomla 3, it appears as a tooltip on hover; in J4/5/6, it may be displayed below the field or in a popover.
`default`	string	Default value that appears in the field when the form is first opened (e.g., https://iws.by).
`required`	boolean	If true, the field becomes required. The form will not save without a filled value. The browser will display a warning.
`relative`	boolean	Important for URLs! If true, allows entering relative paths (without http://). Useful for internal Joomla links. Defaults to false (requires a full external URL).
`scheme`	string	Comma-separated list of allowed protocols (e.g., http,https,ftp). Restricts input to the specified schemes for security.
`filter`	string	Data filter applied on save. For URLs, it is recommended to leave it empty (the url filter is applied by default) or explicitly specify url.
`validate`	string	Joomla validation rule. You can specify url for additional strict server-side link format validation.
`maxlength`	integer	Maximum number of characters that can be entered in the field. Protects against database overflow.
`readonly`	boolean	If true, the field is read-only. The user can see the value but cannot change it. The value is saved.
`disabled`	disabled	If true, the field is completely disabled (grayed out). Its value is not sent or saved when the form is submitted.
`hint`	string	Placeholder text that appears in the empty field and disappears when typing begins.
`class`	string	Additional CSS classes for styling the element itself. For example, form-control or other classes.
`size`	integer	Visible field width in characters. Does not limit input length, only affects the visual size of the input area.
`showon`	string	Display condition. Allows showing the field only if another field has a specific value (e.g., showon="enable_url:1").
`autocomplete`	string	Controls browser autofill. Use off to disable (often for unique IDs) or on to enable.
`autofocus`	boolean	If true, the cursor automatically focuses on this field after the page loads. Convenient for the first fields in a form.
`spellcheck`	boolean	Enables (true) or disables (false) browser spell checking. For URLs, it is usually disabled (false).
`onchange`	string	JavaScript code that executes every time the field value changes.
`translate_default`	boolean	If true, Joomla will attempt to translate the default value. For static URLs, it is recommended to set this to false.
`label_class`	string	CSS classes applied to the tag of this field. Allows styling the label separately from the input field.
`layout`	string	Path to an alternative layout for rendering the field. Used in Joomla 4/5/6 for deep customization of the field's HTML template.

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 URL field in Joomla 4/5/6 – Cassiopeia admin light theme

Modern Cassiopeia design. Light theme.

Joomla 4 / 5 / 6 Cassiopeia (Dark)

Visual display of the URL field in Joomla 4/5/6 – Cassiopeia admin dark theme

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

XML Usage Example

Add this code inside your XML manifest tag. The type="url" attribute automatically enables browser-based link validation.

<field
	name="url"
	type="url"
	label="URL address"
	description="Enter the required URL address"/>

Retrieving Value in PHP

To retrieve data from form fields in Joomla, the JInput object is used. It ensures secure filtering of input data. Below are examples of retrieving a URL for modern versions (J4/J5/J6) and legacy versions (J3). Note the use of the getUrl() method, which automatically checks for the protocol and link validity. The important nuance of handling Cyrillic domains (IDN) is also covered.

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

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

// getUrl() strictly validates the protocol and link security
$myUrl = $input->getUrl('my_url_field', '');


// --- OPTION FOR JOOMLA 3.x (Legacy) ---
// In J3, JFactory or JRequest was used
$input = JFactory::getApplication()->input;
$myUrl = $input->get('my_url_field', '', 'url'); 
// OR the old way:
$myUrl = JRequest::getVar('my_url_field', '', 'get', 'url');


// --- IDN HANDLING ---
// If the URL contains an IDN (e.g., 例子.测试), it is stored as Punycode.
// To display it in a readable format (UTF-8), use conversion:

// For J4/J5/J6:
use JoomlaStringPunycode;
$displayUrl = Punycode::urlToUTF8($myUrl);

// For J3:
$displayUrl = JStringPunycode::urlToUTF8($myUrl);

// Displaying the link
echo '<a href="' . htmlspecialchars($myUrl) . '">' . htmlspecialchars($displayUrl) . '</a>';

In Joomla 4+, the JFactory class is replaced by JoomlaCMSFactory. The getUrl() method is the most reliable way to retrieve links, as it discards invalid data.

Important note on IDN: Joomla stores URLs in Punycode format (xn--...) in the database. Without conversion via Punycode::urlToUTF8(), users will see an unreadable string of characters instead of the clean website address. Always use htmlspecialchars() when outputting to HTML to protect against XSS.

Tip: Always use the getUrl() filter for URL fields. If you support Joomla 3, ensure you escape the output. For IDN domains, conversion to UTF-8 is critical for correct link display to the user.

Common Pitfalls

Protocol requirement: By default, the field uses the HTML5 . This means that both the browser and Joomla require a protocol (http:// or https://). Entering just example.com may trigger a browser validation error or save an incorrect link.
IDN domains: When entering Cyrillic domains (e.g., उदाहरण.परीक्षा or 例子.测试), ensure that your Joomla version handles encoding correctly. In some cases, conversion to Punycode (xn--d1acufc.xn--p1ai) may be required for proper functionality in the href attribute.
Length limit (255 characters): If the database column for this field is VARCHAR(255), long URLs with GET parameters may be truncated upon saving. For complex links, it is recommended to use TEXT or VARCHAR(500+).
PHP Filtering: When retrieving the value via $input->getUrl(), Joomla applies strict filtering. If the link is considered invalid (e.g., missing protocol), the method may return an empty value. For softer data retrieval, use $input->getString() and manually check for the protocol.