` para mostrar errores de validación a nivel de campo. ```html ``` Si el elemento está vacío, Formspree inyecta el mensaje de error de la API. Si el elemento ya contiene contenido, ese contenido se muestra u oculta en su lugar. ### `data-fs-error` Úsalo sin un valor para mostrar errores a nivel de formulario. ```html

``` Esto es útil para errores generales de envío que no pertenecen a un campo específico. ### `data-fs-success` Úsalo para mostrar un mensaje de éxito después del envío. ```html

``` Si el elemento está vacío, se muestra el mensaje predeterminado. Si ya tiene contenido, se utiliza ese contenido en su lugar. ### `data-fs-field` Úsalo en los campos del formulario que deban recibir `aria-invalid="true"` cuando la validación falle. ```html ``` La biblioteca lee el nombre del campo desde el atributo `name` del elemento. ### `data-fs-submit-btn` Úsalo en el botón de envío para que se deshabilite durante el envío y se vuelva a habilitar después. ```html ``` ## Comportamiento predeterminado Si no anulas nada, la biblioteca proporciona valores predeterminados sensatos: - El botón de envío se deshabilita mientras se envía el formulario. - Los errores de campo se muestran dentro de los elementos `data-fs-error="fieldName"` correspondientes. - Los campos inválidos reciben `aria-invalid="true"`. - Se muestra un mensaje de éxito en el elemento `data-fs-success`. - Se muestra un mensaje de error a nivel de formulario en el elemento `data-fs-error`. - Si no hay un elemento `data-fs-success` ni un manejador `onSuccess` personalizado, el formulario se reemplaza con un mensaje "Thank you!". - Si hay un elemento `data-fs-success` y no hay un manejador `onSuccess` personalizado, el formulario se reinicia tras un envío exitoso. - Se inyectan estilos predeterminados básicos automáticamente. ## Configuración avanzada La biblioteca también ofrece formas de personalizar aún más el comportamiento y la apariencia de tu formulario. ### Añadir datos adicionales a cada envío Puedes usar la opción `data` para agregar valores adicionales a cada envío de formulario. Los valores pueden ser: - cadenas estáticas - funciones síncronas - funciones asíncronas Cualquier valor `undefined` se omite. Así es como se usa: ```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(), }, }); ``` Es útil para adjuntar metadatos como nombres de campañas, fuentes de referencia o IDs de sesión sin tener que añadir inputs ocultos a tu HTML. ### Callbacks del ciclo de vida Puedes engancharte a las distintas etapas del ciclo de vida del envío. ```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); }, }); ``` El objeto `context` contiene el formulario actual (`HTMLFormElement`), los detalles del endpoint, el cliente y el objeto de configuración que pasaste a `initForm`. Estos callbacks se pueden usar para: - Seguimiento de eventos (analítica, conversiones, abandonos) - Mostrar UI personalizada (spinners, toasts, banners) - Redirigir tras un envío exitoso - Registrar o depurar solicitudes y fallos - Manejo personalizado de errores de validación o a nivel de formulario - Ejecutar efectos secundarios antes o después del envío (por ejemplo, guardar estado, activar workflows) ### Renderizado personalizado Puedes anular el comportamiento predeterminado de la UI proporcionando métodos de renderizado personalizados en `initForm()`. Esto es útil si quieres tener control total sobre cómo aparecen los estados de carga, los errores y los mensajes de éxito. ```javascript initForm({ formElement: '#contact-form', formId: 'YOUR_FORM_ID', enable: (context) => {}, disable: (context) => {}, renderFieldErrors: (context, error) => {}, renderSuccess: (context, message) => {}, renderFormError: (context, message) => {}, }); ``` #### Métodos disponibles | Método | Cuándo se ejecuta | Usos comunes | | --- | --- | --- | | `disable(context)` | Cuando comienza el envío | Añadir estado de carga, deshabilitar botones/inputs | | `enable(context)` | Después de que el envío se completa | Eliminar spinners, volver a habilitar la UI | | `renderFieldErrors(context, error)` | En errores de validación | UI de error personalizada, errores agrupados, mensajes toast | | `renderSuccess(context, message)` | En envíos exitosos | Reemplazar el formulario, mostrar toast, redirigir | | `renderFormError(context, message)` | En errores a nivel de formulario | Banners de error, alertas, mensajería centralizada | Así es como se usan: ```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 = `

${message}

`; }, }); ``` ### Estilos La biblioteca incluye estilos predeterminados para errores, campos inválidos y mensajes de éxito. Puedes anularlos con tu propio 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; } ``` ### Limpieza `initForm()` devuelve un handle con un método `destroy()`. Puedes usarlo si necesitas limpiar el comportamiento del formulario más adelante. ```javascript const handle = initForm({ formElement: '#contact-form', formId: 'YOUR_FORM_ID', }); // Clean up when needed handle.destroy(); ``` ## Ejemplo completo en ESM Aquí tienes un ejemplo completo usando un formulario HTML simple y `@formspree/ajax` con un bundler. Primero, inicializa el formulario con tu ID de formulario de Formspree: ```javascript import { initForm } from '@formspree/ajax'; initForm({ formElement: '#contact-form', formId: 'YOUR_FORM_ID', }); ``` Luego, crea el formulario HTML con los atributos de datos descritos arriba: ```html

``` ## Ejemplo con etiqueta script Si quieres usar la biblioteca sin un paso de compilación, puedes inicializarla directamente en el navegador: ```html

``` ## Migrar desde código AJAX manual Si previamente has enviado formularios con código personalizado de `fetch`, Axios o jQuery, `@formspree/ajax` te ofrece una alternativa más simple. En lugar de hacer manualmente: - escuchar eventos de envío - serializar los datos del formulario - enviar solicitudes - analizar los errores de validación - actualizar el DOM para los estados de éxito y fallo Puedes inicializar la biblioteca una vez y dejar que se encargue de esas piezas por ti. ## Nota sobre frameworks Esta biblioteca está diseñada para JavaScript estándar y formularios HTML estándar. Si estás usando React, consulta [nuestra biblioteca de React](/es/articles/working-with-react/the-formspree-react-library/) en su lugar.