Standard Joomla XML Field Type - Textarea

The standard Joomla XML form field type Textarea renders the native HTML <textarea> element for multi-line text input without a WYSIWYG editor. Designed for plain text entry, it fully supports data filtering (filter), validation (validate), and conditional display (showon).

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 "textarea". Defines the field type and its behavior (multi-line text field).
`label`	string	Field label displayed to the user in the administrator interface. Can be a language constant (e.g., COM_EXAMPLE_NOTES_LABEL).
`filter`	string	Data filtering method applied before saving. Critical for textarea: "string" (sanitization), "safehtml" (safe HTML), "raw" (no processing). Default depends on global configuration.
`description`	string	Tooltip text. In Joomla 3, it displays when hovering over the label (tooltip). In Joomla 4/5/6, it may render below the field or in a popup tooltip.
`rows`	integer	Number of visible rows in the textarea. If not specified, the browser uses its default value (typically 2-3 rows).
`cols`	integer	Visible width of the field in characters. If not specified, the browser automatically determines the width based on CSS or the parent container.
`hint`	string	Placeholder text displayed inside the field before data entry. In Joomla 4+, it replaces the legacy description attribute for input hints.
`default`	string	Default value when creating a new record. Can be a language constant or static text.
`class`	string	CSS classes for styling the textarea field itself. For example, class="form-control my-custom-class".
`required`	boolean	Makes the field required (true/false). Enables client-side (HTML5) and server-side validation.
`validate`	string	Data validation type: text, maxLength, customRule. Works in conjunction with filter for comprehensive validation.
`readonly`	boolean	Prevents editing of the field, but the value is still submitted to the server when the form is saved (true/false).
`disabled`	boolean	Completely disables the field: it cannot be edited and is not submitted to the server (true/false).
`maxlength`	integer	Maximum number of characters allowed for input (HTML5). It is recommended to duplicate this limit at the database level and use validate="maxLength".
`showon`	string	Conditional display of the field based on the values of other fields. For example, showon="show_notes:1" (show if the show_notes field equals 1).
`onchange`	string	JavaScript code executed when the field value changes. For example, onchange="myFunction(this.value)".
`wrap`	string	Line-wrapping behavior when submitting the form: soft (default, no newline characters are added), hard (inserts rn), off (wrapping disabled).
`labelClass`	string	CSS classes for the label wrapper. For example, labelClass="control-label".
`minlength`	integer	Minimum number of characters (HTML5). Works in conjunction with required for strict input validation.
`autocomplete`	string	Controls browser autocomplete: on, off, or specific tokens (username, email, etc.).
`spellcheck`	boolean	Controls browser spellcheck: true (enabled), false (disabled).
`onkeyup`	string	JavaScript code executed when a key is released in the field.
`onkeydown`	string	JavaScript code executed when a key is pressed in the field.

Visual Examples

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

Joomla 3 Isis

Textarea field in Joomla 3.x settings (Isis administrator template)

Classic field appearance in the Isis template.

Joomla 4 / 5 / 6 Cassiopeia (Light)

Visual appearance of the Textarea field in Joomla 4/5/6 - Cassiopeia administrator template (light theme)

Modern Cassiopeia design. Light theme.

Joomla 4 / 5 / 6 Cassiopeia (Dark)

Visual appearance of the Textarea field in Joomla 4/5/6 - Cassiopeia administrator template (dark theme)

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

XML Usage Example

Add this code inside the form tag of your XML manifest. The type="textarea" attribute creates a standard multi-line input field that preserves line breaks and supports data filtering via the filter parameter.

<field
    name="notes"
    type="textarea"
    label="Notes"
    description="Enter additional information on multiple lines." />

Retrieving Value in PHP

Example of retrieving and processing a textarea field value in your component's PHP code. Note: The getString() method automatically applies basic filtering, but for content containing markup, it is recommended to explicitly specify filter="safehtml" in the XML. When outputting the data, remember to handle line breaks using nl2br() or the CSS property white-space: pre-wrap.

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

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

// getString() automatically escapes dangerous characters and trims whitespace if needed
// The second parameter is the default value if the field is empty
$myText = $input->getString('notes', '');

// Alternative: if manual filter control is needed
// Available filters: 'raw' (no processing), 'string' (basic sanitization), 'safehtml' (safe HTML allowed)
$myText = $input->get('notes', '', 'safehtml');


