Custom Fields in Joomla

1. The Basics

1.1 What is a Custom Field?

A Custom Field is an extra input - beyond title and body - that you can attach to a Joomla item. Each field has a type (text, list, image, date, and so on), a name, a label, and a small set of configuration options.

You can attach Custom Fields to:

• Articles (com_content.article)
• Categories (com_content.categories)
• Contacts (com_contact.contact)
• Users (com_users.user)
• Tags (com_tags.tag)
• Third-party components that opt in

The context string (component.view) is what binds a field to its target. The same field engine powers all of these targets.

1.2 What Problem Do They Solve?

Before Custom Fields, editors had three options to store extra data on an article:

• Build a custom component.
• Hide HTML inside the article body.
• Install a third-party content construction kit (CCK) like K2, Seblod, or Fabrik.

Since Joomla 3.7, the CMS ships this out of the box. No extra extension is needed.

Without Custom Fields, editors tend to:

• Cram everything into the article body.
• Misuse the intro text.
• Rely on copy-paste templates.
• Forget required information.
• Produce inconsistent content.

With Custom Fields, you gain structured data, predictable layouts, validation, per-category forms, and rendering without code.

1.3 Where Do I Find Custom Fields?

In the Joomla 6 backend, every supported component has its own set of fields and field groups:

Content    → Fields                  (article fields)
Content    → Field Groups            (group fields together)
Components → Contacts → Fields    (contact fields)
Users      → Manage   → Fields    (user profile fields)
Components → Tags     → Fields    (tag fields)

1.4 The Four Concepts Behind Every Custom Field

Every Custom Field is defined by four decisions:

Get these four right and the rest is detail.

1.5 Field vs Field Group

It helps to keep two terms apart from the start:

Field Groups give you a shared heading, one template override per group, and a logical grouping in the editor interface.

3. The 18 Core Field Types in Joomla 6

Joomla 6 ships with 18 core field types, including two new ones: Number and Note. Each type is a plugin under plugins/fields/.

3.1 Basic Inputs

3.2 Choice Fields

3.3 Media Fields

The Media field uses Joomla 6's Media Manager modal, supports subfolders, and stores a path string.

3.4 Relational Fields

3.5 Number Fields

Use Number instead of Integer whenever decimals matter. Before Joomla 6, you had to fake this with a Text field plus a filter.

3.6 Date, Colour, and URL

3.7 Helper and Structural Fields

The Note field is purely instructional. It stores no value. It exists to help editors, not to capture data.

The Subform field is the workhorse for "one article has many of something". Its values are stored as JSON, which we will return to later.

3.8 The SQL Field

The SQL field renders a dropdown filled by a database query you write yourself. A typical query looks like this:

SELECT id AS value, title AS text
  FROM `#__content`
 WHERE catid IN (8) AND state = 1
 ORDER BY title ASC;

The SQL field is powerful but risky:

• The query runs with site privileges on every form load.
• Only Super Users are allowed to create SQL fields.
• Never build the query from unfiltered user input.

If you only need a simple lookup, use a regular List field instead.

3.9 At-a-glance Summary

5. Rendering Custom Fields

5.1 Automatic Display

The Automatic Display option places the rendered output in one of four positions:

• After Title: between the title and the intro text.
• Before Display Text: above the article body.
• After Display Text: below the article body.
• Do not automatically display: render it yourself.

A full Field Group renders together, as one block, in the defined order.

5.2 Manual Placement With Shortcodes

Inside the article body you can drop simple shortcodes:

            → renders field id 5 (label + value)
       → renders all fields in field group id 2

You can mix prose and field output:

Speaker: 
Date: 

5.3 Layout Overrides

Field rendering uses layouts under:

layouts/com_fields/
   render.php          (wrapper)
   field/
     render.php        (single field row)
     list.php          (list field type)
     media.php
     subform.php
     ...

Override them in your template:

templates/your_template/html/layouts/com_fields/field/render.php

For a single field type, override the file named after that type (for example media.php). For a single named field, use:

render-<fieldname>.php

5.4 Where the Values Come From

When Joomla loads an article, it:

1. Reads #__fields_values for that item id.
2. Joins #__fields for the metadata.
3. Filters by category assignment.
4. Filters by access level and permissions.
5. Renders the output through the layout chain.

7. The Subform Field

7.1 Why Use a Subform?

Use a Subform when one item has many of something, in a structured way:

• Sessions in a conference article.
• Speakers in an event.
• Downloads in a product page.
• FAQ entries in a help article.

Each row in a Subform is its own mini form, with its own inner fields.

7.2 How to Build One

1. Create the inner fields first (Text, URL, Image, and so on).
2. Create a Subform field.
3. On the Options tab, pick the inner fields. Set Repeatable to Yes and define minimum and maximum rows.
4. Assign the Subform to the right categories.

7.3 What Gets Stored

The Subform value is stored as JSON in #__fields_values.value:

