Field#

A Field object represents a form field of a particular type. Each field has its own unique attributes and functionality. Whenever you're dealing with a field in your template, you're actually working with a Field object.

Attributes#

AttributeDescription
idID of the field.
nameThe name of the field.
labelAn alias to name.
handleThe handle of the field.
typeThe type of the field.
formThe Form this field belongs to.
formIdThe Form ID for the form this field belongs to.
rowIdThe Row ID for the row this field belongs to.
rowIndexThe Row index for the row this field belongs to. This is used for field ordering.
settingsA collection of settings for the field. See Field Settings.

Methods#

MethodDescription
getSvgIcon()Returns the contents of an SVG icon used for a field type.
getSvgIconPath()Returns the path to the SVG icon used for a field type.
getIsNew()Denotes whether this field is new.
hasLabel()Whether the field has a label or not. Some fields do not have one.
renderLabel()An alias to hasLabel().
getIsTextInput()Whether this field is classified as a text input.
getIsSelect()Whether this field is classified as a select input.
getIsFieldset()Whether this field contains a fieldset. Normally, for when fields have sub-fields.
getExtraBaseFieldConfig()Returns any base-level configuration data for the field.
getFieldDefaults()Returns any defaults for the field, when it's created.
getContainerAttributes()Returns an array of options for container attributes.
getInputAttributes()Returns an array of options for input attributes.
getFrontEndInputHtml()Returns the HTML for a the front-end template for a field.
getFrontEndInputOptions()Returns an object of variables that can be used for front-end fields.
getEmailHtml()Returns the HTML for an email notification for a field.
afterCreateField()A function called after a field has been created in the control panel.

Field Settings#

The settings for a field will differ per-type, but the following are general settings applicable to all fields.

AttributeDescription
labelPositionThe position of the field's label.
instructionsPositionThe position of the field's instructions.
cssClassesAny CSS classes, applied on the outer container of a field.
containerAttributesA collection of attributes added to the outer container of a field.
inputAttributesA collection of attributes added to the input element of a field - where applicable.

Address#

SettingDescription
address1LabelThe label for the Address 1 sub-field.
address1PlaceholderThe placeholder for the Address 1 sub-field.
address1DefaultValueThe default value for the Address 1 sub-field.
address1RequiredWhether the Address 1 sub-field should be required.
address1ErrorMessageThe error message for the Address 1 sub-field.
address1CollapsedWhether the Address 1 sub-field is collapsed in the control panel.
address1EnabledWhether the Address 1 sub-field is enabled in the control panel.
address2LabelThe label for the Address 2 sub-field.
address2PlaceholderThe placeholder for the Address 2 sub-field.
address2DefaultValueThe default value for the Address 2 sub-field.
address2RequiredWhether the Address 2 sub-field should be required.
address2ErrorMessageThe error message for the Address 2 sub-field.
address2CollapsedWhether the Address 2 sub-field is collapsed in the control panel.
address2EnabledWhether the Address 2 sub-field is enabled in the control panel.
address3LabelThe label for the Address 3 sub-field.
address3PlaceholderThe placeholder for the Address 3 sub-field.
address3DefaultValueThe default value for the Address 3 sub-field.
address3RequiredWhether the Address 3 sub-field should be required.
address3ErrorMessageThe error message for the Address 3 sub-field.
address3CollapsedWhether the Address 3 sub-field is collapsed in the control panel.
address3EnabledWhether the Address 3 sub-field is enabled in the control panel.
cityLabelThe label for the City sub-field.
cityPlaceholderThe placeholder for the City sub-field.
cityDefaultValueThe default value for the City sub-field.
cityRequiredWhether the City sub-field should be required.
cityErrorMessageThe error message for the City sub-field.
cityCollapsedWhether the City sub-field is collapsed in the control panel.
cityEnabledWhether the City sub-field is enabled in the control panel.
stateLabelThe label for the State sub-field.
statePlaceholderThe placeholder for the State sub-field.
stateDefaultValueThe default value for the State sub-field.
stateRequiredWhether the State sub-field should be required.
stateErrorMessageThe error message for the State sub-field.
stateCollapsedWhether the State sub-field is collapsed in the control panel.
stateEnabledWhether the State sub-field is enabled in the control panel.
zipLabelThe label for the Zip sub-field.
zipPlaceholderThe placeholder for the Zip sub-field.
zipDefaultValueThe default value for the Zip sub-field.
zipRequiredWhether the Zip sub-field should be required.
zipErrorMessageThe error message for the Zip sub-field.
zipCollapsedWhether the Zip sub-field is collapsed in the control panel.
zipEnabledWhether the Zip sub-field is enabled in the control panel.
countryLabelThe label for the Country sub-field.
countryPlaceholderThe placeholder for the Country sub-field.
countryDefaultValueThe default value for the Country sub-field.
countryRequiredWhether the Country sub-field should be required.
countryErrorMessageThe error message for the Country sub-field.
countryCollapsedWhether the Country sub-field is collapsed in the control panel.
countryEnabledWhether the Country sub-field is enabled in the control panel.
countryOptionsAn array of options available to pick a country from.

