The Solspace team is expanding! If you love Craft CMS and youโ€™re looking for an exciting full-time remote position working on software development for the Freeform and Calendar plugins for Craft and more, weโ€™d love to hear from you!

Check Out Job Listing!

Field object

Each field object contains the metadata specified in Composer for the specific form it resides in. It can render its label, input field, instructions and errors out of the box.


  • id #
  • handle #
  • label #
  • instructions #
  • required: true #
    • A boolean value. true if the field is required.
  • errors #
    • An array of error message strings if any are present after submitting the form.
  • pageIndex #
    • A number representing the page index this field resides on.
  • customAttributes #
    • An object of customizable attributes to ease the customizability of render methods.
    • Contains the following properties (each one is null if not set).
      • id #
        • The ID attribute of the HTML input field for renderInput().
        • When used on renderLabel(), it will replace the default for attribute value.
      • class #
        • The CLASS attribute of the HTML input field for renderInput().
      • labelClass #
        • The CLASS attribute of the HTML label field for renderLabel().
      • errorClass #
        • The CLASS attribute of the errors HTML list for renderErrors().
      • instructionsClass #
        • The CLASS attribute of the instructions HTML field for renderInstructions().
      • instructionsBelowField #
        • A boolean value.
        • Set to true to render instructions below, not above the input field when using the render() method.
      • overrideValue #
        • An override value for the field's defaultValue in case you need a context specific default value.
      • inputAttributes #
        • An object of attributes which will be added to the input field. If the form has inputAttributes specified, the attributes will be merged together with field inputAttributes taking precedence over form's inputAttributes.
        • Ex: inputAttributes: { "readonly": true, "data-field-id": "test" }
      • useRequiredAttribute: true #
        • Adds required attribute to input fields that have been set to be required in Composer.
  • idAttribute #
    • The ID for the field.
    • Considers the fieldIdPrefix parameter available to the freeform.form function.
  • value #
    • The default or posted value of the field.
    • Can be a string, number or array (it's an array only for checkbox_group and email fields)
  • valueAsString #
    • The value value cast as a string.
    • Array values get joined via a , separator.
    • Uses the selected option labels for checkbox_group and radio_group.
      • Use getValueAsString(false) to use selected option values instead.
  • type #
    • Type of the field:
      • text
      • textarea
      • hidden
      • select
      • checkbox
      • checkbox_group
      • radio_group
      • email
      • dynamic_recipients
      • file
      • mailing_list
      • html
      • submit
      • number
      • rating Pro
      • opinion_scale Pro
      • table Pro
      • signature Pro
  • rulesHtmlData #
    • Parses the necessary code for Conditional Rules feature.
    • Should be used in automated form rendering, placed on the div wrapper for each field inside of {% for field in row %}.
      • E.g. <div class="{{ columnClass }}"{{ field.rulesHtmlData }}>
      • Will render a data-ff-rule attribute along with the necessary string to work with Freeform's inserted JS for Rules feature, e.g. data-ff-rule='{"show":true,"type":"any","criteria":[{"tgt":"firstName","o":"=","val":"Bob"}]}'.

Field Specific Properties

Each field type has their own specific properties available to them. Some are more complex than others. To see all available properties, check out the Fields & Field Types documentation.


  • render() #
    • Use this method to render a predefined, minimal markup html block containing the field's label, input field, instructions and list of errors.
    • Can receive an object of customAttributes as the first and only argument (optional).
    • When using with HTML blocks or Submit buttons, use the hash value provided in property editor in Composer as the handle. Example code would look like:
      • {{ form.get('Ajx7jNxXL').render }}
  • renderLabel() #
    • Use this method to only render the label html field with the field's label inside.
    • The label class can be overwritten via form's custom attributes or the field's custom attributes.
  • renderInput() #
    • Use this method to only render the field's html input field.
    • The class can be overwritten via form's custom attributes or the field's custom attributes.
    • Single Checkbox fieldtype has an additional method: renderSingleInput() to render the checkbox input without an additional hidden input.
  • renderInstructions() #
    • Use this method to only render the field's html instructions field. (Renders only if there are instructions present).
    • The instructions field class can be overwritten via form's custom attributes or the field's custom attributes.
  • renderErrors() #
    • Use this method to only render the error message block. (Renders only if there are errors present).
    • The error list class can be overwritten via form's custom attributes or the field's custom attributes.
  • isValid() #
    • Returns a boolean value of true if the form has been posted and this field doesn't contain any errors.

Usage in Templates

Render the whole field (label, input field, instructions and errors) with a single line:

{{ field.render() }}

Render each part of the field separately:

{{ field.renderLabel() }}
{{ field.renderInstructions() }}
{{ field.renderInput() }}
{{ field.renderErrors() }}

Fully customize the output of your field:

<label data-label class="label">
  {{ field.label }}
  {% if field.instructions %}
    <span class="instructions">{{ field.instructions }}</span>
  {% endif %}
<input type="text" name="{{ field.handle }}" value="{{ field.valueAsString }}" data-some-value="my_custom_value_here" />
{% if field.errors %}
  {% for errorString in field.errors %}
    <div class="error">{{ errorString }}</div>
  {% endfor %}
{% endif %}

Render the whole field but override some of the HTML element classes:

{{ field.render({
  class: "freeform-input",
  labelClass: "freeform-label" ~ (field.required ? " freeform-required" : ""),
  errorClass: "freeform-errors",
  instructionsClass: "freeform-instructions",
  instructionsBelowField: true,
  overrideValue: "This is now the new default value",
  inputAttributes: {
    "data-field-id": field.id,
}) }}
Last Updated: 1/14/2020, 3:35:55 PM