⌘I

Inviare moduli con JavaScript (AJAX)

Updated March 23, 2026 ·
howtoform-setup
Also available in:

Disponibile su: Tutti i piani

Puoi usare @formspree/ajax per inviare i tuoi moduli Formspree con JavaScript puro, senza scrivere la tua logica di invio con fetch, Axios o jQuery.

La libreria funziona con i moduli HTML standard e aggiunge una gestione dichiarativa del modulo tramite data attribute o una piccola API JavaScript. Gestisce automaticamente l’invio del modulo, lo stato di caricamento, gli errori di validazione e i messaggi di successo.

Come funziona

@formspree/ajax ti offre un modo dichiarativo per configurare un modulo. Invece di ascoltare manualmente gli eventi di submit e scrivere la tua gestione delle richieste, contrassegni il tuo modulo con data attribute e lo inizializzi con l’ID del tuo modulo Formspree.

Per impostazione predefinita, la libreria gestisce:

  • l’invio del modulo
  • lo stato di caricamento sul pulsante di invio
  • gli errori di validazione a livello di campo
  • gli errori a livello di modulo
  • i messaggi di successo
  • lo stato di campo non valido con aria-invalid="true"

Ecco come implementarla nel tuo progetto:

Passaggio 1: configura @formspree-ajax nel tuo progetto

Puoi usare @formspree/ajax in due modi, a seconda della tua configurazione:

  • Con un bundler (ESM tramite npm/yarn)
  • Senza un bundler (tag script/CDN)

Opzione 1: usare un bundler (ESM)

Installa la libreria:

npm install @formspree/ajax   # via npm, or
yarn add @formspree/ajax      # via yarn

E inizializza il tuo modulo in JavaScript:

import { initForm } from '@formspree/ajax';

initForm({
  formElement: '#contact-form',
  formId: 'YOUR_FORM_ID',
});

Assicurati che l’ID del tuo elemento modulo HTML corrisponda all’ID che passi nella proprietà formElement. E sostituisci YOUR_FORM_ID con l’ID del modulo che ricevi nella dashboard Formspree.

Opzione 2: usare un tag script (nessun passaggio di build)

Se non usi un bundler, aggiungi questo snippet prima del tag di chiusura </body>:

<script>
  window.formspree =
    window.formspree ||
    function () {
      (formspree.q = formspree.q || []).push(arguments);
    };
  formspree(
    'initForm', 
    { formElement: '#contact-form', formId: 'YOUR_FORM_ID' }
  );
</script>
<script src="https://unpkg.com/@formspree/ajax@1" defer></script>

Come per la prima opzione, assicurati che l’ID del tuo elemento modulo HTML corrisponda all’ID che passi nella proprietà formElement. E sostituisci YOUR_FORM_ID con l’ID del modulo che ricevi nella dashboard Formspree.

Passaggio 2: costruisci il tuo modulo

Una volta configurato @formspree/ajax nel tuo progetto, ecco come puoi creare un modulo con esso:

<div data-fs-success></div>
<div data-fs-error></div>

<form id="contact-form">
  <label for="email">Email</label>
  <input type="email" id="email" name="email" data-fs-field />
  <span data-fs-error="email"></span>

  <button type="submit" data-fs-submit-btn>Send</button>
</form>

Ancora una volta, assicurati che il valore nell’attributo id del tuo modulo corrisponda all’ID che hai passato come formId nella chiamata initForm nel passaggio precedente.

La libreria invierà automaticamente il modulo a Formspree, disabiliterà il pulsante di invio mentre la richiesta è in corso, mostrerà gli errori di validazione e visualizzerà un messaggio di successo.

Data attribute

La libreria @formspree-ajax include alcuni attributi che ti permettono di controllare il comportamento del modulo senza richiedere ulteriore JavaScript.

data-fs-error="fieldName"

Usalo su un elemento <span> o <div> per visualizzare gli errori di validazione a livello di campo.

<span data-fs-error="email"></span>

Se l’elemento è vuoto, Formspree inserisce il messaggio di errore dell’API. Se l’elemento contiene già del contenuto, quel contenuto viene mostrato o nascosto.

data-fs-error

Usalo senza un valore per visualizzare gli errori a livello di modulo.

<div data-fs-error></div>

È utile per gli errori di invio generali che non appartengono a un campo specifico.

