# Inviare moduli con JavaScript (AJAX)

> Formspree Docs · Creare il tuo modulo · 23 marzo 2026

#### Disponibile su: Tutti i piani

Puoi usare [`@formspree/ajax`](https://www.npmjs.com/package/@formspree/ajax)[](https://www.npmjs.com/package/@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:

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

E inizializza il tuo modulo in JavaScript:

```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>`:

```html
<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:

```html
<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.

```html
<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.

```html
<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.

```html
<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.

```html
<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.

```html
<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:

```javascript
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.

```javascript
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.

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

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

#### Metodi disponibili

  
| Metodo | Quando viene eseguito | Usi comuni |
| --- | --- | --- |
| `disable(context)` | Quando inizia l'invio | Aggiungere uno stato di caricamento, disabilitare pulsanti/input |
| `enable(context)` | Dopo il completamento dell'invio | Rimuovere gli spinner, riabilitare l'UI |
| `renderFieldErrors(context, error)` | In caso di errori di validazione | UI di errore personalizzata, errori raggruppati, messaggi toast |
| `renderSuccess(context, message)` | In caso di invio riuscito | Sostituire il modulo, mostrare un toast, reindirizzare |
| `renderFormError(context, message)` | In caso di errori a livello di modulo | Banner di errore, avvisi, messaggistica centralizzata |

Ecco come usarli:

```javascript
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.

```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.

```javascript
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:

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

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

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

```html
<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:

```html
<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](/articles/working-with-react/the-formspree-react-library/).