Calculations

If you are coming from Ninja Forms 2.9 and used calculations there, please see the note below before moving on in this documentation.

Special note for existing 2.9 users on how calculations have changed in version 3.0

Calculations in Ninja Forms 3.0 differ drastically from 2.9 in ways that make them far superior.  A few key differences if you’re coming from 2.9:

  • Calculations are NOT tied to fields any longer.  “Calculation” fields no longer exist.
  • Calculations do not need to be displayed to the user at all…they can be used invisibly for processing actions conditionally and more
  • “Total” fields in 3.0 have NOTHING to do with manual calculations…they are an automatic total of our new commerce fields.  See here for how Total fields work in 3.0 (and more about our new commerce fields).

Consider calculations in 3.0 learning a new thing.  Forget what you knew in 2.9 as much as possible, and follow the guide below with a fresh mind, making no assumptions about how things should work based on your knowledge of 2.9.

Please also note that individual calculations are NOT supported by our support team per our scope of support.  If you find an easily reproducible bug, please let us know and we will look into it.  Do not ask us to troubleshoot your calculations setup.  Calculations are powerful, but are at your own risk.

Creating a Calculation

Creating a calculation in Ninja Forms has two primary steps:

  1. Creating the fields on which to base the calculation
  2. Creating the calculation itself

Any field that can accept a fully numeric input can be used to base a calculation on.  Alternatively, any fields with a “Calc Value” in them can also be used in calculations.  We strongly recommend NOT mixing commerce fields with calculations but rather opting fully for one solution over the other.

Learn about 'Calc Value' vs 'Value' in Certain Field Settings

The “Calc Value” of a field is different from it’s “Value.”  A fields “Value” is what is passed into the final form submission.  The “Calc Value” is what is used when that field is called from a calculation.

In the screenshot above is an example of a list field’s settings.

  • Label – Labels appear to your user on the front end of your form as a choice in the list
  • Value – Separate from the label.  This will appear in the saved form submission as the users choice, as well as appearing in email, success message, or redirect actions as the submitted data.
  • Calc – This is Ninja Forms specific.  This value will be sent (or totaled and then sent in a multi-select list) to any calculations referencing this field.

Using the screenshot above as a template, if the user selected both “User’s First Choice” and “User’s Second Choice” on the front end, the saved form data would read “Submitted Data 1” and “Submitted Data 2” respectively.  The calc value for the field would be 3 (1 + 2, the sum of the two choice’s calc values).

Single checkboxes also have the “Calc Value” setting.

Once you have added fields to use in your calculation, creating the calculation itself is very simple.

In the form builder, go to “Advanced” and then to “Calculations”:

Click “Add New” to add a calculation to your form:

Name your calculation.  You will use this name to reference the calculation in other places, including displaying the value in the form itself or in any actions.
Note: Only Alpha-numeric characters are able to be used in the Calculation name.

Now, create the calculation.  Using the “Merge Tags” icon in the “Equation” text area, choose the fields that you would like to use in your calculation.  In the example below, I’ve added the list field from our example above as well as a number field.  You may multiply (*), divide (/), add (+), or subtract (-) any two fields.  Order of operations is honored, including the use of parenthesis.  In our example, however, I am simply adding the two fields together.

You’ll notice that the merge tags in calculation fields add “:calc”, a convention only seen here.  This is to let the calculation know to use the “Calc Value” of a field if it exists instead of the normal, submitted “Value.”  In the absence of a “Calc Value”, the submitted “Value” will be used instead.

Displaying the Calculation in Your Form

Displaying a calculation in your form is very easy!  In the form builder, add an HTML field to your form from the “Layout Fields” section:

Once added, open the HTML field settings and choose the merge tag that matches your calculation name:

This will add a merge tag to your form beginning with “calc:”, indicating that a calculated value will appear in this location.

That’s it!  Preview the form on the front end and you will see your total being displayed.  You are free to add a currency symbol, styling, or any other content to the display of your total.  It will update dynamically as the form is completed.  For example, changing the HTML field to

Total: ${calc:my_first_calculation}

will display in your form like this:

Sending a Calculation to Stripe or PayPal

Sending a calculated value works exactly the same way as in the Stripe documentation and PayPal Express documentation, respectively.

The only difference is instead of using the “Total” field as specified in those documents, you will use the “Calculation” merge tags in the same manner we displayed the calculation above:

That’s it!  Your calculated value is what will be passed to the payment gateway.  There is no need to display the value in the form, use “Total” fields, or any other steps required.

Advanced Calculation Tips

  • Calculations can nest.  Any new calculation you add can use any other calculation above it in the list (but never below it).  This can allow for some pretty amazing and powerful use cases.
  • Calculations can be used to fire actions conditionally with our Conditional Logic addon.  This means that based on a user’s answers to questions in your survey, quote request form, etc. that you can send them to different landing pages, contact different members of your sales team, gauge how “hot” your lead is, and more…all in Ninja Forms!

 

How helpful was this documentation?

Gold Star Green Light Yellow Light Red Light
Very helpful Helpful Unclear/Unhelpful Not helpful at all