Custom fields

Custom fields are plugins that extend Strapi’s capabilities by adding new fields to content-types. Once created or installed, custom fields can be used in the Content-Types Builder and Content Manager just like built-in fields.

The present reference documentation is intended to custom fields creators. It describes how custom fields work and can be created from a developer point of view, describing the APIs available to build a new custom field. The user guide describes how to install and use custom fields from Strapi's admin panel.

🤓 Prefer to learn by building?

If you'd rather directly jump to a concrete example, see the Creating a color custom field guide page for step-by-step instructions on how to build your first custom field from scratch.

Custom fields are a specific type of Strapi plugins that include both a back-end (or server) part and a front-end (or admin panel) part. Both parts should be registered for the custom fields to be available and usable in the Content-Types Builder and Content-Manager:

• strapi.customFields.register registers the server part of a custom field in strapi-server.js
• app.customFields.register registers the admin panel part of a custom field in strapi-admin.js

Registering a custom field on the server

On the server part, Strapi needs to be aware of all custom fields to ensure that an attribute using a custom field is valid. To achieve this, the strapi.customFields object exposes a register() method on the Strapi instance.

strapi.customFields.register() registers a custom field on the server during the plugin's server register lifecycle and should pass an object with the following parameters:

Parameter	Description	Type
name	The name of the custom field	String
plugin (optional)	The name of the plugin creating the custom fields	String
type	The existing, built-in Strapi data type the custom field will use (e.g. string, number, JSON — see models documentation for the full list).	String

Example: Registering an example "color" custom field on the server:

// path: ./src/plugins/my-custom-field-plugin/strapi-server.js

module.exports = {
  register({ strapi }) {
    strapi.customFields.register({
      name: 'color',
      plugin: 'my-custom-field-plugin',
      type: 'text',
    });
  },
};

Registering a custom field in the admin panel

On the admin panel part, the custom field should be described to be available in the Content-Type Builder and the Content Manager. To achieve this, the app.customFields exposes a register method on the StrapiApp instance.

app.customFields.register() registers a custom field in the admin panel during the plugin's admin bootstrap lifecycle and should pass an object (or an array of objects) with the following parameters:

Parameter	Description	Type
name	The name of the custom field	String
pluginId (optional)	The name of the plugin creating the custom field	String
type	The existing Strapi data type the custom field will use	String
intlLabel	The translation for the name	IntlObject
intlDescription	The translation for the description	IntlObject
icon (optional)	The icon for the custom field	React.ComponentType
components	The components needed to display the custom field in the Content Manager. Should include: Input: () => Promise<{ default: React.ReactComponent }>; to define the React component to be used in the Content Manager's edit view View: () => Promise<{ default: React.ReactComponent }>; to define a read-only component for the List view	Object
options (optional)	The settings to extend in the Content-Type Builder	Object