API Reference

Installation

npm install formtress-js

Current version: 0.2.1

submitForm(options)

Submits form data to the Formtress endpoint.

import { submitForm } from 'formtress-js'

const result = await submitForm({
  url: 'https://app.formtress.com/api/f/your-form-id',
  data: new FormData(formElement),
})

Parameters

Name	Type	Required	Description
options	object	Yes	Submission options.
options.url	string	Yes	The form’s submit URL (https://app.formtress.com/api/f/your-form-id). Typically read from form.action.
options.data	FormData	Yes	A FormData instance containing the fields to submit.

Return value

Returns Promise<SubmitResult>.

interface SubmitResult {
  ok: boolean
  message?: string
  status?: number
}

Field	Type	Description
ok	boolean	true if the submission was accepted and passed validation.
message	string | undefined	Error message from the server. Only present when ok is false.
status	number | undefined	HTTP status code from the server.

Webflow script

The Webflow script progressively enhances standard HTML forms that submit directly to Formtress. Forms work without JavaScript — the script adds Webflow’s native success/error states and loading text support.

CDN URL

https://cdn.jsdelivr.net/npm/formtress-js@0.2.1/dist/js/webflow.js

Behavior

1. On DOMContentLoaded, finds all <form> elements whose action points to the Formtress submit endpoint.
2. Attaches a submit handler to each form.
3. Intercepts and prevents the default form submission.
4. Collects form data and sends it to the form’s action URL via fetch.
5. On success: triggers Webflow’s native success state.
6. On error: triggers Webflow’s error state and updates any data-ft-error element.
7. Without the script: the form submits normally via standard HTML — spam protection still runs server-side.

Pinning a version

Always pin to a specific version in production:

<script src="https://cdn.jsdelivr.net/npm/formtress-js@0.2.1/dist/js/webflow.js"></script>

To get the latest version automatically (not recommended for production):

<script src="https://cdn.jsdelivr.net/npm/formtress-js@latest/dist/js/webflow.js"></script>