Agree#

SettingDescription
descriptionThe description for the field. This will be shown next to the checkbox.
checkedValue The value of this field when it is checked.
uncheckedValueThe value of this field when it is unchecked.
defaultValueThe default value for the field when it loads.

Calculations#

SettingDescription
formulaThe raw formula used in the field, before it's been parsed.
MethodDescription
getFormula()Returns the parsed formula, given the current submission's context.

Categories#

SettingDescription
placeholderThe option shown initially, when no option is selected.
sourceWhich source do you want to select categories from?
branchLimitLimit the number of selectable category branches.
rootCategoryThe category to act as the root, if set.
showStructureWhether the structure of categories should be shown.

Checkboxes#

SettingDescription
optionsDefine the available options for users to select from.
layoutSelect which layout to use for these fields.

Date/Time#

SettingDescription
minDateThe minimum allowed date.
maxDateThe maximum allowed date.
defaultValueEntering a default value will place the value in the field when it loads.
displayTypeSet different display layouts for this field.
dateFormatThe chosen format for the date.
timeFormatThe chosen format for the time.
includeDateWhether this field should include the date.
includeTimeWhether this field should include the time.
timeLabelThe label for the time sub-field.
dayLabelThe label for the day sub-field.
dayPlaceholderThe placeholder for the day sub-field.
monthLabelThe label for the month sub-field.
monthPlaceholderThe placeholder for the month sub-field.
yearLabelThe label for the year sub-field.
yearPlaceholderThe placeholder for the year sub-field.
hourLabelThe label for the hour sub-field.
hourPlaceholderThe placeholder for the hour sub-field.
minuteLabelThe label for the minute sub-field.
minutePlaceholderThe placeholder for the minute sub-field.
secondLabelThe label for the second sub-field.
secondPlaceholderThe placeholder for the second sub-field.
ampmLabelThe label for the AM/PM sub-field.
ampmPlaceholderThe placeholder for the AM/PM sub-field.
useDatePickerWhether this field should use the Flatpickr datepicker.
datePickerOptionsA collection of options for the Flatpickr datepicker.
SettingDescription
multipleWhether this field should allow multiple options to be selected.
optionsDefine the available options for users to select from.

Email Address#

SettingDescription
placeholderThe text that will be shown if the field doesn’t have a value.
defaultValueEntering a default value will place the value in the field when it loads.
validateDomainWhether to validate the domain when the value is saved.
blockedDomainsA list of domains to block values from.
uniqueValueWhether to the value of this field should be unique across all submissions for the form.

Entries#

SettingDescription
placeholderThe option shown initially, when no option is selected.
sourcesWhich sources do you want to select entries from?
limitLimit the number of selectable entries.

File Upload#

SettingDescription
uploadLocationSourceThe volume for files to be uploaded into.
uploadLocationSubpathThe sub-path for the files to be uploaded into.
limitFilesLimit the number of files a user can upload.
sizeLimitLimit the size of the files a user can upload.
allowedKindsA collection of allowed mime-types the user can upload.

Heading#

SettingDescription
headingSizeChoose the size for the heading.

Hidden#

SettingDescription
defaultOptionThe selected option for the preset default value chosen.
defaultValueEntering a default value will place the value in the field when it loads. This will be dependant on the value chosen for the defaultOption.
queryParameterIf query string is selected for the defaultOption, this will contain the query string parameter to look up.

Html#

SettingDescription
htmlContentEnter HTML content to be rendered for this field.

Multi-Line Text#

