Add formspree-ajax by lpssformspree · Pull Request #79 · formspree/formspree-js

lpssformspree · 2026-01-31T23:42:14Z

Summary

Add new @formspree/ajax package for vanilla JS/TS form submissions
Simplified API: formId + optional origin (replaces full endpoint URLs)
Lifecycle callbacks: onInit, onSubmit, onSuccess, onError, onFailure
Auto-disable/enable submit buttons during submission

Demo App

Vite-based example at examples/ajax-demo
Contact form with loading states and error handling
Uses environment variable for form ID configuration

API Example

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

initForm({
  formElement: '#contact-form',
  formId: 'your-form-id',
  onSuccess: ({ form }) => form.reset(),
  onError: (ctx, error) => console.log(error.getFormErrors()),
});

Test plan

Run yarn test in packages/formspree-ajax
Run demo with yarn dev in examples/ajax-demo
Submit form and verify success/error handling

New package for AJAX form submissions with @formspree/core as peer dependency. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add complete implementation of @formspree/ajax package, a recreation of statickit-html using @formspree/core as the base. Features: - Form initialization with FormConfig (formElement, formEndpoint, callbacks) - Lifecycle callbacks: onInit, onSubmit, onSuccess, onError, onFailure - Dynamic endpoint support (production, staging, custom) - Form context passed to all callbacks with form, formKey, endpoint, client - TypeScript types with JSDoc documentation - Submit button disable/enable during submission - Extra data support (static or function-based) - Debug logging support - Default success handler with "Thank you!" replacement - Form handle with destroy() method for cleanup Files added: - packages/formspree-ajax/src/form.ts: Core form handling logic - packages/formspree-ajax/src/types.ts: TypeScript types and interfaces - packages/formspree-ajax/test/form.test.ts: Unit tests - examples/ajax-demo/index.html: Interactive demo with endpoint configuration Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

- Replace formEndpoint with simpler formId + optional origin config - Add Vite-based demo app with contact form UI - Include loading states, error handling, and form validation feedback - Export appendExtraData from @formspree/core for extra form data Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vercel · 2026-01-31T23:42:19Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
formspree-react-demo	Ready	Preview, Comment	Feb 20, 2026 5:50pm

changeset-bot · 2026-01-31T23:42:20Z

🦋 Changeset detected

Latest commit: 694ef99

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@formspree/ajax	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Update vite (^5.0.0 → ^6.0.6) and tsup (^6.2.2 → ^8.4.0) to use patched esbuild versions (>=0.24.2) that fix the moderate severity vulnerability allowing any website to send requests to the dev server. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Implements missing features from statickit-html: - renderErrors: auto-populate data-fs-error elements with error messages - fields config: custom prettyName and errorMessages per field - Customizable enable/disable/renderErrors functions Updates ajax-demo example to demonstrate the new features with inline error display and custom error messages. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add DataAttributes constant with ERROR, FIELD, and SUBMIT_BTN - data-fs-error: displays validation error messages for fields - data-fs-field: sets aria-invalid="true" on inputs with errors - data-fs-submit-btn: auto-disable buttons during form submission - Update ajax-demo to use new data attributes and remove HTML required Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Removed static error styles from index.html - Added a function to inject default error styles into the document head on form initialization - Ensured styles are only injected once per page load This change enhances the flexibility of styling error messages in forms.

Move message rendering logic (success/error) from the demo into the package as default behavior, following the existing renderErrors pattern. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Simplify global API to accept a single config object instead of formspree('form', 'init', config) dispatch pattern - Add data-fs-message for declarative form-level success/error messages - Add renderMessage callback and defaultRenderMessage implementation - Inject default styles for data-fs-error, data-fs-field, and data-fs-message - Update demos to use Formspree brand colors and simplified API - Update tests for new global API signature Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- Simplified error message handling by removing custom error messages and pretty names from the fields configuration. - Updated error rendering to display only form-level errors, with inline field errors shown via data attributes. - Removed unused types and interfaces related to error messages and field configurations from the codebase. - Adjusted tests to reflect changes in error message expectations. This refactor streamlines the form error handling process and reduces complexity in the configuration options.

