Create a custom configuration field

Your plugin can offer the standard configuration fields available to all Form controls, such as fields to set the control's description, read-only status, or whether it is a required field when submitting the form.

You can also add custom configuration fields to add additional configuration options to your plugin or to Store a value in an output variable.

Custom fields must have a data type, which can be a string of text, an integer or floating point number, a boolean, or a choice from a drop-down list of options.

Jump to:

Custom configuration fields are added in the getMetaConfig() function using the properties object.

Note: Most examples in this documentation use the reactive properties feature of the Lit framework. When a property is reactive, as denoted by @property() , Lit creates a getter and setter pair for the property and schedules a DOM render whenever the property is changed. If you are not using Lit or a similar framework that offers this functionality and you want the plugin to update when properties are changed, you will need to implement this yourself. For more information on using Lit, see Get started with web components and Lit.

Add a custom field

In the getMetaConfig() function, add a properties object.
Inside the properties object, add an object called the name of your custom field. In this example, the field is called myCustomField.
Inside the object, add the properties to define your custom field:
- A type property with a value corresponding to your field's data type.
- A title property with the label you want to appear for this field in the plugin's configuration panel.

For a full list of properties you can use to define your custom field, see Custom field properties.

//...
static getMetaConfig() {

  return {
    //...
    properties: {
      myCustomField: {
        type: 'string',
        title: 'My custom field',
      },
    },
  };
}

Add multiple custom fields

Add multiple custom fields by defining multiple objects in the properties object.

Note: Only one custom field can contain the property isValueField.

See Custom field properties.

//...
static getMetaConfig() {

  return {
    //...
    properties: {
      myVeryLongField: {
        type: 'string',
        title: 'A very long string',
        maxLength: 1000,
      },
      valueField: {
        type: 'integer',
        title: 'Value',
        isValueField: true,
        default: 10,
      },
      myEmailField: {
        type: 'string',
        title: 'Email',
        format: 'email',
      },
    },
  };
}

Flag custom fields as required

Required fields must be completed by the form designer when configuring the plugin.

To flag one or more custom fields as required, add the required property with a value of true in the field definition.

See Custom field properties.

//...
static getMetaConfig() {

  return {
    //...
    properties: {
      myCustomField: {
        type: 'string',
        title: 'My custom field',
        required: true
      },
      valueField: {
        type: 'integer',
        title: 'Value',
        isValueField: true,
        default: 10,
      },
    },
  };
}