Joomla Custom Fields — Adding and Managing Custom Content Fields

In this tutorial, you'll learn how to create and manage Joomla custom fields — adding extra data to articles, users, contacts, and categories using field types like text, editor, image, file, calendar, checkbox, and color, and displaying them in your template.

What You'll Learn

• What custom fields are and why they are useful
• Creating field groups to organize fields by purpose
• Using all field types: Text, Textarea, List, Checkbox, Radio, Media, URL, Editor, Calendar, Color, Image, User, Integer, Repeatable, SQL, Subform
• Configuring field settings per type
• Displaying custom fields in articles automatically
• Using custom fields on user profiles, contacts, and categories
• Rendering fields in template overrides with PHP

Why It Matters

Default Joomla articles have a fixed set of fields: title, alias, intro text, full text, category, and tags. But real-world content needs more. A recipe site needs "cooking time" and "servings." A real estate site needs "price" and "bedrooms." A team page needs "job title" and "phone number." Custom fields let you add these without modifying core code. They were introduced in Joomla 3.7 and have become one of the most powerful features for building custom content types.

Real-World Use

A job board built with Joomla needs each job listing to have: location (list), salary range (text), job type (radio: full-time, part-time, contract), application deadline (calendar), and company logo (image). Using custom fields, the site adds all of these to the standard article form. No extension needed. The fields appear in the article automatically. The template overrides apply custom styling. The job board launches with a professional listing format using only core Joomla features.

Learning Path