[
  {"speaker_name": "Ada", "speaker_role": "Keynote"},
  {"speaker_name": "Tim", "speaker_role": "Workshop"}
]

This JSON drives both the editor interface and the rendered output.

7.4 Rendering a Subform

The Subform has its own layout file:

layouts/com_fields/field/subform.php

Override this file when you need full control over the loop, the markup, the CSS classes, and the per-row layout.

9. Under the Hood (Developer View)

9.1 The Four Database Tables

Custom Fields are stored in four core tables:

#__fields              field definitions (name, type, params, ...)
#__fields_groups       field group definitions
#__fields_values       per-item values (item_id, field_id, value)
#__fields_categories   field-to-category assignments

A value can be plain text, JSON (for a Subform), or any string the field type chooses.

9.2 Key Columns in #__fields

id
title
name           (machine name, used in )
type           (text, list, media, subform, ...)
context        (com_content.article, com_users.user, ...)
group_id
state          (1 published, 0 unpublished)
access
language
fieldparams    (JSON: type-specific options)
params         (JSON: display and behaviour)

9.3 Plugin Architecture

Custom Fields are plugins. Each field type lives in its own directory:

plugins/fields/<type>/

The core ships with: calendar, checkboxes, color, editor, imagelist, integer, list, media, note, number, radio, sql, subform, text, textarea, url, user, and usergrouplist.

A field-type plugin defines:

• How the input renders in the form (form XML).
• How the value renders on the frontend.
• Optional validation.
• Optional onSave and onPrepare logic.

9.4 Plugin Events

These are the seams for your own custom field type:

9.5 The PHP API

The modern, clean way to read fields from PHP:

use Joomla\Component\Fields\Administrator\Helper\FieldsHelper;

// All fields for an article, with values merged in
$fields = FieldsHelper::getFields(
    'com_content.article',
    $article,        // the article object: gives item id + category id
    true             // prepare values for display
);

foreach ($fields as $field) {
    echo $field->name . ' = ' . $field->rawvalue;
    echo $field->value;   // rendered HTML
}

A shorter legacy pattern still works inside content overrides:

echo $item->jcfields[3]->value;   // by field id

Prefer FieldsHelper::getFields(). It survives field-id changes between sites and gives you the full metadata.

9.6 Headless Joomla: Fields Over the Web Services API

Joomla's Web Services API returns custom field values alongside the item:

GET /api/index.php/v1/content/articles/42

The JSON response includes a fields collection with id, name, type, raw value, and rendered value. This makes Joomla a viable headless backend for:

• Vue, React, or Svelte frontends.
• Static-site generators.
• Native mobile apps.
• AI and automation pipelines.

Only published fields that the API user can access are returned. ACL still applies over the API.

9.7 Building Your Own Field Type

1. Create a plugin folder under plugins/fields/myfield/.
2. Add a manifest XML and a main PHP class extending FieldsPlugin.
3. Implement getInputXml() for the editor input.
4. Implement onCustomFieldsPrepareField() for the rendered output.
5. Install through Discover, or as a packaged zip.
6. The new type now appears in the field-type dropdown.

11. Ecosystem and Extensions

11.1 Conditional Custom Fields

Conditional fields appear or disappear depending on the value of another field. This is native in Joomla 6 through plugin settings. A typical example is showing a "Ticket URL" field only when the "Has tickets" checkbox is on.

11.2 YOOtheme Pro

YOOtheme Pro is a popular page builder template that reads Joomla Custom Fields into its dynamic content system:

• Drop a custom field value into any builder element.
• Filter and sort dynamic lists by custom field values.
• Use the built-in Location field (latitude and longitude) on a map.

If your team already uses YOOtheme, you may never need to write a layout override for fields.

11.3 Advanced Custom Fields by Tassos

This third-party extension adds field types that core does not ship, plus richer rendering and conditional logic. It is useful when core's 18 types are not enough, but a full CCK would be overkill.

11.4 When to Reach for a CCK Instead

Custom Fields shine for content with extra attributes. For real database-driven applications (booking systems, real-estate listings with search facets, complex relations), consider:

• Seblod or Fabrik: full content construction kits.
• A custom component that plugs into com_fields.

13. Summary

Custom Fields turn Joomla from a basic CMS into a lightweight content modelling platform. They define:

• Structure: content with a predictable shape.
• Reusability: the same fields across many items.
• Per-category user experience: editors see only what they need.
• Rendering: automatic, shortcode, or full template override.
• Permissions: clear control over who edits and who sees what.
• Extensibility: your own field types through plugins.
• Integration: articles, users, contacts, tags, categories, and third-party components.

A well-designed set of Custom Fields makes a Joomla website easier to edit, easier to maintain, and easier to extend. Poorly named or badly assigned fields create problems that grow with the site.

If you are planning a new Joomla project, modelling a complex content type, or thinking about going headless, Custom Fields are one of the first places to look. They are a quiet but powerful part of what makes Joomla different from a one-shape-fits-all CMS.