data-fs-success

Usalo per mostrare un messaggio di successo dopo l’invio.

<div data-fs-success></div>

Se l’elemento è vuoto, viene mostrato il messaggio predefinito. Se contiene già del contenuto, viene usato quel contenuto.

data-fs-field

Usalo sui campi del modulo che dovrebbero ricevere aria-invalid="true" quando la validazione fallisce.

<input type="email" name="email" data-fs-field />

La libreria legge il nome del campo dall’attributo name dell’elemento.

data-fs-submit-btn

Usalo sul pulsante di invio, in modo che venga disabilitato durante l’invio e riabilitato successivamente.

<button type="submit" data-fs-submit-btn>Send</button>

Comportamento predefinito

Se non sovrascrivi nulla, la libreria fornisce impostazioni predefinite sensate:

  • Il pulsante di invio viene disabilitato mentre il modulo è in fase di invio.
  • Gli errori di campo vengono visualizzati all’interno degli elementi data-fs-error="fieldName" corrispondenti.
  • I campi non validi ricevono aria-invalid="true".
  • Un messaggio di successo viene mostrato nell’elemento data-fs-success.
  • Un messaggio di errore a livello di modulo viene mostrato nell’elemento data-fs-error.
  • Se non c’è un elemento data-fs-success e nessun handler onSuccess personalizzato, il modulo viene sostituito con un messaggio “Thank you!”.
  • Se c’è un elemento data-fs-success e nessun handler onSuccess personalizzato, il modulo viene reimpostato dopo un invio riuscito.
  • Gli stili predefiniti di base vengono iniettati automaticamente.

Configurazione avanzata

La libreria offre anche modi per personalizzare ulteriormente il comportamento e l’aspetto del tuo modulo.

Aggiungere dati extra a ogni invio

Puoi usare l’opzione data per aggiungere valori aggiuntivi a ogni invio del modulo. I valori possono essere:

  • stringhe statiche
  • funzioni sincrone
  • funzioni asincrone

Tutti i valori undefined vengono ignorati. Ecco come usarla:

initForm({
  formElement: '#my-form',
  formId: 'YOUR_FORM_ID',

  // This data will be added to every submission
  data: {
    source: 'landing-page',
    referrer: () => document.referrer || undefined,
    sessionId: async () => await fetchSessionId(),
  },
});

È utile per allegare metadati come nomi di campagne, fonti di referral o ID di sessione senza aggiungere input nascosti al tuo HTML.

Callback del ciclo di vita

Puoi agganciarti alle diverse fasi del ciclo di vita dell’invio.

initForm({
  formElement: '#contact-form',
  formId: 'YOUR_FORM_ID',

  // Called when the form is initialized
  onInit: (context) => {
    console.log('Form initialized');
  },

  // Called before submission is sent.
  onSubmit: (context) => {
    console.log('Submitting form');
  },

  // Called on successful submission.
  onSuccess: (context, result) => {
    console.log('Submission succeeded', result);
  },

  // Called if validation errors are received from Formspree
  onError: (context, error) => {
    console.log('Validation error', error);
  },

  // Called if unexpected errors are received (e.g., network failure).
  onFailure: (context, error) => {
    console.log('Unexpected error', error);
  },
});

L’oggetto context contiene il modulo corrente (HTMLFormElement), i dettagli dell’endpoint, il client e l’oggetto config che hai passato a initForm.

Questi callback possono essere usati per:

  • Tracciare eventi (analytics, conversioni, abbandoni)
  • Mostrare UI personalizzata (spinner, toast, banner)
  • Reindirizzare dopo un invio riuscito
  • Effettuare il logging o il debug di richieste e fallimenti
  • Gestire in modo personalizzato gli errori di validazione o a livello di modulo
  • Eseguire side effect prima o dopo l’invio (ad esempio, salvare lo stato, attivare workflow)

Rendering personalizzato

Puoi sovrascrivere il comportamento predefinito dell’UI fornendo metodi di rendering personalizzati in initForm(). È utile se vuoi il pieno controllo su come appaiono gli stati di caricamento, gli errori e i messaggi di successo.

initForm({
  formElement: '#contact-form',
  formId: 'YOUR_FORM_ID',

  enable: (context) => {},
  disable: (context) => {},
  renderFieldErrors: (context, error) => {},
  renderSuccess: (context, message) => {},
  renderFormError: (context, message) => {},
});

