Reference: Form Field Index

Common Field Attributes

Every field accepts a list of attributes you can use. Each field could share these common attributes, but particular fields might ignore them. The best way to check which attributes are allowed on a field is to check the field description in this page and see which attributes are mentioned.

This list provides a common ground so there's no need to repeat the description of a common field.

Attribute Description
autocomplete Accepts on or off
autofocus if enabled, autofocus on that field
classes accepts a string with one or more CSS classes to add
default sets the field default value
disabled sets the field disabled state
help Adds a tooltip to the field
id sets the field id. Also sets the for attribute on the label
label sets the field label
display_label Accepts true or false
name sets the field name
novalidate sets the field novalidate state
outerclasses Classes added to the div that includes the label and the field
placeholder sets the field placeholder value
readonly sets the field readonly state
size sets the field size, which in turn adds a class to its container. Valid values are large, x-small, medium, long, small. You can ofcourse add more in the template you see, when used in the frontend
style sets the field style
title sets the field title value
type sets the field type
validate.required if set to a positive value, sets the field as required.
validate.pattern sets a validation pattern
validate.message sets the message shown if the validation fails

NOTE: You can set positive values in multiple ways: 'on', true, 1. Other values are interpreted as negative.


Available Fields

Captcha Field

The captcha field type is used to add a Google reCAPTCHA element to your form. Unlike other elements, it can only be used once in a form.

You should configure your Google reCAPTCHA configurations in the reCAPTCHA Admin Console

As of version 3.0, the field supports 3 variations of reCAPTCHA. The overall configuration of reCAPTCHA is best set in your global form configuration file (typically user/config/plugins/form.yaml). The default options are:

recaptcha:
  version: 2-checkbox
  theme: light
  site_key:
  secret_key:

These options should be set based on the following:

Key Values
version Defaults to 2-checkbox, but can also be 2-invisible or 3
theme Defaults to light, but can also be dark (currently only works for version 2-x versions)
site_key Your Google Site Key
secret_key Your Google Secret Key

Please ensure the domain of the site is listed in Google's reCAPTCHA configuration

In the form definition, the name attribute of the captcha field must be g-recaptcha-response. The reason is that Google reCAPTCHA stores the Captcha confirmation code in a field named g-recaptcha-response.

Example:

g-recaptcha-response:
  type: captcha
  label: Captcha

You can also provide a custom failure recaptcha_not_validated message, but if you don't the default one is provided by the Form plugin. If you want to set a form-specific recaptcha_site_key rather than setting it globally in the form configuration, you can set that also.

g-recaptcha-response:
  type: captcha
  label: Captcha 
  recaptcha_site_key: ENTER_YOUR_CAPTCHA_PUBLIC_KEY 
  recaptcha_not_validated: 'Captcha not valid!'
Attribute Description
recaptcha_site_key The Google reCAPTCHA Site Key (optional)
recaptcha_not_validated The message to show if the captcha is not valid
Common Attributes Allowed
help
label
name
outerclasses
validate.required
Server-side Captcha validation

The above code will validate the Captcha in the frontend and prevent form submission if not correct. To also validate the captcha server-side, add the captcha process action to your forms:

process:
    captcha: true

You can also provide an optional success message, but if you don't no specific message will be displayed on success. If you want to set a form-specific recaptcha_secret rather than setting it globally in the form configuration, you can set that also.

process:
    captcha:
      recaptcha_secret: ENTER_YOUR_CAPTCHA_SECRET_KEY
      message: 'Successfully passed reCAPTCHA!'

See the Contact Form example to see it in action.


Checkbox Field

Checkbox Field

The checkbox field type is used to add a single checkbox to your form.

Example:

agree_to_terms:
  type: checkbox
  label: "Agree to the terms and conditions"
  validate:
      required: true

Checkboxes Field

Checkboxes Field

The checkboxes field type is used to add a group of checkboxes to your form.

Examples:

pages.process:
    type: checkboxes
    label: PLUGIN_ADMIN.PROCESS
    help: PLUGIN_ADMIN.PROCESS_HELP
    default:
        markdown: true
        twig: true
    options:
        markdown: Markdown
        twig: Twig
    use: keys
