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.

To add custom attributes, you can use:

attributes:
  key: value

To add custom data-* values, you can use:

datasets:
  key: value

The above shown attributes and datasets definitions lead to the following field definition:

<input name="data[name]" value="" type="text" class="form-input " key="value" data-key="value">

Available Fields

Basic-Captcha Field

Added in Forms 7.0.0 as an local alternative to the Google ReCaptcha field. This field is particularly handy when dealing with SPAM in contact forms when you don't want to deal with the hassle or perhaps GPDR restrictions that come with Google's offering. It uses OCR-resistant fonts to deter attacks, and can be configured with codes to be copied, or simple math questions.

The basic-captcha field type is fully configurable both globally and per-field. Global configuration is set in your form configuration file (typically user/config/plugins/form.yaml), while field-level configuration allows you to customize individual captcha fields in your forms.

Global Configuration

The default global options are:

 1basic_captcha:
 2  type: characters            # options: [characters | math | dotcount | position]
 3  debug: false                # enable debug logging
 4  image:
 5    width: 135                # default image width (for math/dotcount/position types)
 6    height: 40                # default image height (for math/dotcount/position types)
 7    bg: '#ffffff'             # default background color
 8  chars:
 9    length: 6                 # number of chars to output
10    font: zxx-xed.ttf         # options: [zxx-xed.ttf | zxx-sans.ttf | zxx-camo.ttf | zxx-noise.ttf]
11    size: 24                  # font size in px
12    box_width: 200            # image width for character captchas (overrides image.width)
13    box_height: 70            # image height for character captchas (overrides image.height)
14    start_x: 10               # start position in x direction in px
15    start_y: 40               # start position in y direction in px
16    bg: '#ffffff'             # background color for character captchas
17    text: '#000000'           # text color (hex format)
18  math:
19    min: 1                    # smallest digit
20    max: 12                   # largest digit
21    operators: ['+','-','*']  # operators that can be used in math

Field-Level Configuration

As of Forms 7.1.0, you can override the global configuration on a per-field basis. This allows different forms to have different captcha styles, fonts, colors, and types.

Simple Example:

 1basic-captcha:
 2    type: basic-captcha
 3    placeholder: enter the characters
 4    label: Are you human?

Advanced Example with Field-Level Configuration:

 1basic-captcha:
 2    type: basic-captcha
 3    placeholder: enter the characters
 4    label: Are you human?
 5    # Field-level configuration overrides global defaults
 6    captcha_type: characters        # use 'captcha_type' not 'type'
 7    chars:
 8        font: zxx-sans.ttf          # cleaner font
 9        size: 32                    # larger text
10        length: 6                   # 6 characters
11        box_width: 200              # wider image
12        box_height: 70              # taller image
13        bg: '#f0f8ff'               # light blue background
14        text: '#0066cc'             # dark blue text
15        start_x: 20                 # custom X position
16        start_y: 50                 # custom Y position

Math Captcha Example:

 1basic-captcha:
 2    type: basic-captcha
 3    placeholder: enter the answer
 4    label: Solve this math problem
 5    captcha_type: math              # math problem instead of characters
 6    math:
 7        min: 1                      # use small numbers
 8        max: 10
 9        operators: ['+','-']        # only addition and subtraction

Available Captcha Types

When using field-level configuration, set the captcha type with captcha_type:

• characters - Random character string (default)
• math - Simple math problem (e.g., "3 + 5 = ?")
• dotcount - Count dots of a specific color
• position - Identify position of a symbol

Available Fonts

The Basic-Captcha field includes four OCR-resistant fonts:

• zxx-xed.ttf - Default, balanced readability and security
• zxx-sans.ttf - Clean sans-serif, easier to read
• zxx-camo.ttf - Camouflage style, more challenging
• zxx-noise.ttf - Noisy style, highest security

Configuration Options Reference

Form Processing

This also requires a matching process: element to ensure the form is validated properly.

Example:

 1process:
 2    basic-captcha:
 3        message: Humanity verification failed, please try again...

Turnstile Captcha Field (Cloudflare)

As of Form v7.1.0, Grav adds support for the new Cloudflare Turnstile field. This field is a new way to prevent SPAM in forms, and is a great alternative to the Google ReCaptcha field and GPDR restrictions that come with Google's offering. This field is particularly handy when dealing with SPAM in contact forms. Learn more about Turnstile.

Advantages over Google ReCaptcha

