Joomla XML Standard Field Type - Spacer

The Spacer field is a standard Joomla XML form field type designed exclusively for visually structuring administrative forms. It does not store data, is not included in form submissions, and is completely ignored by validation mechanisms. Depending on the configured attributes, the field can render as a section heading, a horizontal line (hr), or a custom HTML block. Below you will find usage examples, a complete attribute reference, and details on its behavior across Joomla 3, 4, 5, and 6.

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 within the fieldset. It is not saved to the database, but is required for the form parser to function correctly.
`type`	string	Required. Must be set to spacer. Defines the field type and its behavior as a visual divider.
`label`	string	Section heading visible to the user in the administration panel. Can be a language constant (e.g., COM_EXAMPLE_SECTION_TITLE) or contain HTML markup.
`description`	string	Help text. In Joomla 3, it appears as a tooltip when hovering over the label. In Joomla 4/5/6, it is rendered below the label or in a popup.
`hr`	boolean	Controls the display of a horizontal line below the heading. Possible values: true or false (default). Does not ignore the label; it renders the line after the heading text.
`class`	string	Additional CSS classes to customize the divider's appearance via the admin template's styles.
`showon`	string	Field visibility condition (Joomla 3+). Allows showing or hiding the divider based on the values of other fields (e.g., showon="enable_api:1").
`layout`	string	Path to an alternative layout file to override the divider's HTML output. Used for full rendering customization.

Visual Examples

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

Joomla 3 Isis

Spacer Field Type with Different Variations in Joomla 3.x Settings (Isis Admin Template)

Classic field appearance in the Isis template.

Joomla 4 / 5 / 6 Cassiopeia (Light)

Spacer Field Visual Display with Different Variations in Joomla 4/5/6 - Cassiopeia Admin Template (Light Theme)

Modern Cassiopeia design. Light theme.

Joomla 4 / 5 / 6 Cassiopeia (Dark)

Spacer Field Visual Display with Different Variations 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 fieldset tag of your form XML file. The type="spacer" attribute will automatically render a visual divider or section heading, without participating in data saving or validation.

<!-- 1. Minimal variant: text-only section divider -->
<field
	name="spacer_basic"
	type="spacer"
	label="Section Heading"/>

<!-- 2. With horizontal line (standard block grouping pattern) -->
<field
	name="spacer_hr"
	type="spacer"
	label="Additional Settings"
	hr="true"/>

<!-- 3. With tooltip (description) -->
<field
	name="spacer_hint"
	type="spacer"
	label="Heading with Tooltip"
	description="This hint appears when hovering over it with the mouse cursor."/>

Retrieving Value in PHP

Since the type="spacer" field does not generate input elements and does not submit values upon form submission, there is no dedicated PHP logic for filtering, binding, or saving it. In extension code, it is handled exclusively at the level of declarative XML definition.

/**
 * Example of working with the type="spacer" field in PHP
 * ⚠️ Important: Spacer is strictly a visual element for backend forms.
 * It is NOT saved to the database, does NOT undergo validation,
 * and is NOT included in the $_POST array upon form submission.
 */

This means that at the controller, model, and table levels, you do not need to implement custom handlers, verify the field's presence in the data array, or apply JFilterInput. The standard JForm mechanism automatically ignores spacer fields during bind(), check(), and save() operations, and correctly renders the divider's HTML markup through $this->form->renderField().

Tip: Use the spacer field exclusively for visual grouping of form fields. If you need to display a warning, documentation link, parameter list, or status block, it is preferable to use type="note" — it is semantically more appropriate and better optimized for the renderers of modern Joomla 4-6 themes. Always assign a unique value to the name attribute for each spacer, even though its data is not saved: this prevents conflicts in the JavaScript renderer of dynamic forms and within nested repeatable structures.

Common Pitfalls

Rendering changes for description and hr in Joomla 4-6: In Joomla 3, the description attribute rendered as a hover tooltip, and hr="true" consistently displayed a horizontal line. In Joomla 4, 5, and 6 (Atum template), descriptions appear as static text below the label, while the divider is often hidden or restyled via theme CSS variables. After migration, form sections may appear visually merged, and descriptions will occupy additional vertical space. A mandatory layout review in the new administration panel is required.