my_field:
    type: checkboxes
    label: A couple of checkboxes
    default:
        option1: true
        option2: true
    options:
        option1: Option 1
        option2: Option 2
Attribute Description
use When set to keys, the checkbox will store the value of the element key when the form is submitted. Otherwise, it will use the element value.
options An array of key-value options that will be allowed.

Conditional Field

The conditional field type is used to conditionally display some other fields base on a condition.

Examples:

If your conditional already returns a true or false then you can simply use this simplified format:

header.field_condition:
  type: conditional
  condition: config.plugins.yourplugin.enabled
  fields: # The field(s) below will be displayed only if the plugin named yourplugin is enabled
    header.mytextfield:
    type: text
    label: A text field

However, if you require more complex conditions, you can perform some logic that returns 'true' or 'false' as strings, and the field will understand that too.

header.field_condition:
  type: conditional
  condition: "config.plugins.yourplugin.enabled ? 'true' : 'false'"
  fields: # The field(s) below will be displayed only if the plugin named yourplugin is enabled
    header.mytextfield:
    type: text
    label: A text field
Attribute Description
condition The condition evaluated by twig. Any variable accessible by twig can be evaluated
Common Attributes Allowed
disabled
id
label
name

Date Field

Date Field

The date field type is used to add an HTML5 date input field.

Example:

-
  type: date
  label: Enter a date
  validate.min: "2014-01-01"
  validate.max: "2018-12-31"