// --- VARIANT FOR JOOMLA 3.x (Legacy) ---
// In J3, JFactory or JRequest was used
$input = JFactory::getApplication()->input;
$myText = $input->get('notes', '', 'string'); 

// OR using the old method (not recommended, but may appear in legacy code):
$myText = JRequest::getVar('notes', '', 'default', 'string');


// --- LINE BREAK HANDLING AND OUTPUT ---
// Text from textarea preserves line breaks (n).
// For correct HTML rendering, use nl2br() or the CSS white-space property.

// Option 1: Convert line breaks to <br> tags
echo nl2br(htmlspecialchars($myText, ENT_QUOTES, 'UTF-8'));

// Option 2: Use CSS (recommended for modern frontend)
echo '<div style="white-space: pre-wrap;">'.htmlspecialchars($myText, ENT_QUOTES, 'UTF-8').'</div>';

// Option 3: If safe HTML is allowed in the field (filter="safehtml")
// Use JoomlaFilterOutputFilter for additional protection
use JoomlaFilterOutputFilter;
echo OutputFilter::safeHtml($myText); // Только для J4+, в J3: JFilterOutput::safeHtml()


// --- IMPORTANT: FILTER SELECTION BY SCENARIO ---
/*
| Filter      | When to use                                  | Security                |
|-------------|----------------------------------------------|-------------------------|
| 'string'    | Plain text, comments, descriptions           | ✅ Automatic sanitization |
| 'safehtml'  | Text with allowed tags (<b>, <i>, <a>)       | ✅ Filters dangerous tags |
| 'raw'       | Only if you handle content processing yourself | ⚠️ Requires manual sanitization |
| 'html'      | Not recommended without custom validation    | ❌ May allow XSS          |
*/

// --- BONUS: Retrieving value from model/form (if working inside a component) ---
// In the modern approach (J4+), form data is often available via $this->getItem() or $form->getValue()
// Example in a model or view:
$myText = $this->item->notes ?? ''; 
// Or via the form:
$myText = $form->getValue('notes');

After retrieving the data, it is important to remember that the filter attribute in XML sanitizes input but does not replace output escaping — always wrap the result in htmlspecialchars() to protect against XSS. Since the field preserves newline characters, use nl2br() or the CSS property white-space: pre-wrap for correct HTML rendering. Filter selection depends on the scenario: string is optimal for plain text, safehtml allows safe markup, and raw should only be used for programmatic processing. The provided code uses the modern Joomla 4-6 namespace; for backward compatibility with Joomla 3.x, simply replace JoomlaCMSFactory with JFactory.

Tip: Always explicitly specify the filter attribute (string for plain text or safehtml for allowed markup) — without it, Joomla does not guarantee automatic XSS protection. When outputting data, always use htmlspecialchars() and handle line breaks via nl2br() or the CSS property white-space: pre-wrap. In Joomla 4+, use the hint attribute for placeholder text inside the field, as description now renders exclusively as a tooltip next to the field.

Common Pitfalls

No explicit filter specified: If the filter attribute is not explicitly specified, the system default filter is applied. Its behavior varies across Joomla versions (J3 is more permissive, while J4/J5/J6 are stricter). This may unexpectedly strip valid tags or leave an XSS vulnerability if the output is not escaped separately.
Ignoring line breaks in HTML: Newline characters (n) from the form are not automatically converted to
tags. Without processing via nl2br() or applying the CSS white-space: pre-wrap property, multi-line text will render as a single continuous line on the frontend.
Unsafe default value with line breaks: Inserting literal newline characters into the default attribute will break XML syntax. Use the entity instead, or set the default value programmatically via PHP or directly in the database.
Confusion between description and hint: In Joomla 3, the description attribute rendered as static text below the field. In Joomla 4+, it was moved to a tooltip. For placeholder text inside the field in modern versions, always use the hint attribute.
Client-side maxlength and database errors: The maxlength attribute restricts input only on the client side (HTML5). If the saved text exceeds the limit of a VARCHAR/TEXT column in the database, the query will fail with an SQL error. Always synchronize maxlength with the database schema.
Data loss in dynamic subforms: In subform or repeatable fields, textarea values may be reset when blocks are cloned programmatically due to JS rendering specifics in Joomla 4+. Always explicitly test this behavior in your target version and ensure the name attribute is correctly bound.
Conflict with WYSIWYG editor: The textarea field does not load a WYSIWYG editor. If user text formatting is expected, change the field type to editor or explicitly specify this in the technical requirements. Otherwise, the content will be saved as plain text.