… spinner functionality - Added new data-fs-field attribute to input elements for better error handling. - Removed unused loading spinner styles and integrated a new spinner implementation in the form submission process. - Updated form submission logic to disable buttons and show a spinner during submission. - Enhanced tests to verify spinner visibility and aria-invalid attribute handling for form fields. These changes streamline the user experience during form submissions and improve accessibility features.

- Updated README to correct spelling of "JavaScript" and reorganize package information. - Introduced `@formspree/ajax` package with installation instructions and usage examples for vanilla JavaScript form handling. - Improved extra data handling in form submissions to support both synchronous and asynchronous functions. - Enhanced tests to validate the inclusion of static and dynamic extra data in submissions, as well as message rendering for success and error states. These changes improve documentation clarity and expand the functionality of the AJAX library for better user experience.

…nsistency - Renamed `renderErrors` to `renderFieldErrors` and `renderMessage` to `renderFormMessage` for better clarity in their purposes. - Updated the form submission logic to utilize the new rendering functions, ensuring field-level and form-level errors are handled appropriately. - Enhanced documentation in the README and types to reflect the changes in error handling and rendering functions. - Adjusted tests to verify the new rendering behavior and ensure proper functionality. These changes improve the readability and maintainability of the error handling process in the AJAX library.

- Replaced `data-fs-message` with `data-fs-success` and `data-fs-error` attributes for clearer distinction between success and error messages. - Updated HTML examples in the demo to reflect the new message handling attributes. - Refactored rendering functions to manage visibility and content of success and error messages more effectively. - Enhanced documentation in the README to clarify the usage of new attributes and their behavior. - Adjusted tests to verify the correct rendering of success and error messages based on the new implementation. These changes improve the user experience by providing clearer feedback during form submissions.

… functionality

Copilot

Pull request overview

This PR introduces a new @formspree/ajax package for vanilla JavaScript/TypeScript form submissions without requiring a framework. The implementation provides both ESM/CJS module support and a global script tag API, with declarative HTML data attributes for error handling and form state management.

Changes:

Added new @formspree/ajax package with lifecycle callbacks (onInit, onSubmit, onSuccess, onError, onFailure)
Created Vite-based demo application showcasing both ESM and script tag usage patterns
Updated turbo.json from deprecated "pipeline" to "tasks" configuration

Reviewed changes

