Skip to main content

Success Return URL on Forms

Freeform offers a wide variety of ways to handle the success return on forms. Check out the list below to see all available options and how to use them.

​Available Options

If you wish to offer flexibility and control to your clients for setting the Return URL, this can be set inside the form builder for each form.

1

Open up the form inside the form builder.

2

Go to the Settings tab.

3

For the Success Behavior setting, select Return the Submitter to the following URL.

4

Inside the Return URL setting, add the path you want Freeform to return the user to upon success.

You can also use the following (wrap with {{ and }}):

  • form.handle - handle of the form.
  • submission.token - the secure token created for the submission.
  • submission.id - the newly created unique submission ID in the URL. This (and submission.token) would allow you to use the Submissions query to display some or all of the users' submission on the success page.

​EXAMPLE

​IMPORTANT NOTES

  • This approach can easily be overwritten by any template parameters. As soon as the template level returnUrl parameter is specified, Freeform will ignore the value set inside the form builder.
  • This approach will not immediately work with AJAX. When AJAX is enabled, Freeform will by default stay on the same page and just show a success banner. To have Freeform perform a redirect to the return URL specified in the form builder upon successful AJAX submit, you'll need to add some JS to your page template. See example below:
<html>
<head>
</head>
<body>

    {{ freeform.form("myFormHandle", {id: 'my-form'}).render() }}

    <script>
      // Find the form element
      const myForm = document.getElementById('my-form');
      // Do something on a successful ajax submit
      myForm.addEventListener('freeform-ajax-success', function(event) {
        // Redirect the user
        if (event.response.finished) {
          window.location.href = event.response.returnUrl;
        }
      })
      myForm.addEventListener("freeform-render-success", function (event) {
      // Stop the default success message rendering
        event.preventDefault();
      });
    </script>

</body>
</html>

​Advanced Options

​Returning Submit to Same Page

Aside from the obvious of using AJAX, you can achieve this by...

Adding a simple query in the success URL instead of an additional segment, e.g. /contact?success:

{% set successParam = craft.app.request.getParam('success') %}
{% if successParam is not null %}
  <p>Success!!</p>
{% endif %}

​Forcing a different Success URL on AJAX forms

Once using AJAX with your forms, Freeform will ignore any Return URL value you have set for the form inside the form builder as well as the returnUrl parameter. Only once you add some additional JS overrides using Freeform's Javascript handling will it begin to work that way:

<html>
<head>
</head>
<body>

    {{ freeform.form("myFormHandle", {
        returnUrl: "contact/success",
        id: 'my-form'
    }).render() }}

    <script>
        // Find the form element
        const myForm = document.getElementById('my-form');
        // Do something on a successful ajax submit
        myForm.addEventListener('freeform-ajax-success', function(event) {
          // Redirect the user
          window.location.href = event.response.returnUrl;
        })
    </script>

</body>
</html>

​Customizing the AJAX Success Message

The built-in AJAX functionality lets you completely customize the way your forms work if you're not satisfied with anything in the provided defaults. If you only need to customize the error messages, you can do so by overriding the defaults like this:

<html>
<head>
</head>
<body>

    {{ freeform.form("myFormHandle", {
        returnUrl: "contact/success",
        id: 'my-form'
    }).render() }}

    <script>
        // Change success and error messages for all forms on this page
        document.addEventListener('freeform-ready', function(event) {
            // Customize the error and success messages
            event.options.successBannerMessage = 'My custom success message';
            event.options.errorBannerMessage = 'My custom error message';
        });
    </script>

</body>
</html>

​Display alternate Success markup from a Template or Existing Div after AJAX Submit

When using the Freeform built-in AJAX feature, if you wish to override the default AJAX success message and instead load alternate success markup from a template or existing div, follow the instructions below:

1

Create a new form or edit an existing one as usual. Be sure to check off the Enable AJAX checkbox inside the form settings area in the form builder.

2

Add a div to hold the success contents inside your existing template that contains the form, e.g. custom-content:

<div id="custom-content">
    <h3>Thank you!</h3>
    <p>
        We have received your submission. You may now
        <a href="{{ siteUrl('path-to/file.pdf') }}">download the PDF guide</a>.
    </p>
</div>
3

Wrap your existing form render with a div to make it easier to swap out with the custom success div, e.g. form-wrapper:

<div id="form-wrapper">
    {{ freeform.form('myContactForm').render }}
</div>
4

In the footer of the template that will contain the form, be sure to include something like this in the footer area:

<script src="https://code.jquery.com/jquery-3.5.1.js"></script>
<script type="text/javascript">
    document.addEventListener('freeform-render-success', function (event) {
        // Disable the default success rendering
        event.preventDefault();
        // We locate the 'form-wrapper' DIV element which contains our form
        // and we swap its contents (the whole form) with the HTML that we
        // fetch from any other element already present on the page
        $('#form-wrapper').html($('#custom-content').html());
    });
</script>

​User Chooses Return URL

If you wish to have the return URL based upon the user's form selection, etc, you can override the return URL manually with a hidden field or checkbox, etc named formReturnUrl, allowing for a more dynamic return URL dependent on the user's choice or action, as long as you hash the value.

Some examples of this might be:

  • Having the form return to a different page if Field X contains Y.
  • Providing a single checkbox that, when checked, returns them to a different URL.
  • Providing a series of options in a radio or select field that contain different return values.

Please keep in mind that if you're wanting to make the return path dependent on another field selection, or if you wish to know which "return option" the user chose, using the formReturnUrl field does NOT collect and store the data selection. In this case, you would be best to use a real Freeform field to collect the data, and then implement your own custom JS that calculates and/or copies another field's option values and inserts a return URL into the formReturnUrl hidden field accordingly.

If you're using an automated rendering of the form, you'll need to consider how and where to add this into the formatting template. In most cases it might be best to add a conditional and pair this with the submit button or another field.

​EXAMPLES

Below are some examples of how this could be applied:

<input type="hidden" name="formReturnUrl" value="{{ 'whatever/my-url'|hash }}" />
Page Feedback