Form Ajax

Progressively add Ajax support to <form> elements, and send data to APIs with just HTML.

• Display a message while the form is submitting or show a spinner.
• Display custom success and error messages or use API response data.
• Prevent multiple submissions while waiting for a response.
• Clear form fields after success or keep them filled in.
• Optionally include fields from other forms.
• Optionally remove the form after a successful submit.
• Optionally redirect the user after a successful submit.
• Optionally remove success messages after a short period of time.
• All status messages are announced to screen reader users, including submitting state.

Basic Usage

Wrap a <form> element in a <kelp-form-ajax> element.

It will use the form’s [action] and [method] attributes to submit the <form> data asynchronously, without a page reload. Form fields must have a [name] attribute to be included in the request.

Demo: Create a Post

<kelp-form-ajax>
	<form action="/path/to/endpoint" method="POST">
		<div>
			<label for="title">Post Title</label>
			<input type="text" name="title" id="title" required>
		</div>

		<div>
			<label for="body">Content</label>
			<textarea id="body" name="body" required></textarea>
		</div>

		<div>
			<button>Create Post</button>
		</div>
	</form>
</kelp-form-ajax>

Status Messages

The <kelp-form-ajax> component automatically displays status notifications using an ARIA live region, ensuring messages are announced to people who use screen readers.

Custom Messages

You can provide default messages when the form is submitting, succeeds, and fails using the [msg-*] attributes.

<kelp-form-ajax
	msg-submitting="Updating your contact info..."
	msg-success="Your contact info was updated!"
	msg-failed="Something went wrong. Please try again."
>
	<form action="/path/to/endpoint" method="POST">
		<!-- ... -->
	</form>
</kelp-form-ajax>

API Response Messages

If the API provides useful success or error messages, you can provide the path to those messages using the [path-on-*] attributes. Use the same path structure you would for a nested JavaScript array or object.

If the matching path is not found, the corresponding [msg-*] attribute will be used instead.

<kelp-form-ajax
	msg-submitting="Updating your contact info..."
	msg-success="Your contact info was updated!"
	path-on-success="user.details[0].message"
	msg-failed="Something went wrong. Please try again."
	path-on-success="error.message"
>
	<form action="/path/to/endpoint" method="POST">
		<!-- ... -->
	</form>
</kelp-form-ajax>

Styling Messages

Status messages receive a .submitting, .success, or .danger class. You can use the [msg-class] attribute to add one or more additional classes to the status message.

<kelp-form-ajax
	msg-class="callout"
>
	<form action="/path/to/endpoint" method="POST">
		<!-- ... -->
	</form>
</kelp-form-ajax>

You can also provide custom styles by targeting the kelp-form-ajax [role="status"] element (with the corresponding status classes as needed).

/**
 * Add color and italics to the status text
 */
@layer kelp.extend {
	kelp-form-ajax [role="status"] {
		--color: var(--color-outline);
		color: var(--color);
		font-style: italic;
	}
}

Submitting Spinner

If you include the [submit-loading] attribute, the <form> will be visually hidden, and a spinner component will be displayed in its place.

The status notification will still be included in the UI so that visually impaired users receive announcements about the form status, but will be .visually-hidden.

<kelp-form-ajax 
	submit-loading
>
	<form action="/path/to/endpoint" method="POST">
		<!-- ... -->
	</form>
</kelp-form-ajax>

To adjust the size or color of the spinner, use the desired classes as attribute values.

<kelp-form-ajax 
	submit-loading="warning size-5xl"
>
	<form action="/path/to/endpoint" method="POST">
		<!-- ... -->
	</form>
</kelp-form-ajax>

Redirect on Success

For some forms, you may want to redirect the user after the form successfully submits.

You can do that by including a [redirect-on-success] attribute, with the path of the URL to redirect to as its value.

<kelp-form-ajax 
	redirect-on-success="/dashboard"
>
	<form action="/login" method="POST">
		<!-- ... -->
	</form>
</kelp-form-ajax>

If the redirect URL is variable and returned by the API response, you can include the [path-redirect] attribute, with the path as its value. Use the same path structure you would for a nested JavaScript array or object.

If not found, the component will use the [redirect-on-success] URL as a fallback, if one is provided.

<kelp-form-ajax 
	redirect-on-success="/dashboard"
	path-redirect="details[0].redirect"
>
	<form action="/login" method="POST">
		<!-- ... -->
	</form>
</kelp-form-ajax>

Options

Use custom attributes to configure component settings.

Submitting

• [msg-submitting] - The message to display while submitting the form (default: Submitting...).
• [external-forms] - A selector string for any external forms to include in the form data.
• [submit-loading] - If present, display a spinner and hide the <form> while submitting. To adjust the spinner’s color or size, pass in the desired classes as values.

Success

• [msg-success] - The message to display after the form is successfully submitted (default: none).
• [path-success] - The path for the success message on the API response. If missing or not found, uses [msg-success] as a fallback.
• [keep-fields] - If present, field values are preserved after the form is successfully submitted.
• [delay] - The number of milliseconds to wait after a successful submit before re-enabling the form (default: 0, or 6000 if present).
• [remove-form-on-success] - If present, remove the form after it successfully submits.
• [dismiss-msg-on-success] - If present, automatically dismiss the success message after the provided number of milliseconds (default: 6000).
• [redirect-on-success] - A URL to redirect the user to after a successful submit.
• [path-to-redirect] - The path for a URL to redirect the user to on the API response. If missing or not found, uses [redirect-on-success] as a fallback.

Failure

• [msg-failed] - The message to display if the form fails to submit (default: Something went wrong. Unable to submit form.).
• [path-failed] - The path for the error message on the API response. If missing or not found, uses [msg-failed] as a fallback.

General Form Options

• [msg-class] - A list of classes to add to the status message container.
• [msg-start] - If present, status messages are displayed before the <form> instead of after.
• [event-keys] - A comma-separated list of unique identifiers to include in the event.detail object for custom events.

Events

The <kelp-form-ajax> element emits a few events.

• kelp-form-ajax:ready emits when the component is instantiated.
• kelp-form-ajax:submit emits before sending data to the endpoint, and is cancellable with event.preventDefault().
• kelp-form-ajax:success emits when the form successfully submits.
• kelp-form-ajax:failed emits when the form has an error.

The event.detail object includes either the FormData or error response object, and an array of eventKeys (or the form’s [action] attribute value if there are no [event-keys] provided).

document.addEventListener('kelp-form-ajax:ready', (event) => {
	console.log('ready:', event.target);
});

document.addEventListener('kelp-form-ajax:submit', (event) => {
	console.log('The form is about to submit:', event.detail);
	// Prevent it from submitting
	event.preventDefault();
});

document.addEventListener('kelp-form-ajax:success', (event) => {
	console.log('The form was successfully submitted.', event.detail);
});

document.addEventListener('kelp-form-ajax:failed', (event) => {
	console.log('The form failed to submit.', event.detail);
});