--- title: 'Reference: Form Actions' url: 'https://learn.getgrav.org/2/forms/forms/reference-form-actions' markdown: 'https://learn.getgrav.org/2/forms/forms/reference-form-actions.md' date: '2026-09-17' description: 'Reference: Form Actions Form actions We saw some example form actions in the simple form example above. Let''s detail the actions you can use. Email Sends an email with the specified options. Example: YAMLCopy 1process: 2 - email: 3 from: "{{ config.plugins.email.from }}" 4 to: "…' taxonomy: category: - docs --- # Reference: Form Actions ## Form actions We saw some example form actions in the simple form example above. Let's detail the actions you can use. ### Email Sends an email with the specified options. Example: YAML ``` 1process: 2 - email: 3 from: "{{ config.plugins.email.from }}" 4 to: "{{ config.plugins.email.to }}" 5 subject: "Contact by {{ form.value.name|e }}" 6 body: "{% include 'forms/data.html.twig' %}" ``` Sends an email from the email address specified in the Email plugin configuration, sends it to that same email address (it's a contact form, we send it to ourselves). Unless you want to use other values, you could freely omit from and to, as they are already configured by default to use these values. Caution If you have a "full" email address (e.g., `My Name `) stored in a file like site.yaml, and you are using Twig to refer to it, be sure to include the `|raw` filter (e.g., `{{ config.site.emails.sales|raw }}`. Otherwise, you will encounter "An email must have a 'To', 'Cc', or 'Bcc' header" errors. The email has the set subject and body. In this case, the body is generated by the `forms/data.html.twig` file, which is found in the active template (Antimatter and the other main themes have it, but it's not guaranteed that every theme includes it). Antimatter sets it to TWIG ``` 1{% for field in form.fields %} 2 <div><strong>{{ field.label }}strong>: {{ string(form.value(field.name)|e) }}div> 3{% endfor %} ``` In short, it just loops the values and prints them in the email body. Caution Refer to the email plugin documentation for additional [important form email options](https://github.com/getgrav/grav-plugin-email#emails-sent-with-forms) including [multipart message bodies](https://github.com/getgrav/grav-plugin-email#multi-part-mime-messages) (good for anti-spam scores), `reply_to`, and [attachments](https://github.com/getgrav/grav-plugin-email#sending-attachments). ##### Dynamic email attribute If you want for example to set the `email.from` field from a Form input, you can get its content and use it in this way: `from: "{{ form.value.email|e }}"` In this case, we get the field "email" from the form, and use it for the "from" attribute. This way the site owner will receive an email and will be able to directly reply to the email entered in the form. ### Redirect Redirects the user to another page. The action is immediate, so if you use this, you probably need to put it at the bottom of the actions list. YAML ``` 1process: 2 - redirect: '/forms/landing-page' ``` You may also set some or all of the `redirect` field from a form input or hidden form field. You can get its content and use it in this way: `redirect: "/path to/location/{{ form.value.hiddenfield }}"` In this case, we get the field "hiddenfield" from the form, and use it for the last portion of the redirect location. This can be useful when creating forms that, for example, redirect to a download upon completion. ### Message Sets a message to be shown upon form submission. YAML ``` 1process: 2 - message: Thank you for your feedback! ``` By default, the message will be rendered at the beginning of the `form` element. However, you can optionally modify the presentation either through `display` or through `redirect`. #### Validation Message You can utilize the message action to trigger in the event of a failed validation. For example: YAML ``` 1username: 2 type: text 3 label: Username 4 validate: 5 required: true 6 message: My custom message when validation fails! ``` This will enable you to write a custom message that users will see in the event that validation fails. ### Display After submitting the form, the presentation of the form will update to embed a subpage. So for example, if your form lives in `/form`, you can embed the subpage `/form/thankyou` with the following code: YAML ``` 1process: 2 - display: thankyou ``` If you prefer to embed an absolute page path, like `site.com/thankyou`, prepend it with `/`, for example: `display: /thankyou`. The Form plugin provides a `formdata` template that's suitable for the process destination page, as it outputs the result of the form submission. In the above example, you could create a `pages/form/thankyou/formdata.md` page. Antimatter and compatible themes provide the `formdata.html.twig` Twig template, that looks like this: TWIG ``` 1{% extends 'partials/base.html.twig' %} 2 3{% block content %} 4 5 {{ content|raw }} 6 7 <div class="alert">{{ form.message|e }}div> 8 <p>Here is the summary of what you wrote to us:p> 9 10 {% include "forms/data.html.twig" %} 11 12{% endblock %} ``` If the `thankyou/formdata.md` page is YAML ``` 1--- 2title: Email sent 3cache_enable: false 4process: 5 twig: true 6--- 7 8## Email sent! ``` The output will be a page with the "Email sent!" title, followed by a confirmation message and the form data entered in the previous page. You could use any page type you want, as a destination page. Just create your own and set the destination page type accordingly. ### Save Saves the form data to a file. The file is saved to the `user/data` folder, in a subfolder named as the `form.name` parameter. The form **must** have a name for this action to succeed, and the subfolder must be created with appropriate permissions before data can be saved in it, as a new directory will not be created if one does not exist. For example: Caution The `fileprefix` and `body` can contain Twig markup. YAML ``` 1process: 2 - save: 3 fileprefix: feedback- 4 dateformat: Ymd-His-u 5 extension: txt 6 body: "{% include 'forms/data.save.txt.twig' %}" 7 operation: create ``` Saved submissions may contain private data. Confirm that your web server blocks their URLs, including when nginx serves static files in front of Apache. If your host exposes `.txt` but blocks `.dat`, `extension: dat` is an interim option; test it with harmless data first. Extensions on `security.uploads_dangerous_extensions` are rejected, so changing to `yaml` or `json` may make the save action fail. See [User Folder Exposure](https://learn.getgrav.org/security/user-folder-exposure) for the server-side protections required. If you leave `body` out entirely, it defaults to `forms/data.save.txt.twig`. That template is provided by the Form plugin, and a theme can override it with its own `templates/forms/data.save.txt.twig`. Use it rather than `forms/data.txt.twig` for saved files: `forms/data.txt.twig` is HTML-escaped because it also gets included into HTML email bodies, which would store `Tom & Jerry` instead of `Tom & Jerry` in the saved file. Warning the `operation` can be either `create` (default) to create a new file per-form-submission or `add` to append to a single file. Warning note that the `add` operation now requires a static filename: to be defined see the example below. YAML ``` 1process: 2 - save: 3 filename: feedback.txt 4 body: "{% include 'forms/data.save.txt.twig' %}" 5 operation: add ``` ### Captcha To also validate the captcha server-side, add the captcha process action. YAML ``` 1process: 2 - captcha: 3 recaptcha_secret: ENTER_YOUR_CAPTCHA_SECRET_KEY ``` Caution The `recaptcha_secret` is optional and will use the Form plugin's configuration values if you have provided them there. ### User IP Address Display the user's IP address on the output. Put it above email / save processes in the 'form.md' to ensure it is used by the output processe(s). YAML ``` 1process: 2 - ip: 3 label: User IP Address ``` ### Timestamp Add a form submission timestamp to the output. Put it above email / save processes in the 'form.md' to ensure it is used by the output process(es). YAML ``` 1process: 2 - timestamp: 3 label: Submission Timestamp ``` ### Reset the form after submit By default, the form is not cleared after the submit. So if you don't have a `display` action and the user is sent back to the form page, it's still filled with the data entered. If you want to avoid this, add a `reset` action: YAML ``` process: - reset: true ``` ### Remember field values Using the `remember` action, you can allow your users to have *some* field values "recalled" from the last time a form was submitted. This is especially useful for forms which are submitted repeatedly, like an anonymous submission that requires information about the submitter. Warning [HTML5](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) and [Grav's Form plugin](https://learn.getgrav.org/2/forms/forms/fields-available#common-field-attributes) already provide this in limited ways through the browser, so do make use of this. However, you may find that autocomplete doesn't work reliably for some users and fields. Warning The `remember` action **uses cookies** to store the last value, so it will only work on the same device and browser where the browser is configured to allow them from your site. To use this action, simply list the names of the fields you would like to be remembered. For example, an online medical referral form is a good use case. These are typically completed from the same computer with some field values that rarely change and are boring to complete repeatedly. YAML ``` process: - remember: - referrer-name - referrer-address - referrer-specialty - preferred-practitioner ``` ## Custom Actions You can "hook" into a form processing and perform any kind of operation. Perform custom processing, add data for an online web application, even save to a database. To do this, in the form process field add your own processing action name, for example 'yourAction'. YAML ``` process: yourAction: true ``` Then, create a simple plugin. In its main PHP file, register for the event `onFormProcessed` PHP ``` 1namespace Grav\Plugin; 2use Grav\Common\Plugin; 3use RocketTheme\Toolbox\Event\Event; 4 5class EmailPlugin extends Plugin 6{ 7 public static function getSubscribedEvents() 8 { 9 return [ 10 'onFormProcessed' => ['onFormProcessed', 0] 11 ]; 12 } 13} ``` Then provide a handler for the saveToDatabase action: PHP ``` 1public function onFormProcessed(Event $event) 2{ 3 $form = $event['form']; 4 $action = $event['action']; 5 $params = $event['params']; 6 7 switch ($action) { 8 case 'yourAction': 9 //do what you want 10 } 11} ``` If your processing might go wrong and you want to stop the next form actions, which are executed in series, you can stop the processing by calling `stopPropagation` on the $event object: PHP ``` 1$event->stopPropagation(); 2return; ``` Sample code with form handling is available in the Form plugin, and in the Email plugin repositories. #### An example of custom form handling The Form plugin offers this ability of sending emails, saving files, setting status messages and it’s really handy. Sometimes however you need total control. That’s for example what the Login plugin does. It defines the `login.md` page frontmatter: YAML ``` 1title: Login 2template: form 3 4form: 5 name: login 6 7 fields: 8 - name: username 9 type: text 10 placeholder: Username 11 autofocus: true 12 13 - name: password 14 type: password 15 placeholder: Password ``` The Forms plugin correctly generates and shows the form. Notice there’s no `process` defined. The form `buttons` are missing too, since they’re manually added in `templates/login.html.twig`. That’s where the form `action` and `task` are defined too. In this case, `task` is `login.login`, and `action` is set to the page url. When a user presses 'Login' in the form, Grav calls the `onTask.login.login` event. `user/plugins/login/login.php` hooks up to `onTask.login.login` to its `classes/controller.php` file, and that's where the authentication happens. [ Edit this page on Github ](https://github.com/getgrav/grav-learn/edit/develop/pages/2/06.forms/02.forms/04.reference-form-actions/doc.md) © 2026 Grav Documentation. All rights reserved. --- ## Navigation - Parent: [Frontend Forms](https://learn.getgrav.org/2/forms/forms.md) - Previous: [Example: Contact Form](https://learn.getgrav.org/2/forms/forms/example-form.md) - Next: [How to: Forms in modular pages](https://learn.getgrav.org/2/forms/forms/how-to-forms-in-modular-pages.md)