---
title: "Custom fields"
date: 2026-10-08
description: "Sync Joomla custom field values with ContentSync PRO: how fields are matched by name, the field mapping, the supported field types and what is skipped."
author: "Claude MCP"
---

# Custom fields

Custom fields are the extra fields you add to articles in Joomla, such as a subtitle, a price or an event date. With the PRO edition, ContentSync copies their values along with the article.

## Create the fields on the target site first

ContentSync copies values. It does not create fields. Before you switch this on, make the same fields on the target site, under **Content \> Fields**.

Two things have to be the same on both sites:

- the **Name** of the field. That is the technical name, not the title. You find it in the field itself, under the title;
- the **Type** of the field.

The title, the description and the field group may be different.

## Switching it on

Open your task and set **Sync Custom Fields** to Yes.

From the next run, every article that is created or updated gets its field values. The log tells you how many fields are synced, and names every field that is skipped with the reason.

Articles that were copied before only get their fields once they change on the source. To fill them all in at once, switch on **Force Resync** for one run.

## When a field has another name

Is the field called `subtitle` on the source and `sub-title` on the target? Add a line to **Field Mapping**: the name on the source, a colon, the name here.

```
subtitle:sub-title
```

You only need this for fields whose names differ. Fields with the same name are matched by themselves.

## Supported field types

- Text, textarea and editor
- URL
- Integer and number
- Calendar
- Color
- List, radio and checkboxes
- Media and media file

For a list, radio or checkboxes field, give the options the same values on both sites. The value is what is stored, the label is only what you see.

For a media field, the image is downloaded to the target site, under the same rules as other images. See [Images, documents and media](https://www.joomill-extensions.com/index.php?option=com_content&view=article&id=471&catid=118).

## Field types that are skipped

- **User**, **user groups** and **SQL** fields. Their value is the number of a user, a group or a database row, and that number means something else on another site.
- **Subform** fields. A subform refers to its inner fields by number.
- **List of images**. It depends on a folder that is set inside the field.
- Field types that come from another extension.

A skipped field is named in the log once per run. The rest of the article is copied as usual.

## What the source site has to allow

To know the type of each field, ContentSync asks the source site for its list of fields, once per run. The user whose API token you use needs access to **Fields** on the source site. A Super User has that.

If the list cannot be read, custom fields are left out for that run, with a warning in the log. The articles themselves are still copied.

Only published fields are synced. A field that is unpublished on the source sends no values.

## Good to know

- Textarea and editor fields go through the same HTML filter as the article text.
- A URL field only accepts a web address or a path. Anything that could run script is left out.
- A field that is empty on the source gets the default value of the source field, because that is what Joomla hands over.
- When an article is permanently deleted by ContentSync, its field values are removed too.