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
columnWidthHow many columns (out of 12) this field takes up.
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.

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.

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.

Checkboxes #

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

Date/Time #

SettingDescription
includeTimeWhether this field should include the time.
defaultValueEntering a default value will place the value in the field when it loads.
displayTypeSet different display layouts for this field.

Dropdown #

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.

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.

Group #

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.
richTextButtonsAn array of available buttons the Rich Text field should use. Consult the Pell 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.
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.
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.
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.

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.

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.

Get started with Formie

Available for Craft 3. Get it from the plugin store.