SettingDescription
placeholderThe text that will be shown if the field doesn’t have a value.
defaultValueEntering a default value will place the value in the field when it loads.
limitWhether to limit the content of this field.
limitTypeEither words or characters.
limitAmountThe number of character or words to limit this field by.
useRichTextWhether the front-end of the field should use a Rich Text editor. This is powered by Pell (opens new window).
richTextButtonsAn array of available buttons the Rich Text field should use. Consult the Pell (opens new window) docs for these options.

Name#

SettingDescription
useMultipleFieldsWhether this field should use multiple fields for users to enter their details.
prefixLabelThe label for the Prefix sub-field.
prefixPlaceholderThe placeholder for the Prefix sub-field.
prefixDefaultValueThe default value for the Prefix sub-field.
prefixRequiredWhether the Prefix sub-field should be required.
prefixErrorMessageThe error message for the Prefix sub-field.
prefixCollapsedWhether the Prefix sub-field is collapsed in the control panel.
prefixEnabledWhether the Prefix sub-field is enabled in the control panel.
prefixOptionsAn array of options available to pick a prefix from.
firstNameLabelThe label for the First Name sub-field.
firstNamePlaceholderThe placeholder for the First Name sub-field.
firstNameDefaultValueThe default value for the First Name sub-field.
firstNameRequiredWhether the First Name sub-field should be required.
firstNameErrorMessageThe error message for the First Name sub-field.
firstNameCollapsedWhether the First Name sub-field is collapsed in the control panel.
firstNameEnabledWhether the First Name sub-field is enabled in the control panel.
middleNameLabelThe label for the Middle Name sub-field.
middleNamePlaceholderThe placeholder for the Middle Name sub-field.
middleNameDefaultValueThe default value for the Middle Name sub-field.
middleNameRequiredWhether the Middle Name sub-field should be required.
middleNameErrorMessageThe error message for the Middle Name sub-field.
middleNameCollapsedWhether the Middle Name sub-field is collapsed in the control panel.
middleNameEnabledWhether the Middle Name sub-field is enabled in the control panel.
lastNameLabelThe label for the Last Name sub-field.
lastNamePlaceholderThe placeholder for the Last Name sub-field.
lastNameDefaultValueThe default value for the Last Name sub-field.
lastNameRequiredWhether the Last Name sub-field should be required.
lastNameErrorMessageThe error message for the Last Name sub-field.
lastNameCollapsedWhether the Last Name sub-field is collapsed in the control panel.
lastNameEnabledWhether the Last Name sub-field is enabled in the control panel.

Number#

SettingDescription
placeholderThe text that will be shown if the field doesn’t have a value.
defaultValueEntering a default value will place the value in the field when it loads.
limitWhether to limit the numbers for this field.
minThe minimum number that can be entered for this field.
maxThe maximum number that can be entered for this field.
decimalsSet the number of decimal points to format the field value.

Phone#

SettingDescription
showCountryCodeWhether to show an additional dropdown for selecting the country code.
countryShowDialCodeWhether to show an the dial code.
countryAllowedA collection of allowed countries.
countryLabelThe label for the Country sub-field.
countryPlaceholderThe placeholder for the Country sub-field.
countryDefaultValueThe default value for the Country sub-field.
countryCollapsedWhether the Country sub-field is collapsed in the control panel.
countryEnabledWhether the Country sub-field is enabled in the control panel.
countryOptionsAn array of options available to pick a country from.
numberLabelThe label for the Number sub-field.
numberPlaceholderThe placeholder for the Number sub-field.
numberDefaultValueThe default value for the Number sub-field.
numberCollapsedWhether the Number sub-field is collapsed in the control panel.

Products#

SettingDescription
placeholderThe option shown initially, when no option is selected.
sourcesWhich sources do you want to select products from?
limitLimit the number of selectable products.

Radio#

SettingDescription
optionsDefine the available options for users to select from.
layoutSelect which layout to use for these fields.

Recipients#

SettingDescription
displayTypeWhat sort of field to show on the front-end for users.
optionsDefine the available options for users to select from.

Repeater#

SettingDescription
addLabelThe label for the button that adds another instance.
minRowsThe minimum required number of instances of this repeater's fields that must be completed.
maxRowsThe maximum required number of instances of this repeater's fields that must be completed.

Section#

SettingDescription
borderAdd a border to this section.
borderWidthSet the border width (in pixels).
borderColorSet the border color.

Signature#