Metodi disponibili

MetodoQuando viene eseguitoUsi comuni
disable(context)Quando inizia l’invioAggiungere uno stato di caricamento, disabilitare pulsanti/input
enable(context)Dopo il completamento dell’invioRimuovere gli spinner, riabilitare l’UI
renderFieldErrors(context, error)In caso di errori di validazioneUI di errore personalizzata, errori raggruppati, messaggi toast
renderSuccess(context, message)In caso di invio riuscitoSostituire il modulo, mostrare un toast, reindirizzare
renderFormError(context, message)In caso di errori a livello di moduloBanner di errore, avvisi, messaggistica centralizzata

Ecco come usarli:

initForm({
  formElement: '#contact-form',
  formId: 'YOUR_FORM_ID',

  disable: ({ form }) => form.classList.add('loading'),
  enable: ({ form }) => form.classList.remove('loading'),

  renderSuccess: ({ form }, message) => {
    form.innerHTML = `<p>${message}</p>`;
  },
});

Stili

La libreria include stili predefiniti per errori, campi non validi e messaggi di successo. Puoi sovrascriverli con i tuoi CSS.

[data-fs-error] {
  color: #dc3455;
}

[data-fs-field][aria-invalid='true'] {
  border-color: #dc3455;
}

[data-fs-success][data-fs-active] {
  background: #de4dda;
}

[data-fs-error=''][data-fs-active] {
  background: #f87dda;
  color: #72c124;
}

Pulizia

initForm() restituisce un handle con un metodo destroy(). Puoi usarlo se hai bisogno di ripulire il comportamento del modulo in un secondo momento.

const handle = initForm({
  formElement: '#contact-form',
  formId: 'YOUR_FORM_ID',
});

// Clean up when needed
handle.destroy();

Esempio ESM completo

Ecco un esempio completo che usa un modulo HTML semplice e @formspree/ajax con un bundler. Per prima cosa, inizializza il modulo con l’ID del tuo modulo Formspree:

import { initForm } from '@formspree/ajax';

initForm({
  formElement: '#contact-form',
  formId: 'YOUR_FORM_ID',
});

Quindi crea il modulo HTML con i data attribute descritti sopra:

<div data-fs-success></div>
<div data-fs-error></div>

<form id="contact-form">
  <label for="email">Email</label>
  <input type="email" id="email" name="email" data-fs-field />
  <span data-fs-error="email"></span>

  <label for="message">Message</label>
  <textarea id="message" name="message" data-fs-field></textarea>
  <span data-fs-error="message"></span>

  <button type="submit" data-fs-submit-btn>Send</button>
</form>

Esempio con tag script

Se vuoi usare la libreria senza un passaggio di build, puoi inizializzarla direttamente nel browser:

<div data-fs-success></div>
<div data-fs-error></div>

<form id="my-form">
  <label for="email">Email</label>
  <input type="email" id="email" name="email" data-fs-field />
  <span data-fs-error="email"></span>

  <label for="message">Message</label>
  <textarea id="message" name="message" data-fs-field></textarea>
  <span data-fs-error="message"></span>

  <button type="submit" data-fs-submit-btn>Submit</button>
</form>

<script>
  window.formspree =
    window.formspree ||
    function () {
      (formspree.q = formspree.q || []).push(arguments);
    };

  formspree('initForm', {
    formElement: '#my-form',
    formId: 'YOUR_FORM_ID',
  });
</script>
<script src="https://unpkg.com/@formspree/ajax@1" defer></script>

Migrazione dal codice AJAX manuale

Se in precedenza hai inviato moduli con codice personalizzato fetch, Axios o jQuery, @formspree/ajax ti offre un’alternativa più semplice. Invece di farlo manualmente:

  • ascoltare gli eventi di submit
  • serializzare i dati del modulo
  • inviare le richieste
  • analizzare gli errori di validazione
  • aggiornare il DOM per gli stati di successo e fallimento

Puoi inizializzare la libreria una volta e lasciare che gestisca questi aspetti per te.

Nota sui framework

Questa libreria è progettata per JavaScript vanilla e moduli HTML standard. Se usi React, dai un’occhiata alla nostra libreria React.