1. GDPR compliant and user-privacy focused
2. Extremely fast challenge verification
3. Very simple to implement both in Cloudflare and Grav, no complex UIs or parameters to configure
4. No fancy workarounds for asynchronous form submissions (ajax), it just works!
5. Exceptional user experience compared to ReCaptcha, no more counting cars, traffic lights, or other nonsense
6. Built on top of machine learning, it will get better over-time and adapt to new attack vectors
7. Exhaustive analytics on the effectiveness of the challenge, see screenshot

Integration

Before integrating Grav Forms with Turnstile, you must first create a new Turnstile site, you can also follow the official "get started" tutorial. Here you can also choose the type of widget you want to use, it can be either managed, non-interactive or invisible. It is important to note that you can only change the type of widget from Cloudflare, you won't be able to configure this via Grav. However, if not happy with one choice, you will be able to change it later if you need to. Learn more about the different widget types.

Once you have created a site, you will be given a site_key and site_secret that you will need to configure in your form configuration file (typically user/config/plugins/form.yaml). You can ignore the script tag suggested, as Grav takes care of it for you.

The default options are:

 1turnstile:
 2  theme: light
 3  site_key: <Your Turnstile Site Key>
 4  secret_key: <Your Turnstile Secret Key>

Finally, you will also requires a matching process: element to ensure the form is validated properly.

Example

A typical example for a contact form would look like the following.

 1form:
 2  name: contact
 3  fields:
 4    name:
 5      label: Name
 6      type: text
 7      validate:
 8        required: true
 9    email:
10      label: Email
11      type: email
12      validate:
13        required: true
14    message:
15      label: Message
16      type: textarea
17      validate:
18        required: true
19    captcha:
20        type: turnstile
21        theme: light
22  buttons:
23    submit:
24      type: submit
25      value: Submit
26  process:
27    turnstile: true
28    email:
29      subject: "[Acme] {{ form.value.name|e }}"
30      reply_to: "{{ form.value.name|e }} <{{ form.value.email }}>"
31    message: Thanks for contacting us!
32    reset: true
33    display: '/'

Google Captcha Field (ReCaptcha)

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.

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:

 1recaptcha:
 2  version: 2-checkbox
 3  theme: light
 4  site_key:
 5  secret_key:

These options should be set based on the following:

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:

 1g-recaptcha-response:
 2  type: captcha
 3  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.

 1g-recaptcha-response:
 2  type: captcha
 3  label: Captcha
 4  recaptcha_site_key: ENTER_YOUR_CAPTCHA_PUBLIC_KEY
 5  recaptcha_not_validated: 'Captcha not valid!'

This also requires a matching process: element to ensure the form is validated properly.

Example:

 1process:
 2    captcha: true

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:

 1process:
 2  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.

 1process:
 2  captcha:
 3    recaptcha_secret: ENTER_YOUR_CAPTCHA_SECRET_KEY
 4    message: 'Successfully passed reCAPTCHA!'

See the Contact Form example to see it in action.

Checkbox Field

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

Example:

 1agree_to_terms:
 2  type: checkbox
 3  label: "Agree to the terms and conditions"
 4  validate:
 5      required: true

Checkboxes Field

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

Examples:

 1pages.process:
 2    type: checkboxes
 3    label: PLUGIN_ADMIN.PROCESS
 4    help: PLUGIN_ADMIN.PROCESS_HELP
 5    default:
 6        markdown: true
 7        twig: true
 8    options:
 9        markdown: Markdown
10        twig: Twig
11    use: keys

 1my_field:
 2    type: checkboxes
 3    label: A couple of checkboxes with help for each option and option1 disabled
 4    default:
 5        - option1
 6        - option2
 7    options:
 8        option1: Option 1
 9        option2: Option 2
10    help_options:
11        option1: Help for Option 1
12        option2: Help for Option 2
13    disabled_options:
14        - option1

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:

 1my_conditional:
 2  type: conditional
 3  condition: config.plugins.yourplugin.enabled
 4  fields: # The field(s) below will be displayed only if the plugin named yourplugin is enabled
 5    header.mytextfield:
 6      type: text
 7      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.

 1my_conditional:
 2  type: conditional
 3  condition: "config.site.something == 'custom'"
 4  fields: # The field(s) below will be displayed only if the `site` configuration option `something` equals `custom`
 5    header.mytextfield:
 6        type: text
 7        label: A text field

Date Field

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

Example:

 1-
 2  type: date
 3  label: Enter a date
 4  validate.min: "2014-01-01"
 5  validate.max: "2018-12-31"

Display Field

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

Example:

 1test:
 2    type: display
 3    size: large
 4    label: Instructions
 5    markdown: true
 6    content: "This is a test of **bold** and _italic_ in a text/display field\n\nanother paragraph...."