SettingDescription
backgroundColorSet the background color.
penColorSet the pen color.
penWeightSet the line thickness (weight) for the pen.

Single-Line Text#

SettingDescription
placeholderThe text that will be shown if the field doesn’t have a value.
defaultValueEntering a default value will place the value in the field when it loads.
limitWhether to limit the content of this field.
limitTypeEither words or characters.
limitAmountThe number of character or words to limit this field by.

Table#

SettingDescription
columnsDefine the columns your table should have.
defaultsDefine the default values for the field.
addRowLabelThe label for the button that adds another row.
staticWhether this field should disallow adding more rows, showing only the default rows.
minRowsThe minimum required number of rows in this table that must be completed.
maxRowsThe maximum required number of rows in this table that must be completed.

Tags#

SettingDescription
placeholderThe option shown initially, when no option is selected.
sourceWhich source do you want to select tags from?

Users#

SettingDescription
placeholderThe option shown initially, when no option is selected.
sourcesWhich sources do you want to select users from?
limitLimit the number of selectable users.

Variants#

SettingDescription
placeholderThe option shown initially, when no option is selected.
source Which source do you want to select variants from?
limitLimit the number of selectable variants.

Custom Validation#

You can add custom validation to field, to handle all manner of scenarios. To do this, you'll need to create a custom module to contain PHP code for the validation logic.

Make sure you’re comfortable creating a plugin or module for Craft CMS (opens new window). Take a look at this Knowledge Base (opens new window) article for a complete example.

If you write your own plugin or module, you’ll want to use its init() method to subscribe to an event on the Submission object to add your validation rules. Your event listener can add additional validation rules (opens new window) for fields.

For example, let's say we have a field with a handle emailAddress which we'd like required. We could do this with the following.

use verbb\formie\elements\Submission;
use verbb\formie\events\SubmissionRulesEvent;
use yii\base\Event;

Event::on(Submission::class, Submission::EVENT_DEFINE_RULES, function(SubmissionRulesEvent $event) {
    $event->rules[] = [['field:emailAddress'], 'required'];
});

Or, maybe we only want a field required when another field is a certain value.

Event::on(Submission::class, Submission::EVENT_DEFINE_RULES, function(SubmissionRulesEvent $event) {
    $event->rules[] = [['field:emailAddress'], 'required', 'when' => function($model) {
        return $model->subscribeMe;
    }];
});

Here, we check if a field with handle subscribeMe is truthy, and if so make the emailAddress field required.

Another example could be limiting a field to be numeric, and a maximum length.

Event::on(Submission::class, Submission::EVENT_DEFINE_RULES, function(SubmissionRulesEvent $event) {
    $event->rules[] = [['field:accountNumber'], 'number', 'integerOnly' => true, 'max' => 9];
});

You can also customise the validation message with number validation when using min/max with tooSmall and tooBig.

However, the above rules are applied to every submission, which will throw an error if you set a rule for a field that doesn't exist on the form for the submission you're creating. The above example assumes you have a field with the handle emailAddress for every form, which may not always be the case, especially if you have multiple forms.

Instead, you'll want to add a conditional check what form you're creating a submission on.

Event::on(Submission::class, Submission::EVENT_DEFINE_RULES, function(SubmissionRulesEvent $event) {
    $form = $event->submission->getForm();

    // Only apply this custom validation for the form with handle `contactForm`
    if ($form->handle === 'contactForm') {
        $event->rules[] = [['field:emailAddress'], 'required'];
    }
});

If you have a lot of forms, or would rather not conditionally check every form for your site, you can loop through the available fields for the submission, to add a check whether the field exists. This can be useful if you want to enforce a validation for all email fields across your site, but not every form has an emailAddress field.

Event::on(Submission::class, Submission::EVENT_DEFINE_RULES, function(SubmissionRulesEvent $event) {
    if ($fieldLayout = $event->submission->getFieldLayout()) {
        foreach ($fieldLayout->getFields() as $field) {
            // Check against the handle of the field
            if ($field->handle === 'emailAddress') {
                $event->rules[] = [['field:emailAddress'], 'required'];
            }

            // Or, for a more global-check - against the type of the field
            if ($field instanceof \verbb\formie\fields\formfields\Email) {
                $event->rules[] = [['field:emailAddress'], 'required'];
            }
        }
    }
});

Previous ← Row Next Submission →