Attribute Description
validate.min Sets the min attribute of the field (see http://html5doctor.com/the-woes-of-date-input/#feature-min-max-attributes)
validate.max Sets the max attribute of the field (see http://html5doctor.com/the-woes-of-date-input/#feature-min-max-attributes)

Display Field

Display Field

The display field type is used to show some text or instructions inside the form. Can accept markdown content

Example:

test:
    type: display
    size: large
    label: Instructions
    markdown: true
    content: "This is a test of **bold** and _italic_ in a text/display field\n\nanother paragraph...."
Attribute Description
markdown boolean value that enables markdown processing on the content field
content the textual content to show
Common Attributes Allowed
help
id
label
name
id
outerclasses
size
style

Email Field

Email Field

The email field type is used to present a text input field that accepts an email, using the email HTML5 input.

Example:

header.email:
  type: email
  autofocus: true
  label: Email

File Field

With the file field type, you can let users upload files through the form. The field by default allows one file only, of type image and will get uploaded to the current page where the form has been declared.

# Default settings
my_files:
  type: file
  multiple: false
  destination: '@self'
  accept:
    - image/*
Attribute Description
multiple Can be true or false, when set to true, multiple files can be selected at the same time
destination Can be either @self, @page:/route or local/rel/path/.
Set to @self, the files will be uploaded where the form has been declared (current .md).
Using @page:/route will upload to the specified route of a page, if exists (e.g., @page:/blog/a-blog-post).
Set to 'local/rel/path': Can be any path relative to the Grav instance. For instance, user/data/files. If the path doesn't exist, it will get created, so make sure it is writable.
accept Takes an array of MIME types that are allowed. For instance to allow only gifs and mp4 files: accept: ['image/gif', 'video/mp4']

The File field in the admin is a bit different, allowing also to delete a file uploaded to a form, because the use-case in admin is to upload and then associate a file to a field.

Common Attributes Allowed
help
label
name
outerclasses
validate.required

By default, in Admin the file field will overwrite an uploaded file that has the same name of a newer one, contained in the same folder you want to upload it, unless you set avoid_overwriting to true in the field definition.


Hidden Field

The hidden field type is used to add a hidden element to a form.

Example:

header.some_field:
  type: hidden
  default: my-value
Attribute Description
name The field name. If missing, the field name is got from the field definition element (in the example above: header.some_field)
Common Attributes Allowed
default

Honeypot Field

The honeypot field type creates a hidden field that, when filled out, will return with an error. This is a useful way to prevent bots from filling out and submitting a form.

Example:

fields:
    honeypot:
      type: honeypot

This is a simple text field which does not appear on the front end. Bots, which detect fields in the code and fill them out automatically, will likely fill the field out. The error prevents that form from being properly submitted. The error comes back next to the form element, rather than on the top in a message block.

A honeypot field is a popular alternative to captcha fields.


Ignore Field

The ignore field type can be used to remove unused fields when extending from another blueprint

Example:

header.process:
  type: ignore
content:
  type: ignore

Password Field

The password field type is used to present a password text input field.

Example:

password:
  type: password
  label: Password

Radio Field

Radio Field

The radio field type is used to present a set of radio fields

Example:

my_choice:
  type: radio
  label: Choice
  default: markdown
  options:
      markdown: Markdown
      twig: Twig
Attribute Description
options An array of key-value options that will be allowed.

Range Field

Range Field

The range field is used to present a range input field.

Example:

header.choose_a_number_in_range:
  type: range
  label: Choose a number
  validate:
    min: 1
    max: 10

Select Field

Select Field

The select field type is used to present a select field.

Example:

pages.order.by:
    type: select
    size: long
    classes: fancy
    label: PLUGIN_ADMIN.DEFAULT_ORDERING
    help: PLUGIN_ADMIN.DEFAULT_ORDERING_HELP
    options:
        default: PLUGIN_ADMIN.DEFAULT_ORDERING_DEFAULT
        folder: PLUGIN_ADMIN.DEFAULT_ORDERING_FOLDER
        title: PLUGIN_ADMIN.DEFAULT_ORDERING_TITLE
        date: PLUGIN_ADMIN.DEFAULT_ORDERING_DATE
Attribute Description
options An array of key-value options that will be allowed.
multiple Allow the form to accept multiple values.

Select Optgroup Field

Select Optgroup Field

The select_optgroup field type is used to present a select field with groupings.

Example:

header.newField:
    type: select_optgroup
    label: Test Optgroup Select Field
    options:
      - OptGroup1:
        - Option1
        - Option2
      - OptGroup2:
        - Option3
        - Option4
Attribute Description
options An array of key-value options that will be allowed.
multiple Allow the form to accept multiple values.

Spacer Field

The spacer field type is used to add some text, a headline or a hr tag

Example:

test:
    type: spacer
    title: A title
    text: Some text
    underline: true
Attribute Description
title add a h3 title to the form
text Add some text. If title is set, add it after the title
underline boolean, add a <hr> tag if positive

Tabs / Tab Fields

Tabs

The tabs and tab field types are used to divide the contained form fields in tabs.

Example:

tabs:
  type: tabs
  active: 1

  fields:
    content:
      type: tab
      title: PLUGIN_ADMIN.CONTENT

      fields:

        # .... other subfields

    options:
      type: tab
      title: PLUGIN_ADMIN.OPTIONS

      fields:

        # .... other subfields
Attribute Description
active The active tab number

Text Field

Text Field

The text field is used to present a text input field.

Example:

header.title:
  type: text
  autofocus: true
  label: PLUGIN_ADMIN.TITLE
Attribute Description
prepend prepend some text or HTML to the front of a field
append append some text or HTML to the end of a field

Textarea Field

Textarea Field

The textarea field is used to present a textarea input field.

Example:

header.content:
  type: textarea
  autofocus: true
  label: PLUGIN_ADMIN.CONTENT
Attribute Description
rows Add a rows attribute with the value associated with this property
cols Add a cols attribute with the value associated with this property
Common Attributes Allowed
autofocus
classes
default
disabled
help
id
label
name
novalidate
outerclasses
readonly
size
style
title
validate.required
validate.pattern
validate.message

Toggle Field

Toggle Field

The toggle field type is an on/off kind of input, with configurable labels.

Example:

summary.enabled:
    type: toggle
    label: PLUGIN_ADMIN.ENABLED
    highlight: 1
    help: PLUGIN_ADMIN.ENABLED_HELP
    options:
        1: PLUGIN_ADMIN.YES
        0: PLUGIN_ADMIN.NO
    validate:
        type: bool
Attribute Description
highlight The key of the option to highlight (set green when selected)
options The list of key-value options
Common Attributes Allowed
default
help
label
name
style
toggleable
validate.required
validate.type
disabled

Currently Undocumented Fields

Field Description
Array
Avatar
Color
Columns
Column
Datetime
Fieldset
Formname
Key
Month
Number
Signature
Switch
Tel
Time
Unique Id
Url
Value
Week

Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to make your changes.