Email Field

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

Example:

 1header.email:
 2  type: email
 3  autofocus: true
 4  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.

 1# Default settings
 2my_files:
 3  type: file
 4  multiple: false
 5  destination: 'self@'
 6  accept:
 7    - image/*

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.

FilePond Field

Added in Forms 7.0.0, the filepond field type is a modern alternative to the File field, powered by the FilePond JavaScript library. It provides a superior user experience with drag-and-drop uploads, image previews, built-in image editing (crop, resize, rotate), and smooth animations.

When to use FilePond:

• Image-heavy forms requiring preview and editing capabilities
• Modern user interfaces with drag-and-drop functionality
• Forms requiring client-side image optimization before upload
• Projects prioritizing user experience over legacy browser support

When to use File field (Dropzone):

• General file uploads (non-image files)
• Simpler implementation without image editing needs
• Legacy browser compatibility requirements

Basic Usage

 1my_images:
 2    type: filepond
 3    label: Upload Images
 4    destination: user/media/uploads
 5    multiple: true
 6    limit: 5
 7    filesize: 10
 8    accept:
 9        - image/*

Configuration Options

Image Transform & Resize Options

FilePond includes powerful image processing capabilities through the filepond configuration key:

 1my_images:
 2    type: filepond
 3    label: Upload and Edit Images
 4    destination: user/media/uploads
 5    multiple: true
 6    filesize: 10
 7    accept:
 8        - image/jpeg
 9        - image/png
10        - image/webp
11    filepond:
12        # Output Format
13        allowImageTransform: true
14        imageTransformOutputMimeType: 'image/jpeg'
15        imageTransformOutputQuality: 85
16        imageTransformOutputStripImageHead: true
17
18        # Resize Settings
19        allowImageResize: true
20        imageResizeTargetWidth: 1024
21        imageResizeTargetHeight: 768
22        imageResizeMode: 'contain'
23        imageResizeUpscale: false
24
25        # Crop Settings
26        allowImageCrop: true
27        imageCropAspectRatio: '16:9'
28
29        # Preview Settings
30        allowImagePreview: true
31        imagePreviewHeight: 256
32
33        # UI Customization
34        stylePanelLayout: 'compact'
35        labelIdle: '<span class="filepond--label-action">Browse</span> or drop images'

FilePond-Specific Options Reference

Complete Form Example

 1---
 2title: 'Photo Upload Form'
 3form:
 4    id: photo-upload
 5    xhr_submit: true
 6    fields:
 7        photos:
 8            type: filepond
 9            label: Upload Your Photos
10            help: Upload up to 5 photos. They will be automatically resized to 1920x1080.
11            destination: user/media/galleries
12            multiple: true
13            limit: 5
14            filesize: 15
15            accept:
16                - image/jpeg
17                - image/png
18                - image/webp
19            validate:
20                required: true
21            filepond:
22                # Optimize images for web
23                imageTransformOutputMimeType: 'image/jpeg'
24                imageTransformOutputQuality: 85
25                imageTransformOutputStripImageHead: true
26
27                # Resize to HD
28                allowImageResize: true
29                imageResizeTargetWidth: 1920
30                imageResizeTargetHeight: 1080
31                imageResizeMode: 'contain'
32
33                # Force 16:9 crop
34                allowImageCrop: true
35                imageCropAspectRatio: '16:9'
36
37                # Custom label
38                labelIdle: '<span class="filepond--label-action">Click to browse</span> or drag photos here'
39
40    buttons:
41        submit:
42            type: submit
43            value: Upload Photos
44
45    process:
46        upload: true
47        message: 'Thank you! Your photos have been uploaded successfully.'
48        reset: true
49---
50
51# Photo Gallery Upload
52
53Upload your photos and they will be automatically optimized and resized.

Form Processing

The FilePond field requires the upload process action to save uploaded files:

 1process:
 2    upload: true
 3    message: 'Files uploaded successfully!'

Files are processed via AJAX and saved to the specified destination folder. Image transformations (resize, crop, format conversion) happen in the browser before upload, reducing server load and upload time.

XHR Form Integration

FilePond works seamlessly with AJAX form submissions (xhr_submit: true). The field automatically:

• Prevents form submission while files are uploading
• Reinitializes after form updates
• Preserves uploaded files during validation errors
• Cleans up temporary files on successful submission

Features Summary

✅ Modern drag-and-drop interface - Smooth animations and visual feedback ✅ Image preview - See images before upload with zoom and pan ✅ Built-in image editing - Crop, resize, rotate images in the browser ✅ Client-side optimization - Reduce file size before upload ✅ Format conversion - Convert images to JPEG/PNG/WebP ✅ Real-time validation - File type and size validation with instant feedback ✅ Progress indication - Upload progress bars for each file ✅ Multiple file support - Upload several files with one field ✅ Responsive design - Works on desktop, tablet, and mobile devices ✅ Accessibility - Keyboard navigation and screen reader support

Comparison with File Field

Hidden Field

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

Example:

 1header.some_field:
 2  type: hidden
 3  default: my-value

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:

 1fields:
 2    honeypot:
 3      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:

 1header.process:
 2  type: ignore
 3content:
 4  type: ignore

Number Field

The number field type is used to present a text input field that accepts numbers only, using the number HTML5 input.

Example:

 1header.count:
 2  type: number
 3  label: 'How Much?'
 4  validate:
 5    min: 10
 6    max: 360
 7    step: 10

Password Field

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

Example:

 1password:
 2  type: password
 3  label: Password

Radio Field

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

Example:

 1my_choice:
 2  type: radio
 3  label: Choice
 4  default: markdown
 5  options:
 6      markdown: Markdown
 7      twig: Twig

Range Field

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

Example:

 1header.choose_a_number_in_range:
 2  type: range
 3  label: Choose a number
 4  validate:
 5    min: 1
 6    max: 10

Section Field

The Section field type is used to divide a setting page into sections.

Example:

 1content:
 2    type: section
 3    title: PLUGIN_ADMIN.DEFAULTS
 4    underline: true
 5
 6    fields:
 7
 8        #..... subfields

Select Field

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

Example 1:

 1pages.order.by:
 2    type: select
 3    size: long
 4    classes: fancy
 5    label: 'Default Ordering'
 6    help: 'Pages in a list will render using this order unless it is overridden'
 7    options:
 8        default: 'Default - based on folder name'
 9        folder: 'Folder - based on prefix-less folder name'
10        title: 'Title - based on title field in header'
11        date: 'Date - based on date field in header'

Example 2 - Disabling Individual Options:

 1my_element:
 2    type: select
 3    size: long
 4    classes: fancy
 5    label: 'My Select Element'
 6    help: 'Use the disabled key:value to display but disable a particular option'
 7    options:
 8        option1:
 9          value: 'Option 1'
10        option2:
11          value: 'Option 2'
12        option3:
13          disabled: true
14          value: 'Option 3'

If you set multiple to true, you need to add

pages.order.by:
  validate:
    type: array

Otherwise the array of selected values will not be saved correctly.

Select Optgroup Field

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

Example:

 1header.newField:
 2    type: select_optgroup
 3    label: Test Optgroup Select Field
 4    options:
 5      - OptGroup1:
 6        - Option1
 7        - Option2
 8      - OptGroup2:
 9        - Option3
10        - Option4

Spacer Field

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

Example:

 1test:
 2    type: spacer
 3    title: A title
 4    title_type: h2
 5    text: Some text
 6    underline: true

Tabs / Tab Fields

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

Example:

 1tabs:
 2  type: tabs
 3  active: 1
 4
 5  fields:
 6    content:
 7      type: tab
 8      title: PLUGIN_ADMIN.CONTENT
 9
10      fields:
11
12        # .... other subfields
13
14    options:
15      type: tab
16      title: PLUGIN_ADMIN.OPTIONS
17
18      fields:
19
20        # .... other subfields

Tel Field

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

Example:

 1header.phone:
 2  type: tel
 3  label: 'Your Phone Number'

Text Field

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

Example:

 1header.title:
 2  type: text
 3  autofocus: true
 4  label: PLUGIN_ADMIN.TITLE
 5  minlength: 10
 6  maxlength: 255

Textarea Field

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

Example:

 1header.content:
 2  type: textarea
 3  autofocus: true
 4  label: PLUGIN_ADMIN.CONTENT
 5  minlength: 10
 6  maxlength: 255

Toggle Field

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

Example:

 1summary.enabled:
 2    type: toggle
 3    label: PLUGIN_ADMIN.ENABLED
 4    highlight: 1
 5    help: PLUGIN_ADMIN.ENABLED_HELP
 6    options:
 7        1: PLUGIN_ADMIN.YES
 8        0: PLUGIN_ADMIN.NO
 9    validate:
10        type: bool

Url Field

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

Example:

 1header.url:
 2  type: url
 3  label: 'Your Website Url'

Currently Undocumented Fields