Copilot reviewed 38 out of 40 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
turbo.json	Updated Turborepo configuration to use "tasks" instead of deprecated "pipeline"
packages/formspree-ajax/*	New package implementation including types, form handling, utilities, and test suites
examples/ajax-demo/*	Demo application with contact form examples using both ESM and global script approaches
package.json	Updated tsup to v8.4.0 and added packageManager field
README.md	Documentation updates for new ajax package and installation instructions

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

… compatibility

…y in task management

examples/ajax-demo/public/global.html

packages/formspree-ajax/src/form.ts

examples/ajax-demo/public/global.html

packages/formspree-ajax/src/run.ts

packages/formspree-ajax/LICENSE

packages/formspree-ajax/package.json

packages/formspree-ajax/README.md

README.md

- Add command dispatch to global API: formspree('initForm', config) - Split renderFormMessage into renderSuccess and renderFormError - Rename demo files: index-packages.html and index-cdn.html - Extract shared CSS into styles.css - Update placeholder messages to realistic copy - Keep form HTML consistent between both demos - Add Larissa Oliveira to contributors - Fix install instructions (core is a transitive dep) - Replace real form ID with YOUR_FORM_ID in CDN demo Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

packages/formspree-ajax/src/form.ts

packages/formspree-ajax/src/global.ts

Move disable/clear calls before async data resolution to prevent duplicate submissions when ExtraData contains async functions. Add per-form submitting guard to block concurrent handleSubmit calls. Wrap queue flush loop in try-catch so one failing form doesn't prevent remaining forms from initializing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

colevscode · 2026-02-20T05:15:22Z

README.md

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


is there any way to make this cleaner? This is a pretty ugly script URL. Ideally it would be something like https://unpkg.com/@formspree/ajax@1.0.0

we might be able to.. I'll check on that

@colevscode Turns out the "unpkg" field in package.json already points to dist/global.js, so unpkg resolves it automatically. I’ve updated all references to use the shorter https://unpkg.com/@formspree/ajax@1 — so no explicit path needed.

colevscode

This is pretty much good to go. I want to look at how/where it's packaged (what file path) and also need to update NPM permissions

colevscode · 2026-02-20T05:22:08Z

@krharsh17 please review this. We're likely want to write up some tutorials and replace some of our example ajax code with this library

The "unpkg" field in package.json already points to dist/global.js, so the explicit path is unnecessary. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

lpssformspree and others added 3 commits January 31, 2026 18:48

Add @formspree/ajax package

f770476

New package for AJAX form submissions with @formspree/core as peer dependency. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Refactor form initialization to use formId instead of formEndpoint

501bd59

vercel bot had a problem deploying to Preview January 31, 2026 23:51 Failure

vercel bot had a problem deploying to Preview February 2, 2026 22:15 Failure

Add changeset for @formspree/ajax package

aca9c24

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vercel bot had a problem deploying to Preview February 3, 2026 00:02 Failure

vercel bot deployed to Preview February 4, 2026 23:21 View deployment

vercel bot deployed to Preview February 5, 2026 00:27 View deployment

vercel bot deployed to Preview February 5, 2026 00:47 View deployment

lpssformspree and others added 2 commits February 7, 2026 17:33

Add data-fs-message for declarative form-level message display

f4f32c1

Move message rendering logic (success/error) from the demo into the package as default behavior, following the existing renderErrors pattern. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Enhance AJAX demo with global script tag support

c598308

vercel bot deployed to Preview February 8, 2026 00:42 View deployment

vercel bot deployed to Preview February 10, 2026 23:30 View deployment

lpssformspree added 2 commits February 10, 2026 21:01

vercel bot deployed to Preview February 11, 2026 00:31 View deployment

vercel bot deployed to Preview February 11, 2026 20:40 View deployment

vercel bot deployed to Preview February 11, 2026 21:20 View deployment

remove spinner styles

d52a635

vercel bot deployed to Preview February 11, 2026 23:19 View deployment

Enhance form configuration to support project ID

3061d5c

vercel bot deployed to Preview February 11, 2026 23:30 View deployment

Refactor form handling and utility functions for improved clarity and…

43a7d7e

… functionality

vercel bot deployed to Preview February 11, 2026 23:56 View deployment

lpssformspree requested a review from Copilot February 11, 2026 23:59

Copilot AI reviewed Feb 11, 2026

View reviewed changes

Remove ARCHITECTURE.md

ed4d954

vercel bot deployed to Preview February 12, 2026 00:02 View deployment

Update package dependencies and downgrade tsup version to 6.2.2 for…

b7478e8

… compatibility

vercel bot deployed to Preview February 12, 2026 19:50 View deployment

revert tubo

604304f

vercel bot had a problem deploying to Preview February 12, 2026 19:51 Failure

Update turbo.json to rename 'pipeline' to 'tasks' for improved clarit…

291e86f

…y in task management

vercel bot deployed to Preview February 12, 2026 19:58 View deployment

colevscode requested changes Feb 17, 2026

View reviewed changes

vercel bot deployed to Preview February 18, 2026 22:22 View deployment

lpssformspree commented Feb 18, 2026

View reviewed changes

packages/formspree-ajax/src/form.ts Outdated Show resolved Hide resolved

lpssformspree commented Feb 18, 2026

View reviewed changes

packages/formspree-ajax/src/global.ts Outdated Show resolved Hide resolved

vercel bot deployed to Preview February 18, 2026 23:18 View deployment

update license

a835837

vercel bot deployed to Preview February 19, 2026 00:03 View deployment

colevscode reviewed Feb 20, 2026

View reviewed changes

Shorten unpkg CDN URLs to use package-level resolution

694ef99

The "unpkg" field in package.json already points to dist/global.js, so the explicit path is unnecessary. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

vercel bot deployed to Preview February 20, 2026 17:50 View deployment

Comments

Conversation

lpssformspree commented Jan 31, 2026

Summary

Demo App

API Example

Test plan

Uh oh!

vercel bot commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Jan 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

colevscode Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

lpssformspree Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

lpssformspree Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

colevscode left a comment

Choose a reason for hiding this comment

Uh oh!

colevscode commented Feb 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel bot commented Jan 31, 2026 •

edited

Loading

changeset-bot bot commented Jan 31, 2026 •

edited

Loading