flowchart LR
  A["User Groups"] --> B["Custom Fields"]
  B --> C["Joomla API"]
  C --> D["Database Maintenance"]
  D --> E["Go-Live Checklist"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px
  class B current

What are Custom Fields?

Custom fields are extra data fields you can attach to Joomla content types. They were introduced in Joomla 3.7 and are supported in Joomla 4 and 5.

Supported content types:

When you add a custom field to articles, it appears in the article edit form. When the article is saved, the field value is stored and displayed in the article output.

Field Groups

Field groups help you organize related fields.

1. Go to Content > Fields (or Components > Fields for other contexts)
2. Click the Groups tab
3. Click New to create a group
4. Example groups:

Creating a Group

Title: Job Listing Fields
Type: com_content.article
Description: Extra fields for job listings
Published: Yes

After creating the group, you add fields to it.

Field Types

Joomla offers many field types. Each is designed for a specific kind of data.

Text

Simple single-line text input. Best for short values like "Price" or "Author."

<!-- Rendered output -->
<input type="text" name="custom_field_price" value="299" size="40" maxlength="255" />

Textarea

Multi-line text input. Best for longer values like "Description" or "Notes."

List

Dropdown selection. Best for choosing one option from a set.

Checkbox

Single checkbox for boolean values.

Multiple Checkbox

Multiple checkboxes for selecting several options.

Radio

Radio buttons for mutually exclusive options.

Media

File picker that opens the Media Manager.

URL

URL input with validation.

Editor

Full WYSIWYG editor (TinyMCE).

Calendar

Date/time picker.

Color

Color picker that returns hex values.

Image

Image with alt text.

User

User selection from a dropdown of registered users.

Integer/Number

Numeric input with range validation.

Repeatable

A group of subfields that can be repeated. Best for tabular data.

SQL

Dynamic dropdown populated by an SQL query.

Subform

Embed a group of reusable fields within another form.

Creating a Field

1. Go to Content > Fields (or Components > Fields)
2. Click New
3. Configure:

Assigning to Context

The field must be assigned to a context:

Displaying Custom Fields in Articles

By default, custom fields appear automatically in the article output, below the full text and above the tags.

Order of Display

Fields are displayed in the order they appear in the Fields manager. You can reorder them by dragging.

Template Override for Custom Fields

If you want full control over field display, override the layout:

1. Copy /components/com_content/tmpl/article/default.php to /templates/cassiopeia/html/com_content/article/default.php
2. In the override, add field rendering:

<?php
// In template override, render custom fields manually
$fields = FieldsHelper::getFields('com_content.article', $this->item, true);
foreach ($fields as $field) {
    if ($field->value) {
        echo '<div class="custom-field">';
        echo '<strong>' . $this->escape($field->label) . ':</strong> ';
        echo JLayoutHelper::render('joomla.content.field_value', $field);
        echo '</div>';
    }
}
?>

Alternatively, use a layout override for the whole field display:

<?php
// Get rendered field HTML
echo JLayoutHelper::render('joomla.content.blog_style_default_item_title', $this->item);
?>

Custom Fields on Users

1. Go to Components > Fields
2. Set context to com_users.user
3. Create fields: Phone, Department, Location, Bio
4. Users see these fields when editing their profile

Custom Fields on Contacts

1. Set context to com_contact.contact
2. Create fields: Office Hours, Department, Specialization
3. The fields appear in the contact form

Custom Fields on Categories

1. Set context to com_content.category
2. Create fields: Category Icon, Featured Status, Color Code
3. The fields appear in the category edit form

Rendering in Template Overrides

For advanced customization, use PHP in template overrides:

<?php
// Load custom fields helper
use Joomla\CMS\Fields\FieldsHelper;

// Get fields for this article
$fields = FieldsHelper::getFields(
    'com_content.article',
    $this->item,
    true  // Only visible fields
);

// Display each field with custom markup
foreach ($fields as $field) {
    echo '<div class="custom-field mb-2">';
    echo '<span class="custom-field-label fw-bold">' .
         htmlspecialchars($field->label) . ':</span> ';
    echo '<span class="custom-field-value">' .
         FieldsHelper::renderFieldValue($field, 'com_content.article') .
         '</span>';
    echo '</div>';
}
?>

Field Display in Feeds

Custom fields do not appear in RSS/Atom feeds by default. To include them, you need a plugin or custom feed layout override.

Common Mistakes

1. Not assigning a field to the correct context: A field created for com_content.article will not appear on user profiles. Always double-check the context setting.

2. Creating too many fields: Each field adds complexity to the article edit form. Group related fields into Field Groups and keep the total under 20 per content type.

3. Not setting default values: For List, Radio, and Checkbox fields, set sensible defaults. Empty fields can cause display issues in templates.

4. Using the wrong field type: A URL field validates URLs and may reject relative paths. A Text field accepts anything. Choose the type that validates correctly for your data.

5. Forgetting to render fields in template overrides: If you override the article layout, custom fields are not automatically displayed. Add the FieldsHelper::getFields() call explicitly.

Practice Questions

1. What content types support custom fields in Joomla? Answer: Articles (com_content.article), user profiles (com_users.user), contacts (com_contact.contact), and categories (com_content.category). Each context stores fields in the same database structure but associates them with the relevant content type.

2. How do you display custom fields in a template override? Answer: Use FieldsHelper::getFields('com_content.article', $item, true) to load visible fields, then loop through them with FieldsHelper::renderFieldValue() to display each field's rendered value.

3. What is the difference between a Repeatable field and a Subform field? Answer: A Repeatable field lets you define a set of subfields that can be repeated multiple times (like a table with rows). A Subform field embeds an entire group of fields (defined elsewhere) into another form. Subforms are more flexible for complex nested data.

4. Challenge: Create a complete set of custom fields for a "Recipes" content type. Include: cooking time (text), servings (integer), difficulty (list: easy, medium, hard), ingredients (repeatable field with name and amount), featured image (media), and dietary tags (multiple checkbox: vegetarian, vegan, gluten-free). Group these fields into a "Recipe Details" field group. Create 5 recipe articles with different values. Display the fields in the article output using a template override with custom CSS styling.

FAQ

Mini Project

Your task is to build a custom data solution for a job board site.

1. Create a field group called "Job Listing Fields" (context: com_content.article)

2. Create these custom fields in the group:

   • Location (List type: Remote, On-site, Hybrid)
   • Job Type (Radio: Full-time, Part-time, Contract, Internship)
   • Salary Range (Text: "$50k - $70k")
   • Application Deadline (Calendar type with Show Time = No)
   • Company Name (Text)
   • Company Logo (Image type, directory = images/logos/)
   • Apply URL (URL type)
   • Requirements (Editor type for rich formatting)

3. Create 5 job listing articles with values in all custom fields

4. Create a template override for the article layout that displays fields in a professional card layout

5. Style the output with CSS (use Bootstrap utility classes)

6. Verify fields display correctly on the frontend

Document your field configuration and template code.

What's Next

Now that you can extend content with custom fields, learn about the Joomla API:

Continue to Lesson 38: Joomla Web Services API — REST API and application endpoints.

Related lessons:

• {{< ilink "Joomla" "Joomla User Groups" }} — Control who can edit custom fields
• {{< ilink "Joomla" "Joomla Multilingual Sites" }} — Custom fields with translations