Skip to documentation content

Form Field

On this page

    The form field object and its typed field variants.

    {{ form_field }} is the shared shape for a form control. It is not a separate runtime type: each field is one of the typed field objects on this page (text_field, select_field, and the rest). Use object_type or type to tell which implementing type you have. Typed objects add the properties for that field type.

    {{ form_field }}

    {{ form_field }} is the shared shape for a form control. It is not a separate runtime type: each field is one of the typed field objects (text_field, select_field, and the rest). Use object_type or type to tell which implementing type you have.

    Properties
    Name Type Description
    is_valid boolean Will always be true
    value string Synonym for guid
    object_type string The object_type of the implementing field (for example text_field or select_field)
    classname string CSS class name(s) to be applied to the field
    type string The field type (text, textarea, select, checkbox, etc...)
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    field_id string The identifier for this field
    label string The label for this field
    output string The default output that the form_field would produce if it were output directly to the template. The default output may change at any time. Template developers should avoid using this and should handle the output of different form fields themselves. May include additional markup in the editor preview to make it easier to edit content

    Typed field objects add further properties that are not listed here. See each type on this page.

    Example Load one form and list each form_field label{% form %} loads a single form by name or GUID; fields is the list of form_field controls on that form.
    Liquid
    {%- form var contact = "Contact Us" -%}
{%- if contact.is_valid -%}
	<h2>{{ contact.title }}</h2>
	<ul>
	{%- for field in contact.fields -%}
		<li>{{ field.label }} ({{ field.object_type }})</li>
	{%- endfor -%}
	</ul>
{%- endif -%}

    {% form %} fetches a single form. Pass a name or GUID after the assignment target. Form-specific fields include fields (the ordered form_field list), form_start, form_end, redirect_url, and javascript helpers, plus shared entity properties such as title and is_valid.

    {{ hidden_field }}

    Should be used to output a hidden field inside a form, which by definition is not displayed to or directly editable by users.

    Properties
    Name Type Description
    object_type string Will always be hidden_field
    is_valid boolean Will always be true
    type string Will always be "hidden"
    field_id string The value that should be used for the name attribute of the hidden field
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    classname string CSS class name(s) to be applied to the field. Although the field is not displayed, the classname may still be used when setting the field value (eg: for the editor to specify the type of data to save in the field)
    map_to_attribute string If the user is signed into a profile when they submit this form and map_to_attribute is set, the profile attribute specified in map_to_attribute will be set to the value of this field. This should also be used to override the default value if the user is signed into a profile and the specified attribute has already been set
    output string Default HTML markup for this field, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more

    Hidden form fields are generally only useful for template developers, since the user is not able to directly edit their value. When including a hidden field in a form, developers should ensure that there is some way for the value to be set - typically either using liquid markup to specify the value explicitly in the template or using javascript after the form is displayed to calculate and set a dynamic value

    Example Output hidden_field using field_id as the name attributehidden_field has no label; field_id is the value to use for the input's name attribute, and its value must be supplied by the template.
    Liquid
    {%- if form_field.object_type == "hidden_field" -%}
	<input type="hidden" name="{{ form_field.field_id }}" value="{{ entity.canonical_name }}"{% if form_field.classname %} class="{{ form_field.classname }}"{% endif %}>
{%- endif -%}

    hidden_field has no label property, unlike the other typed fields on this page: it is never shown to or directly edited by the visitor. field_id names the field, but its value is never set automatically, so the template must supply one, either with Liquid markup as shown here or with javascript once the form is displayed.

    {{ checkboxlist_field }}

    Should be used to display a list of checkboxes inside a form.

    Properties
    Name Type Description
    object_type string Will always be checkboxlist_field
    is_valid boolean Will always be true
    type string Will always be "checkboxlist"
    items object A dictionary containing all of the checkboxes and their values to be included in the checkboxlist, where the keys are the value to be stored and the values are the text to be displayed
    options string The raw and un-parsed options for the checkboxlist field
    delimiter string The string that is used to distinguish one option from another in both the raw options property and the final saved value
    value_delimiter string The string that should be used to distinguish the value for each option from the text to be displayed, where the value is to the left of value_delimiter and the text is to the right. Any options that do not contain the value_delimiter will use the full option as both the text and the value
    count integer The number of options in this checkboxlist
    default_value string The raw and un-parsed default value for this checkboxlist field. Includes all of the values for the options that should be checked by default, separated by the delimiter
    map_to_attribute string If the user is signed into a profile when they submit this form and map_to_attribute is set, the profile attribute specified in map_to_attribute will be set to the value of this field. This should also be used to override the default value if the user is signed into a profile and the specified attribute has already been set
    required boolean Will be true if the user is required to check at least one checkbox in this list
    required_message string The message to display when the user attempts to submit the form without checking any checkboxes in this list
    validators {{ validators }} The list of validators that should be used to validate this form field, if applicable
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    classname string CSS class name(s) to be applied to the field
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for this checkboxlist, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content
    Example Loop a field's items and read its option delimitersselect_field, radio_field, and checkboxlist_field all expose items, options, delimiter, value_delimiter, and count for their option lists; select_field also adds allow_multiple.
    Liquid
    {%- if form_field.object_type == "select_field" or form_field.object_type == "radio_field" or form_field.object_type == "checkboxlist_field" -%}
	<p>{{ form_field.label }} ({{ form_field.count }} option(s), delimited by "{{ form_field.delimiter }}")</p>
	<ul>
	{%- for key in form_field.items -%}
		<li data-value="{{ key }}">{{ form_field.items[key] }}</li>
	{%- endfor -%}
	</ul>
	{%- if form_field.object_type == "select_field" and form_field.allow_multiple -%}
		<p class="hint">This select list allows more than one selection.</p>
	{%- endif -%}
{%- endif -%}

    select_field, radio_field, and checkboxlist_field share items (the parsed option dictionary), options (the raw un-parsed string), delimiter, value_delimiter, and count. items behaves like {{ dictionary }}: iterate it with {% for %} to get each key, then read the matching display text with items[key]. Only select_field adds allow_multiple, since radio and checkboxlist already fix whether zero-or-more or exactly-one option may be chosen by their own shape.

    {{ textarea_field }}

    Should be used to display a textarea field inside a form.

    Properties
    Name Type Description
    object_type string Will always be textarea_field
    is_valid boolean Will always be true
    type string Will always be "textarea"
    placeholder string The placeholder text to display when this textarea does not have a value
    default_value string The text to include in this textarea by default when the form is initially displayed
    map_to_attribute string If the user is signed into a profile when they submit this form and map_to_attribute is set, the profile attribute specified in map_to_attribute will be set to the value of this field. This should also be used to override the default value if the user is signed into a profile and the specified attribute has already been set
    required boolean Will be true if the user is required to enter text in this textarea
    required_message string The message to display when the user attempts to submit the form without entering any text in this textarea
    validators {{ validators }} The list of validators that should be used to validate this textarea, if applicable
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    classname string CSS class name(s) to be applied to the field
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for this textarea field, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content
    Example Read placeholder, default value, and validators for text-like fieldstext_field and textarea_field share placeholder, default_value, and validators; only text_field adds is_numeric.
    Liquid
    {%- if form_field.object_type == "text_field" or form_field.object_type == "textarea_field" -%}
	<label>{{ form_field.label }}</label>
	<input type="{{ form_field.type }}" placeholder="{{ form_field.placeholder }}" value="{{ form_field.default_value }}">
	{%- if form_field.object_type == "text_field" and form_field.is_numeric -%}
		<p class="hint">Numbers only.</p>
	{%- endif -%}
	{%- if form_field.validators.is_valid -%}
		<p class="hint">{{ form_field.validators.validators | size }} rule(s) apply to this field.</p>
	{%- endif -%}
{%- endif -%}

    text_field and textarea_field share placeholder, default_value, and validators, and both set type to their own name ("text" or "textarea"). Only text_field adds is_numeric, a convenience property backed by the field's own validators. validators.is_valid is true only when the list holds one or more validator objects, so this never prints an empty hint for a field with none.

    {{ checkbox_field }}

    Should be used to display a checkbox field inside a form.

    Properties
    Name Type Description
    object_type string Will always be checkbox_field
    is_valid boolean Will always be true
    type string Will always be "checkbox"
    default_value boolean Whether or not the checkbox should be checked by default when the form is displayed
    map_to_attribute string If the user is signed into a profile when they submit this form and map_to_attribute is set, the profile attribute specified in map_to_attribute will be set to "true" or "false". This should also be used to override the default value if the user is signed into a profile and the specified attribute has already been set
    required boolean Will be true if the user is required to check this checkbox before submitting the form
    required_message string The message to display when the user attempts to submit the form without checking this checkbox
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    classname string CSS class name(s) to be applied to the field
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for this field, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content
    Example Read checkbox_field's boolean default and required statecheckbox_field's default_value is a boolean rather than text; required marks whether the box must be checked before the form can submit.
    Liquid
    {%- if form_field.object_type == "checkbox_field" -%}
	<label>
		<input type="checkbox" name="{{ form_field.field_id }}"{% if form_field.default_value %} checked{% endif %}{% if form_field.required %} required{% endif %}>
		{{ form_field.label }}
	</label>
	{%- if form_field.required and form_field.required_message -%}
		<p class="hint">{{ form_field.required_message }}</p>
	{%- endif -%}
{%- endif -%}

    checkbox_field's default_value is a boolean, true or false, unlike the text or delimited defaults on the other typed fields, so it can be used directly to decide whether the box starts checked. required is only true when the visitor must check the box before submitting, and required_message is the message to show when they try to submit without doing so.

    {{ file_field }}

    Should be used to display a file upload field inside a form.

    Properties
    Name Type Description
    object_type string Will always be file_field
    is_valid boolean Will always be true
    type string Will always be "file"
    allow_multiple boolean Whether or not this field may be used to upload multiple files at once
    accept string A string containing the types of files that may be uploaded using this field. Intended to be used directly in the "accept" property of an HTML file input element
    required boolean Will be true if the user is required to upload a file before submitting the form
    required_message string The message to display when the user attempts to submit the form without uploading a file
    validators {{ validators }} The list of validators that should be used to validate this form field, if applicable
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    classname string CSS class name(s) to be applied to the field
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for this file field, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content

    There may be additional restrictions on file uploads that are not specified in the validators, such as max upload filesize. Furthermore, after being uploaded, all files are automatically scanned for malware, although that does not prevent users from uploading malicious files; it only reports the expected security status of the file to administrators

    Example Restrict uploads with file_field's accept and allow_multiplefile_field's accept restricts which file types the browser offers, and allow_multiple controls whether more than one file may be uploaded at once.
    Liquid
    {%- if form_field.object_type == "file_field" -%}
	<label>{{ form_field.label }}</label>
	<input type="file" name="{{ form_field.field_id }}" accept="{{ form_field.accept }}"{% if form_field.allow_multiple %} multiple{% endif %}{% if form_field.required %} required{% endif %}>
{%- endif -%}

    accept is a string meant to be used directly in the HTML input's accept attribute, restricting which file types the browser offers to upload. allow_multiple decides whether the multiple attribute is written, allowing more than one file to be uploaded in this field at once.

    {{ group_field }}

    Should be used to display a group of fields inside a form.

    Properties
    Name Type Description
    object_type string Will always be group_field
    is_valid boolean Will always be true
    type string Will always be "group"
    fields list The list of fields in the group. May include other groups as well
    collapsible boolean Whether or not the group of fields may be collapsed (partially hidden) on the page
    collapsed boolean Whether or not the group of fields should initially be collapsed (partially hidden) when the form is first displayed
    element_id string A helper property containing a unique ID for this group on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the group
    condition {{ condition }} The condition that should be used to show and hide this group
    classname string CSS class name(s) to be applied to the group
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for this group and all of the fields in this group, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content

    Groups may be deeply nested, which templates should be able to handle. Template developers may optionally handle collapsing and expanding groups, although if possible it is recommended to allow it for optimal feature parity with the editor options when editing form fields

    Example Loop a group_field's nested fields and show its collapse stategroup_field's fields property holds the nested form_field list for the group, which may include other groups; collapsible and collapsed control whether it starts partially hidden.
    Liquid
    {%- if form_field.object_type == "group_field" -%}
	<fieldset class="{{ form_field.classname }}"{% if form_field.collapsible and form_field.collapsed %} data-collapsed="true"{% endif %}>
		<legend>{{ form_field.label }}</legend>
		{%- for nested_field in form_field.fields -%}
			<p>{{ nested_field.label }} ({{ nested_field.object_type }})</p>
		{%- endfor -%}
	</fieldset>
{%- endif -%}

    fields is the ordered list of form_field controls nested inside the group, and may itself include other group_field entries, so templates should be prepared to handle nesting. collapsible marks whether the group may be collapsed at all, and collapsed is only meaningful once collapsible is true: it decides whether the group starts partially hidden when the form first displays.

    {{ submit_field }}

    Should be used to display a submit button inside a form.

    Properties
    Name Type Description
    object_type string Will always be submit_field
    is_valid boolean Will always be true
    type string Will always be "submit"
    button_value string Optional. If specified, this should be used as the value for the submit button. This is not typically used, but may be helpful in some edge cases
    text_is_html boolean If true, the template should use the button_html property when displaying the submit button. If false, the template should use the button_text property, which should be propertly escaped since it is not supposed to contain HTML markup
    button_html string The html markup to display inside the submit button. Should be used if the text_is_html property is true
    button_text string The plain text to display inside the submit button. Should be used if the text_is_html property is false
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    classname string CSS class name(s) to be applied to the field
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for the submit button, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content

    Almost every form should have one and only one submit button.

    Example Show a button's text or HTML, plus button_field's extra controlsbutton_field and submit_field share button_text, button_html, and text_is_html; only button_field adds button_type and on_click.
    Liquid
    {%- if form_field.object_type == "button_field" or form_field.object_type == "submit_field" -%}
	<button type="{{ form_field.type }}">
	{%- if form_field.text_is_html -%}
		{{ form_field.button_html }}
	{%- else -%}
		{{ form_field.button_text }}
	{%- endif -%}
	</button>
	{%- if form_field.object_type == "button_field" -%}
		<p class="hint">button_type: {{ form_field.button_type }}{%- if form_field.on_click -%}, has a custom on_click handler{%- endif -%}</p>
	{%- endif -%}
{%- endif -%}

    button_field and submit_field share button_text, button_html, and text_is_html: use button_html when text_is_html is true, otherwise use the pre-escaped button_text. Only button_field adds button_type ("none", "button", "reset", or "submit") and on_click, since submit_field's type is always fixed to "submit" and it should not carry arbitrary javascript.

    {{ button_field }}

    Should be used to display a custom button inside a form.

    Properties
    Name Type Description
    object_type string Will always be button_field
    is_valid boolean Will always be true
    type string Will always be "button"
    button_type string The type of button to display. Will be one of "none", "button", "reset", or "submit"
    button_value string Optional. If specified, this should be used as the value for the button (eg: for submit buttons)
    text_is_html boolean If true, the template should use the button_html property when displaying the button. If false, the template should use the button_text property, which should be propertly escaped since it is not supposed to contain HTML markup
    button_html string The html markup to display inside the button. Should be used if the text_is_html property is true
    button_text string The plain text to display inside the button. Should be used if the text_is_html property is false
    on_click string The custom javascript to execute when this button is clicked. Note that there is no guarantee that the javascript is valid or that any other functions or variables that it may reference have been defined. This functionality should only be used by developers and power users who know what they are doing
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    classname string CSS class name(s) to be applied to the field
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for the button field, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content

    The button field should only be used by power users who know what they are doing, and should always be tested to ensure that it works as anticipated. Most of the time the submit field should be used instead.

    Example Show a button's text or HTML, plus button_field's extra controlsbutton_field and submit_field share button_text, button_html, and text_is_html; only button_field adds button_type and on_click.
    Liquid
    {%- if form_field.object_type == "button_field" or form_field.object_type == "submit_field" -%}
	<button type="{{ form_field.type }}">
	{%- if form_field.text_is_html -%}
		{{ form_field.button_html }}
	{%- else -%}
		{{ form_field.button_text }}
	{%- endif -%}
	</button>
	{%- if form_field.object_type == "button_field" -%}
		<p class="hint">button_type: {{ form_field.button_type }}{%- if form_field.on_click -%}, has a custom on_click handler{%- endif -%}</p>
	{%- endif -%}
{%- endif -%}

    button_field and submit_field share button_text, button_html, and text_is_html: use button_html when text_is_html is true, otherwise use the pre-escaped button_text. Only button_field adds button_type ("none", "button", "reset", or "submit") and on_click, since submit_field's type is always fixed to "submit" and it should not carry arbitrary javascript.

    {{ select_field }}

    Should be used to display a select list inside a form.

    Properties
    Name Type Description
    object_type string Will always be select_field
    is_valid boolean Will always be true
    type string Will always be "select"
    allow_multiple boolean Whether or not to allow users to select more than one option from this select list
    items object A dictionary containing all of the options and their values to be included in the select list, where the keys are the value to be stored and the values are the text to be displayed
    options string The raw and un-parsed options for the select list
    delimiter string The string that is used to distinguish one option from another in both the raw options property and the final saved value
    value_delimiter string The string that should be used to distinguish the value for each option from the text to be displayed, where the value is to the left of value_delimiter and the text is to the right. Any options that do not contain the value_delimiter will use the full option as both the text and the value
    count integer The number of options in this select list
    default_value string The raw and un-parsed default value for this select list. Includes the value of all options that should be selected by default, separated by the delimiter
    map_to_attribute string If the user is signed into a profile when they submit this form and map_to_attribute is set, the profile attribute specified in map_to_attribute will be set to the value of this field. This should also be used to override the default value if the user is signed into a profile and the specified attribute has already been set
    required boolean Will be true if the user is required to select an option in this list
    required_message string The message to display when the user attempts to submit the form without selecting an option in this list
    validators {{ validators }} The list of validators that should be used to validate this form field, if applicable
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    classname string CSS class name(s) to be applied to the field
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for this field, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content
    Example Loop a field's items and read its option delimitersselect_field, radio_field, and checkboxlist_field all expose items, options, delimiter, value_delimiter, and count for their option lists; select_field also adds allow_multiple.
    Liquid
    {%- if form_field.object_type == "select_field" or form_field.object_type == "radio_field" or form_field.object_type == "checkboxlist_field" -%}
	<p>{{ form_field.label }} ({{ form_field.count }} option(s), delimited by "{{ form_field.delimiter }}")</p>
	<ul>
	{%- for key in form_field.items -%}
		<li data-value="{{ key }}">{{ form_field.items[key] }}</li>
	{%- endfor -%}
	</ul>
	{%- if form_field.object_type == "select_field" and form_field.allow_multiple -%}
		<p class="hint">This select list allows more than one selection.</p>
	{%- endif -%}
{%- endif -%}

    select_field, radio_field, and checkboxlist_field share items (the parsed option dictionary), options (the raw un-parsed string), delimiter, value_delimiter, and count. items behaves like {{ dictionary }}: iterate it with {% for %} to get each key, then read the matching display text with items[key]. Only select_field adds allow_multiple, since radio and checkboxlist already fix whether zero-or-more or exactly-one option may be chosen by their own shape.

    {{ radio_field }}

    Should be used to display a radio field inside a form.

    Properties
    Name Type Description
    object_type string Will always be radio_field
    is_valid boolean Will always be true
    type string Will always be "radio"
    items object A dictionary containing all of the options and their values to be included in the template, where the keys are the value to be stored and the values are the text to be displayed
    options string The raw and un-parsed options for the radio field
    delimiter string The string that is used to distinguish one option from another in the raw options property
    value_delimiter string The string that should be used to distinguish the value for each option from the text to be displayed, where the value is to the left of value_delimiter and the text is to the right. Any options that do not contain the value_delimiter will use the full option as both the text and the value
    count integer The number of options in this radio field
    default_value string The value of the radio option that should be selected by default when this form is displayed
    map_to_attribute string If the user is signed into a profile when they submit this form and map_to_attribute is set, the profile attribute specified in map_to_attribute will be set to the value of this field. This should also be used to override the default value if the user is signed into a profile and the specified attribute has already been set
    required boolean Will be true if the user is required to select one of the radio options
    required_message string The message to display when the user attempts to submit the form without selecting a radio option
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    classname string CSS class name(s) to be applied to the field
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for this radio field, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content
    Example Loop a field's items and read its option delimitersselect_field, radio_field, and checkboxlist_field all expose items, options, delimiter, value_delimiter, and count for their option lists; select_field also adds allow_multiple.
    Liquid
    {%- if form_field.object_type == "select_field" or form_field.object_type == "radio_field" or form_field.object_type == "checkboxlist_field" -%}
	<p>{{ form_field.label }} ({{ form_field.count }} option(s), delimited by "{{ form_field.delimiter }}")</p>
	<ul>
	{%- for key in form_field.items -%}
		<li data-value="{{ key }}">{{ form_field.items[key] }}</li>
	{%- endfor -%}
	</ul>
	{%- if form_field.object_type == "select_field" and form_field.allow_multiple -%}
		<p class="hint">This select list allows more than one selection.</p>
	{%- endif -%}
{%- endif -%}

    select_field, radio_field, and checkboxlist_field share items (the parsed option dictionary), options (the raw un-parsed string), delimiter, value_delimiter, and count. items behaves like {{ dictionary }}: iterate it with {% for %} to get each key, then read the matching display text with items[key]. Only select_field adds allow_multiple, since radio and checkboxlist already fix whether zero-or-more or exactly-one option may be chosen by their own shape.

    {{ label_field }}

    Should be used to display a text label inside a form.

    Properties
    Name Type Description
    object_type string Will always be label_field
    is_valid boolean Will always be true
    type string Will always be "label"
    element_id string A helper property containing a unique ID for this label on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the label. Not typically used for label fields, although the developer may specify an alternate use for this or may customize the output using this
    condition {{ condition }} The condition that should be used to show and hide this label
    classname string CSS class name(s) to be applied to the label
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for this label, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content

    How the label is displayed in the form is entirely up to the template developer as there is currently no way for editors to specify the styling to use when displaying labels

    Example Print label_field's text and classnamelabel_field only carries display text and an optional condition; it has no value of its own to submit.
    Liquid
    {%- if form_field.object_type == "label_field" -%}
	<p class="{{ form_field.classname }}">{{ form_field.label }}</p>
{%- endif -%}

    label_field only carries a label and an optional condition to show or hide it. Unlike the other typed fields on this page, it has no value to submit and no required or validators properties, since it is decorative text rather than an input.

    {{ captcha_field }}

    Should be used to display a captcha inside a form.

    Properties
    Name Type Description
    object_type string Will always be captcha_field
    is_valid boolean Will always be true
    type string Will always be "captcha"
    theme string "light" or "dark"
    captcha_size string "compact" or "normal"
    google_recaptcha_site_key string The public Google ReCaptcha site key, which is required for the captcha to work
    required boolean Will always be true
    required_message string The message to display when the user attempts to submit the form without passing the catpcha
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    classname string CSS class name(s) to be applied to the field
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for the captcha field, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content

    Captcha fields are recommended in order to prevent bots from spamming forms, although each form may only have a single catpcha field. Additionally, it is not recommended for the captcha field to be conditional, as that would defeat its purpose.

    Example Read captcha_field's theme, size, and site keycaptcha_field's theme, captcha_size, and google_recaptcha_site_key configure a Google reCAPTCHA widget.
    Liquid
    {%- if form_field.object_type == "captcha_field" -%}
	<div class="g-recaptcha" data-sitekey="{{ form_field.google_recaptcha_site_key }}" data-theme="{{ form_field.theme }}" data-size="{{ form_field.captcha_size }}"></div>
{%- endif -%}

    captcha_field's theme is "light" or "dark" and captcha_size is "compact" or "normal"; both map directly to the Google reCAPTCHA widget's own data attributes. google_recaptcha_site_key is the public site key required for the captcha to render.

    {{ text_field }}

    Should be used to display a text field inside a form.

    Properties
    Name Type Description
    object_type string Will always be text_field
    is_valid boolean Will always be true
    type string Will always be "text"
    is_numeric boolean Will be true if the field should only be used to enter numbers, which may only include integers or may include decimals as well. This is a convenience property which uses the validators to check if the field validates for numeric or decimal values
    placeholder string The placeholder text to display when this field does not have a value
    default_value string The text to include in this field by default when the form is initially displayed
    map_to_attribute string If the user is signed into a profile when they submit this form and map_to_attribute is set, the profile attribute specified in map_to_attribute will be set to the value of this field. This should also be used to override the default value if the user is signed into a profile and the specified attribute has already been set
    required boolean Will be true if the user is required to enter text in this field
    required_message string The message to display when the user attempts to submit the form without entering any text in this field
    validators {{ validators }} The list of validators that should be used to validate this text field, if applicable
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    classname string CSS class name(s) to be applied to the field
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for this field, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content

    The text field may also be used to display number inputs, although there are not number-specific properties (eg: increment) so it is currently up to the template developer's discretion how they want to display number inputs

    Example Read placeholder, default value, and validators for text-like fieldstext_field and textarea_field share placeholder, default_value, and validators; only text_field adds is_numeric.
    Liquid
    {%- if form_field.object_type == "text_field" or form_field.object_type == "textarea_field" -%}
	<label>{{ form_field.label }}</label>
	<input type="{{ form_field.type }}" placeholder="{{ form_field.placeholder }}" value="{{ form_field.default_value }}">
	{%- if form_field.object_type == "text_field" and form_field.is_numeric -%}
		<p class="hint">Numbers only.</p>
	{%- endif -%}
	{%- if form_field.validators.is_valid -%}
		<p class="hint">{{ form_field.validators.validators | size }} rule(s) apply to this field.</p>
	{%- endif -%}
{%- endif -%}

    text_field and textarea_field share placeholder, default_value, and validators, and both set type to their own name ("text" or "textarea"). Only text_field adds is_numeric, a convenience property backed by the field's own validators. validators.is_valid is true only when the list holds one or more validator objects, so this never prints an empty hint for a field with none.

    {{ date_field }}

    Should be used to display a date field inside a form.

    Properties
    Name Type Description
    object_type string Will always be date_field
    is_valid boolean Will always be true
    type string Will always be "date"
    default_value {{ time }} Optional. The default value to use for this date field when the form is displayed. Will be null if there is no default value
    map_to_attribute string If the user is signed into a profile when they submit this form and map_to_attribute is set, the profile attribute specified in map_to_attribute will be set to the value of this field. This should also be used to override the default value if the user is signed into a profile and the specified attribute has already been set
    required boolean Will be true if the user is required to enter a date before submitting the form
    required_message string The message to display when the user attempts to submit the form without entering a date
    validators {{ validators }} The list of validators that should be used to validate this date field, if applicable
    element_id string A helper property containing a unique ID for this field on this instance of this form. This value should be different every time the form is output
    subtext {{ text }} Help or hint text to display together with the field
    condition {{ condition }} The condition that should be used to show and hide this form field
    classname string CSS class name(s) to be applied to the field
    field_id string The identifier for this field
    label string The label for this field
    output string Default HTML markup for this date field, which makes a number of assumptions about other elements on the page that may or may not be included. Developers should avoid using the default output in order to guarantee that forms work as expected, including styling, validation, conditionals, and more. May include additional markup in the editor preview to make it easier to edit content
    Example Show date_field's default value only when one is setdate_field's default_value is optional and returns null when unset, so guard before printing it as the input's value.
    Liquid
    {%- if form_field.object_type == "date_field" -%}
	<label>{{ form_field.label }}</label>
	<input type="date" name="{{ form_field.field_id }}"{% if form_field.default_value %} value="{{ form_field.default_value }}"{% endif %}{% if form_field.required %} required{% endif %}>
	{%- if form_field.required -%}
		<p class="hint">{{ form_field.required_message }}</p>
	{%- endif -%}
{%- endif -%}

    date_field's default_value is optional and is null when the field has no default, so the value attribute is only written when one is present. required and required_message work the same way as on the other typed fields that validate before submit.